fallow agent: set up Claude Code, Codex and Cursor

Set up fallow for Claude Code, Codex, and Cursor with one command. It installs AGENTS.md, the skill, the MCP server, and a commit and push gate.

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
fallow agent status --format json

Review next_actions after installation. Approve the project and its hooks in your harness when prompted.

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

Fallow does not write, back up or delete a project path when the path, or a directory on the way to it, is a symlink that resolves outside the project root, or a dangling link. The step then has the status skipped and the reason symlinked_path. A link that stays inside the project, such as CLAUDE.md -> AGENTS.md, still works. --user targets still follow symlinks.

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.

A --dry-run of agent install that plans at least one write puts an agent-install-apply action first in next_actions[]. The human output shows it first in the Next: list. Its command applies the plan: it drops --dry-run and repeats the flags that change the plan (--harness, --user, --without, --force, --approve, --gitignore-claude, and --root). A harness that detection found is repeated as --harness, because detection reads the session environment and $HOME. A run of the command in another shell then writes the same plan.

{
  "next_actions": [
    {
      "id": "agent-install-apply",
      "command": "fallow agent install --harness claude",
      "reason": "This was a dry run. The command writes the steps marked \"would write\".",
      "mutating": true
    }
  ]
}

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 the surface needs a refresh, or that its runtime is missing or unverified. 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.

Gate readiness

For Codex, the hooks step covers the gate script and the AGENTS.md routing block. Check detail and next_actions[] for a stale gate:

Status inventories project launchers and package managers without executing them. It does not verify project trust or hook activation. Branch on state and the action ID. A missing reader makes the gate print a notice and exit 0 without auditing.

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

See also