Factory Droid Config: AGENTS.md, .factory/settings.json, MCP, Hooks

Droid loads AGENTS.md from each directory between your working directory and the git root, including the .factory/, .agents/ and .agent/ folders, plus personal files in ~/.factory/. MCP servers are in ~/.factory/mcp.json or .factory/mcp.json, hooks in .factory/hooks.json, skills in .factory/skills/ (or .agents/skills/). Command policy is permissionRules in .factory/settings.json, with allow, ask and block decisions and required tests, plus an OS-level sandbox and an autonomy level.

Factory Droid at a glance

Global instructions	✓ Yes `~/.factory/`, `~/.agents/`, `~/.agent/` (AGENTS.md)
Project instructions	✓ Yes `AGENTS.md` in each dir from cwd up to git root, and in `.factory/`, `.agents/`, `.agent/`
Nested / subfolder	✓ Yes Nested AGENTS.md refines root files
AGENTS.md	✓ Yes Primary format
Skills (SKILL.md)	✓ Yes `.factory/skills/`, `.agents/skills/`; `~/.factory/skills/`, `~/.agents/skills/`
MCP config	✓ Yes `~/.factory/mcp.json` (user), `.factory/mcp.json` (project)
Permissions / allowlist	✓ Yes `permissionRules` (allow / ask / block, token-prefix match, required tests) in `~/.factory/settings.json` or `.factory/settings.json`; autonomy levels
Sandbox	✓ Yes OS sandbox: Seatbelt (macOS), bubblewrap (Linux/WSL2); per-command or whole-process
Hooks	✓ Yes `~/.factory/hooks.json`, `.factory/hooks.json`
Claude Pro/Max login	? Not documented Not documented
ChatGPT Plus/Pro login	? Not documented Not documented
API key / own plan	✓ Yes Factory plans or BYOK custom models

Exact file paths

Path	Scope	What it does
`AGENTS.md (+ .factory/, .agents/)`	Project	Instructions
`~/.factory/`	User	Personal instructions, settings, skills
`.factory/settings.json`	Project	permissionRules and settings
`.factory/mcp.json`	Project	MCP servers (user: ~/.factory/mcp.json)
`.factory/hooks.json`	Project	Hooks
`.factory/skills/<name>/SKILL.md`	Project	Skills

Using a shared AGENTS.md with Factory Droid

Native (also in .factory/ and .agents/). See one AGENTS.md for every agent, or generate one with the AGENTS.md generator.

Copy-paste examples

Require approval before git push

File: .factory/settings.json

{
  "permissionRules": {
    "version": 1,
    "rules": [
      {
        "id": "project/git-push",
        "decision": "ask",
        "reason": "Review remote Git changes before pushing.",
        "match": { "prefix": ["git", "push"] },
        "tests": { "match": ["git push origin main"], "noMatch": ["git status"] }
      }
    ]
  }
}

Safe permissions preset

Safe Droid permission rules

File: .factory/settings.json

{
  "permissionRules": {
    "version": 1,
    "rules": [
      {
        "id": "project/no-rm-rf",
        "decision": "block",
        "reason": "No recursive deletes.",
        "match": { "prefix": ["rm", ["-rf", "-fr"]] },
        "tests": { "match": ["rm -rf build"], "noMatch": ["rm file.txt"] }
      },
      {
        "id": "project/no-force-push",
        "decision": "block",
        "reason": "Never force-push.",
        "match": { "prefix": ["git", "push", ["--force", "-f"]] },
        "tests": { "match": ["git push --force"], "noMatch": ["git push origin main"] }
      },
      {
        "id": "project/review-push",
        "decision": "ask",
        "reason": "Review before pushing.",
        "match": { "prefix": ["git", "push"] },
        "tests": { "match": ["git push origin main"], "noMatch": ["git status"] }
      }
    ]
  }
}

Each rule needs tests that must match and must not match; Droid validates them. Prefix matching is token-exact, so git -C /repo push is a different spelling. Pair with the sandbox. The old commandAllowlist / commandDenylist keys are deprecated.

Gotchas

commandAllowlist and commandDenylist are deprecated in favour of permissionRules.
Keep long runbooks out of AGENTS.md; use skills for procedures.

FAQ

Where is the Factory Droid MCP config?

~/.factory/mcp.json for personal servers and .factory/mcp.json in the project for shared servers.

Does Droid read AGENTS.md?

Yes. It searches from the working directory up to the git root, checking each directory and its .factory/, .agents/ and .agent/ folders, plus ~/.factory/ for personal files.

Sources

Checked against these official pages on 2026-10-12. Cells marked "Not documented" mean we could not find the behaviour in these docs; it may still exist.

Factory Droid configuration guide: instruction files, MCP, permissions