Fallow for coding agents
Set up fallow for Claude Code, Codex, Cursor and other coding agents, choose the parts that your agent needs, and verify each change.
A coding agent says that a task is done, and the diff looks correct. But the agent can leave an export that nothing imports, or copy a function that the project already has, and the tests still pass. Fallow gives the agent a check of its own change, so it finds these problems before it commits. This page helps you choose the parts of the setup that your agent needs, and shows how to verify a change.
A coding agent gets three things from fallow:
- A check of its own change.
fallow auditgives a verdict for the changed files, and marks each finding that the change adds. - Facts from the module graph. For example, which files import an export, or why fallow reports a file as unused. The agent then does not guess from the text of one file.
- Fixes that it can preview.
fallow fix --dry-runlists each change beforefallow fix --yesapplies it.
Before you start
- Add fallow to the development dependencies of the project:
npm install --save-dev fallow. The agent then runs the same version as your team and your CI. - Use fallow with a coding agent shows the setup step by step, with real output. This page gives the choices.
Set up with one command
You do not need to write the agent setup by hand. fallow agent install sets up each agent that it finds in the project, in your home folder and in the current session. It supports Claude Code, Codex and Cursor. Run it with --dry-run first to see the plan:
npx fallow agent install --dry-run
npx fallow agent install
The command writes four parts. Each part has a marker, so npx fallow agent status can report it and npx fallow agent uninstall can remove it.
- To skip a part, add
--without guide,--without skill,--without mcpor--without hooks. - To select the agents yourself, add
--harness claude,--harness codexor--harness cursor. - To write the skills, the MCP server and the commit gate to your home folder for all projects, add
--user. The guide stays a project file. For the MCP server of Claude Code, the command prints aclaude mcp addcommand for you to run.
fallow agent lists each option and the files of each agent.
Which part do I need
The parts work in two ways. The guide and the skills tell the agent what to do. The commit gate makes sure that the check runs, also when the agent does not follow the skill. The table shows which agents can use each part:
| Part | What it gives the agent | Agents | Set up with |
|---|---|---|---|
| The CLI with JSON output | Each analysis, with typed JSON. Always needed. | Each agent with a shell | npm install --save-dev fallow |
| The guide | AGENTS.md with a task map: the fallow command to run before each kind of change. | Each agent that reads AGENTS.md. Claude Code reads it through a CLAUDE.md import. | fallow agent install |
| Skills | Instructions for each task: the command, the options, and how to read the output. | Claude Code (.claude/skills/), Codex and Cursor (.agents/skills/), and other agents that read Agent Skills | fallow agent install, or a plugin |
| MCP server | Each analysis as a typed tool call. Use it for a client without a shell, or when you want structured tool calls. | Each MCP client | fallow agent install, or the config of the client |
| Commit gate | A hook that runs fallow audit before git commit and git push, and blocks the command on a fail verdict. | Claude Code and Codex | fallow agent install |
Install all parts with fallow agent install, unless your agent cannot use one of them. Cursor gets no commit gate, so there only the guide and the skills ask the agent to run the check. Use fallow with a coding agent shows four rows of that task map.
Plugins
fallow agent install works on one project at a time. The fallow-skills repository packages the skills as a plugin for some agents. Use a plugin when you want the skills for all your projects. fallow agent install writes the same skills into one project.
| Agent | Install | The plugin adds |
|---|---|---|
| Claude Code | /plugin marketplace add fallow-rs/fallow-skills, then /plugin install fallow@fallow-skills | The skills, a commit gate, and the Fallow app: a code health dashboard in the conversation |
| Codex | codex plugin marketplace add fallow-rs/fallow-skills, then codex plugin add fallow@fallow-skills | The skills, and in the Codex desktop app the Fallow app: a dashboard, a Code Health tab for each thread, @Fallow mentions and a config editor |
| Cursor | Copy the fallow folder of the repository to ~/.cursor/plugins/local/fallow | The skills and the MCP server |
| Other agents | npx skills add fallow-rs/fallow-skills | The skills |
The Fallow app needs Node.js 20 or later. It runs the fallow CLI on your machine, so the code stays local. The commit gate of the Claude Code plugin does nothing when fallow agent install already wrote a commit gate. To turn the plugin version off, set FALLOW_PLUGIN_GATE=off in the environment of Claude Code.
Verify a change
With the setup in place, the next question is whether you can trust the claim of the agent that a task is done. A check that runs on the change gives you evidence for that claim. Each check finds a different problem:
| Check | Command | What it tells you |
|---|---|---|
| Tests and type check | The commands of your project | The code does what the tests expect. |
| Changed-code check | fallow audit | The change adds no unused code, complexity, duplication or styling problem. |
| Diff-risk rules | fallow audit | The change does not skip a test, remove an assertion, or add a suppression comment. |
| Mutation testing | fallow mutation | The tests fail when the changed code is wrong. |
| Review brief | fallow audit --brief | The places in the change that a reviewer looks at first. |
fallow audit runs no project code, so the agent can run it on each change. fallow mutation runs your tests many times. Limit it with --max-mutants or --time-budget.
The diff-risk rules compare each changed file with its base. They have the severity warn by default, so they report and do not fail the audit. To make the audit fail on them, set them to error:
// .fallowrc.json
{
"rules": {
"weakened-tests": "error",
"added-suppression": "error"
}
}
The agent can change the config file too. Fallow reports a change that makes a rule less strict as a weakened-tests finding. Add a code owner for the config file, and run fallow audit in CI, where the agent cannot change the command.
A verify skill for your project
The agent runs these checks only when something asks it to. A skill tells the agent which checks to run and what to report. Put this file in .claude/skills/verify/SKILL.md for Claude Code, or in .agents/skills/verify/SKILL.md for Codex and Cursor. Replace the test commands with the commands of your project.
---
name: verify
description: Use before you say that a change is done, before a commit, and before you open a pull request. Runs the tests, fallow audit and fallow mutation, and reports the evidence.
---
# Verify
Run each step in order. When a step fails, fix the cause, then start again at step 1.
1. Run the type check: `npm run typecheck`.
2. Run the tests: `npm test`.
3. Run `fallow audit --format json --quiet --explain`.
- When `verdict` is `fail`, fix each finding with `"introduced": true`.
- Do not skip a test, remove an assertion, or add a suppression to make a check pass.
4. When the change adds logic, run `fallow mutation --max-mutants 50 --format json --quiet`.
- For each `survived` mutant, write a test that fails on that mutant.
When one step fails three times, stop. Report the step, the error, and what you tried.
## Report
- The command of each step and its result.
- The audit verdict and each diff-risk finding.
- The mutation score, and each `survived` mutant without a new test.
- Each step that you did not run, and the reason.
Rules for an agent that runs fallow
The verify skill above calls the CLI. Each skill or script that runs fallow needs the same rules, because the default output is for people. Give these rules to an agent, or check that its skill follows them:
- Add
--format jsonand parse the JSON. Add--quietto remove the progress output. - Use the issue filters, for example
--unused-exports, to keep the output small. - Run
fallow fix --dry-run --format json --quietbefore a fix. Apply an approved fix withfallow fix --yes. - Use the
actionsarray and theauto_fixablefield of a finding. Do not invent a fix. - Read each path as relative to the project root.
- Read the exit code: 0 means that no gate failed, 1 that a gate failed, and 2 that the input was invalid or the run failed.
- Bare
fallowwith--format jsonexits with code 0 on findings. Add--fail-on-issuesto fail on them. - Add
--explainto get the meaning of each metric in the output. - Do not run
fallow watch. It does not exit. - Read the options from
fallow --helpandfallow <command> --help.
Check the result
Run npx fallow agent status. Each part that the install wrote shows installed. In the demo project, after npx fallow agent install --harness claude, these are the lines for Claude Code:
AGENTS.md installed guide authored by fallow, task map block present
CLAUDE.md installed guide (claude) imports AGENTS.md
.claude/skills/fallow installed skill (claude) embedded skill from fallow 3.45.0
.claude/hooks/fallow-gate.sh installed hooks (claude) gate script from fallow 3.45.0
A part that the install did not write shows absent. In the demo project, .mcp.json shows absent, because the project has no fallow-mcp launcher. The next section gives the cause.
If it fails
- The MCP step shows
skippedwithmcp_entry_unavailable. Fallow found nofallow-mcplauncher. Install fallow in the project with npm, then run the install again. - Cursor shows
skippedfor the hooks step. Cursor has no compatible hook. Cursor still readsAGENTS.md. - Codex does not run the commit gate. Codex runs a project hook only after you trust it in
/hooks.
Related
- Next: Commit gate for Claude Code and Codex. It shows the block message and how to set the policy of the gate.
fallow agent- MCP server