fallow agent

Set up fallow for Claude Code, Codex, and Cursor with one command. Fallow agent installs the AGENTS.md task map, the skill, the MCP server registration, and the commit and push gate, and can show status or uninstall.

Set up fallow for each coding-agent harness in a project with one command. fallow agent install detects Claude Code, Codex, and Cursor. Then it writes the files that each harness reads:

• an AGENTS.md task map
• the fallow and fallow-setup skills
• the MCP server registration
• the commit and push gate

fallow agent status shows what is installed. fallow agent uninstall removes exactly what fallow wrote.

fallow agent install --dry-run   # show the plan first
fallow agent install             # wire every detected harness

Detection

Without --harness, fallow selects a harness when one or more of its signals is present. When no signal exists, fallow writes nothing for that harness. For example, a Cursor-only repository never gets a .claude/ directory.

When fallow detects no harness, it writes only the harness-neutral files (AGENTS.md and .agents/skills/fallow). The output then names the --harness values that you can pass. AGENTS.md is not a detection signal, because every harness and fallow write it.

What each step writes

Skills. The step writes two skills: fallow for analysis, and fallow-setup to set up code-quality tooling in a project. It reports one skill row for each skill in each skill directory. When the project has node_modules/fallow/skills/<name>, the installed skill is a small pointer to that copy. The skill thus always matches the fallow version that the project pins. Without that directory, fallow writes the skill from the binary, which matches the binary version. Fallow selects the source of each skill separately. An older npm package without fallow-setup thus gets the copy from the binary for that skill. If a skill named fallow or fallow-setup exists and fallow did not write it, that step is refused (skill_name_taken), unless you pass --force. Fallow still writes the other skill.

MCP. Before it writes anything, fallow checks that the server command can start. It tries these commands:

• npx --no fallow-mcp for an npm-installed project
• fallow-mcp from PATH
• the running binary, when it is the npm multicall build

When none of them exists, fallow skips the step with mcp_entry_unavailable. It does not write a registration that cannot start. A project-level .codex/config.toml applies only after Codex trusts the project. The output thus starts with the codex mcp add fallow -- ... command, which works immediately.

Gate. For Claude Code and Codex, the step installs a PreToolUse hook that runs fallow audit before git commit and git push, and blocks the command on a fail verdict. Both harnesses run the same gate script. The Codex handler in .codex/hooks.json uses the matcher ^Bash$. Codex runs a project hook only after you trust it in /hooks. The AGENTS.md block tells agents to use fallow and names the hook as the enforcement layer. Claude Code hooks has the details.

Approval. Claude Code asks before it starts a project-scoped MCP server. --approve records that approval for you: it lists fallow in .claude/settings.local.json. The flag is opt-in. Fallow refuses it when git tracks that file.

Markers, idempotency, and uninstall

Each file or block that fallow writes has a <!-- fallow:agent-install v1 ... --> marker. A second run gives the same bytes and reports every step as unchanged.

• Fallow never overwrites a file that it did not write, unless you pass --force.
• A fallow MCP entry belongs to fallow only when its command is one that fallow writes. Fallow refuses a hand-written entry (mcp_entry_foreign) and keeps it.
• --force on a config file that fallow cannot parse first saves the old bytes as <file>.fallow-bak.
• uninstall removes managed blocks and entries, and deletes a config file that it emptied. It deletes AGENTS.md or CLAUDE.md only while the file still matches what fallow wrote.

Options

The root is the git toplevel of the current directory, unless you pass --root. A run from a monorepo package thus still writes where the harnesses read. The first line of output shows the chosen root.

Output

Human output groups paths under "Shared with your team (commit these)" and "Local to you".

With --format json, the envelope has kind (agent-install, agent-uninstall, agent-status), schema_version, and fallow_version. Each step has:

• harness, step, scope, and path
• status: written, removed, unchanged, skipped, refused, or failed
• a reason, when the step was skipped or refused

After the steps comes next_actions. An action is flagged mutating when it would write harness config. The next_steps of the analysis commands are read-only.

The exit code is 2 when a step is refused or failed. All other steps still run.

agent status reports a different shape: surfaces[], each with harness, step, path, and a state of absent, installed, stale, or foreign. stale means that an older fallow version wrote the surface, or that the surface is installed but would not do its job. foreign means that the file or entry exists, but fallow did not write it. fallow agent install --force replaces a foreign surface. Without --force, fallow leaves it alone.

For Codex, the hooks step has two surfaces: the gate script .codex/hooks/fallow-gate.sh and the AGENTS.md routing block. A hooks gate is stale when an older fallow wrote it. An installed gate is also stale when its run-time prerequisites are missing. The reason is in detail, with a matching entry in next_actions[]. Two gate conditions report this way:

• gate-requires-jq: when jq is absent, the gate script prints one stderr line and exits 0, and a PreToolUse hook never shows that line.
• gate-path-version: the gate runs the fallow that PATH resolves, which can differ from the build that installed it.

Branch on state, and not on the presence of the path.

fallow agent install --format json --quiet
fallow agent status --format json
fallow agent uninstall --dry-run

See also