AGENTS.md for Factory Droid: Complete Setup and Configuration Guide (2026)

Factory’s Droid CLI reads AGENTS.md automatically — no flag, no config toggle. What trips people up isn’t getting Droid to read the file; it’s writing one that actually changes what Droid does, installing the CLI correctly in the first place, and confirming the instructions made it into context before you trust Droid with real work. This guide covers all three, plus a piece almost nobody documents: getting AGENTS.md working inside droid exec, Factory’s headless mode for CI.

If you specifically want the internals of how Droid’s discovery and override logic work — which of six candidate folders it checks, and what happens when a nested file conflicts with the root one — we cover that separately in how Factory Droid CLI discovers AGENTS.md. This guide is the practical companion: install, write, verify, automate.

Installing Droid CLI

Droid ships three install paths, and which one you want depends on your OS and whether you’d rather manage it through a package manager you already use.

macOS / Linux (official installer):

curl -fsSL https://app.factory.ai/cli | sh

Factory’s own quickstart quotes this as a sub-two-minute install. On Linux, you need xdg-utils present for the browser-based sign-in step to work — install it first if it isn’t already there:

sudo apt-get install xdg-utils

Any OS with Node installed (npm):

npm install -g droid

Useful if you want Droid version-pinned alongside other Node-based CLI tools, or if you’re on a machine where you’d rather not run a piped shell script. Pin an exact version the same way you would any global npm package:

npm install -g droid@0.174.0

Windows (PowerShell):

irm https://app.factory.ai/cli/windows | iex

First run

cd /path/to/your/project
droid

Droid opens a full-screen terminal UI showing mode, autonomy level, MCP status, and a prompt composer. If this is your first run, it prompts you to sign in through your browser to connect to Factory’s backend — there’s no separate droid login step to remember, it happens inline the first time you need it.

“droid: command not found” after install? This is almost always a PATH issue, not a failed install. The npm method puts the binary in your npm global bin directory, which isn’t always on PATH by default — add it to your shell config (.zshrc, .bashrc, or the fish equivalent) and restart your shell. On Windows, if you hit a permission error during install, either run PowerShell as Administrator or point npm at a user-writable prefix: npm config set prefix %APPDATA%\npm.

Writing Your First AGENTS.md

Factory’s own guidance is deliberately sequenced — do these in order, not all at once:

1. Start with one file at the repo root. Don’t pre-emptively create a nested file for every package. Add AGENTS.md at the root first, and only fork off nested files later, once you actually hit a directory that needs different rules than the rest of the project.

2. Commands come before conventions. Droid can’t verify its own work without knowing how to build, test, and lint your project. This is the section that pays off fastest — write it before anything else:

## Commands

- Install: `pnpm install`
- Dev server: `pnpm dev`
- Test: `pnpm test`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- Build: `pnpm build`

3. Add the guardrails, not just the happy path. Factory’s docs are specific about what belongs here: repository layout, generated-file handling, security boundaries, ownership boundaries, and — this is the part teams skip — what proof Droid needs to produce before it’s allowed to call a task done.

4. Commit it. AGENTS.md is a project file, not a personal dotfile. If it only exists on your machine, every teammate’s Droid session and every CI run using droid exec operates with less context than yours does.

A filled-in example

Here’s what that looks like assembled, for a TypeScript API service:

# AGENTS.md

## Project Overview
REST API for order management. Express + TypeScript, PostgreSQL via Prisma.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 4000)
- Test: `pnpm test`
- Type check: `pnpm typecheck`
- Lint: `pnpm lint`
- DB migrate: `pnpm prisma migrate dev`

## Repository Map
src/routes/       # Route handlers only — no business logic here
src/services/     # Business logic, called from routes
src/repositories/ # All Prisma queries live here, nowhere else
tests/            # Mirrors src/ structure

## Conventions
- No `any` types — TypeScript strict mode is on
- Errors: return `Result<T, E>`, never throw across module boundaries
- Env vars: access only through src/config.ts, never process.env directly

## Generated Files
prisma/generated/ is regenerated by `pnpm prisma generate` — never hand-edit it.

## Verification
Before calling any task finished, run and confirm passing:
1. `pnpm test`
2. `pnpm typecheck`
3. `pnpm lint`

## Security Rules
Never read or print .env, .env.local, or anything under secrets/.
Do not commit migration files without running them locally first.

Notice what’s absent: no prose about “writing clean code,” no changelog of past decisions, no full copy of the README. Factory’s guidance explicitly calls out long inventories and duplicated documentation as things that consume budget without changing agent behavior.

Nested files, briefly

If a subdirectory needs different commands or conventions — a mobile/ package using React Native inside an otherwise-web monorepo, for instance — drop a second AGENTS.md in that directory. Droid applies the more specific file for work scoped to that subtree. The full precedence rules, including how Droid resolves conflicts between root, nested, and personal-level files, are covered in the discovery mechanics guide — worth reading before you go past two or three nested files, since the override behavior (replace, not merge) surprises people coming from tools that concatenate everything.

Migrating From CLAUDE.md

If your repo already has a CLAUDE.md for Claude Code, you don’t need to duplicate it. Droid’s compatible filename list includes CLAUDE.md and Claude.md alongside AGENTS.md, agents.md, and Agents.md. Factory’s stated recommendation is AGENTS.md for new projects, but an existing CLAUDE.md works as-is — provided the content doesn’t lean on Claude Code-specific syntax like @file import references, which Droid’s docs don’t confirm it resolves.

For a team running both tools against the same repo, that means one file, not two — until the content diverges enough that it’s worth splitting.

Verifying Droid Actually Loaded Your Instructions

Writing AGENTS.md and confirming Droid used it are two different steps, and skipping the second one is how teams end up debugging phantom “why didn’t it follow my rules” issues that are actually just a file in the wrong place.

The fastest check: ask Droid directly, in a fresh session, before you give it any real task.

> What repository instructions do you currently have loaded, and where did they come from?

A working setup answers specifically — naming your commands section, your conventions, your file paths. A vague or generic answer (“I’ll follow standard best practices”) means Droid isn’t seeing your AGENTS.md at all. At that point, check the basics in order: is the file actually named correctly (case matters — Agents.MD is not AGENTS.md), is it committed rather than sitting in .gitignore, and are you running droid from inside the git repository rather than a parent or sibling directory outside it?

The other thing worth checking once you have a working file: length. Droid enforces an 80,000-character budget on the initial load and a smaller 40,000-character budget for files discovered dynamically as it reads into subdirectories mid-session. A root AGENTS.md that’s approaching either ceiling is usually a sign it’s carrying content that belongs in a nested file instead — Factory’s own guidance is blunt that smaller files perform better than one file trying to cover everything.

Using AGENTS.md With droid exec in CI

This is the part most AGENTS.md coverage skips entirely: Droid isn’t only the interactive terminal app. droid exec is Factory’s headless mode — a one-shot, non-interactive run that reads and writes stdout/stderr, built for CI pipelines, cron jobs, and scripted automation. It reads the same AGENTS.md your interactive sessions do, which means the commands and safety rules you write once apply whether a human is typing droid or a GitHub Actions runner is calling droid exec.

A minimal CI step:

# .github/workflows/droid-review.yml
- name: Run Droid analysis
  run: |
    droid exec --cwd . --auto low \
      "Review the diff in this PR against AGENTS.md conventions and flag violations"

A few things matter more in headless mode than in an interactive session:

• Exit codes are your signal. droid exec exits 0 on success and non-zero on failure — a permission violation, a tool error, or an unmet objective all produce non-zero. Treat any non-zero exit as a failed CI step; don’t parse stdout for success/failure.
• Keep --auto conservative. --auto low limits what Droid can mutate without triggering a stop. In an unattended pipeline, that’s the difference between a bad run producing a diagnostic report and a bad run pushing a broken commit.
• Ask for artifacts your pipeline can check. Rather than relying on prose output, have your AGENTS.md verification section (or your prompt) instruct Droid to emit structured output — JSON or a file the next pipeline step can parse — instead of a paragraph a human has to read.
• If a permission tier is exceeded, Droid stops cold. No partial changes, a clear error, non-zero exit. That’s a deliberate safety property, not a bug to work around by cranking --auto up until it stops complaining.

If your AGENTS.md already has a ## Verification section written for interactive sessions, it doubles as the check droid exec runs against in CI — you’re not maintaining two separate instruction sets for the same repo.

AGENTS.md vs settings.json vs CLAUDE.md

The short version: settings.json is permissions and behavior, AGENTS.md is project knowledge. Factory’s docs are explicit that the older .droid.yaml format is being superseded by AGENTS.md for the instructions half of that split — if you have an existing .droid.yaml, migrating its repository-instructions content into AGENTS.md is the direction Factory is pushing.

What Not to Put in AGENTS.md

Factory’s own guidance flags these, and they match what causes problems across every AGENTS.md-reading tool, not just Droid:

• Secrets, credentials, tokens, or private hostnames
• Full copies of documentation that already lives elsewhere in the repo
• Inventories that go stale fast — exact dependency versions, file counts
• Vague style guidance that doesn’t change agent behavior (“write clean code”)
• Instructions telling Droid to skip verification steps

On the secrets point specifically: even if you keep credentials out of AGENTS.md itself, they’re not actually protected if they’re still sitting in a .env file in the same directory Droid can read. 1Password CLI’s op run injects secrets into the process environment at runtime instead of storing them in a file at all — there’s nothing in the repo for an AGENTS.md-reading agent, or a teammate browsing the same directories, to stumble into.

Frequently Asked Questions

Do I need to enable anything for Droid to read AGENTS.md? No. Droid reads it automatically from your project’s git root (and nested directories) with zero configuration. If it isn’t picking up your instructions, the cause is almost always the file’s location, name, or git-ignore status — not a missing setting.

What’s the fastest way to install Droid on macOS? curl -fsSL https://app.factory.ai/cli | sh. It’s the officially quoted sub-two-minute install path and doesn’t require Node already installed, unlike the npm method.

Can I reuse my existing CLAUDE.md instead of writing a new AGENTS.md? Yes, as-is, provided it doesn’t rely on Claude Code-specific syntax like @file imports. Droid’s compatible filename list includes CLAUDE.md and Claude.md directly.

Does droid exec use the same AGENTS.md as the interactive CLI? Yes. droid exec reads the same file, which is what makes it possible to write your verification and conventions once and have them apply in both an interactive session and an unattended CI run.

How do I confirm my AGENTS.md is actually being read? Start a fresh Droid session and ask it directly what repository instructions it has loaded and where they came from. A specific answer naming your actual commands and conventions confirms it’s working; a generic “best practices” answer means it isn’t finding the file.

What happens if my AGENTS.md is too long? Droid caps initial load at 80,000 characters and dynamically discovered files at 40,000 characters. Content past that ceiling doesn’t get read. Split project-wide rules from directory-specific detail into nested files rather than growing one root file indefinitely.

Is AGENTS.md a Factory-specific format? No — it’s an open, multi-vendor standard also read by Claude Code, Codex, Cursor, Gemini CLI, and others. Droid’s specific contribution is the six-location discovery search (project and personal levels, three folder name variants each) and the CLAUDE.md filename compatibility, both covered in more depth in our discovery mechanics guide.

Related Reading on The Prompt Shelf

• How Factory Droid CLI Discovers AGENTS.md (2026) — the full precedence order and folder search mechanics
• AGENTS.md for OpenAI Codex: Complete Setup and Configuration Guide (2026)
• AGENTS.md vs CLAUDE.md: Tool Support Compared (2026)
• Does Claude Code Support AGENTS.md? The Complete 2026 Reference
• AGENTS.md Not Loading? How to Debug It in 2026

Browse real-world AGENTS.md files across different stacks in our rules gallery.