Agent integration

Your coding agent writes code fast, but it cannot see the whole codebase at once. It cannot build a module graph, follow re-export chains, find duplication across thousands of files, or score complexity hotspots. Fallow does that analysis for the agent. The agent calls fallow through the CLI or MCP and gets the same complete result on every run.

Why agents need fallow

To analyze a codebase, a tool must build the full import graph and walk it. An agent that reads files into its context window cannot do this.

CLI: the primary agent interface

Every AI coding agent can run shell commands, so you do not need MCP:

# Full dead code analysis with JSON output
fallow dead-code --format json

# Only check changed files (great for agent PR workflows)
fallow dead-code --changed-since main --format json

# Find code duplication
fallow dupes --format json

# Preview what auto-fix would remove
fallow fix --dry-run --format json

# Apply fixes (agents should use --yes to skip confirmation)
fallow fix --yes --format json

# Detect feature flags and environment gates
fallow flags --format json

# List project info (plugins, entry points, file count)
fallow list --format json

MCP: structured tool calling

For agents that support MCP (Model Context Protocol), fallow-mcp gives each analysis as a structured tool. The agent gets typed inputs and outputs and does not parse CLI text.

The MCP server uses stdio transport and a hybrid adapter. It runs supported requests in process. For options that only the CLI command has, it starts a managed fallow CLI subprocess. Set FALLOW_BIN only when CLI-backed calls need a specific binary. The default is fallow in PATH.

The fallow npm package includes the fallow-mcp launcher. You can also install it with cargo install fallow-mcp, or download a binary from GitHub Releases.

# Available in every project on this machine
claude mcp add fallow --scope user fallow-mcp

# This repository only, checked in for the whole team
claude mcp add fallow --scope project fallow-mcp

{
  "mcpServers": {
    "fallow": {
      "command": "fallow-mcp"
    }
  }
}

{
  "mcpServers": {
    "fallow": {
      "command": "fallow-mcp"
    }
  }
}

# Start the MCP server directly
fallow-mcp

# With a custom fallow binary path
FALLOW_BIN=/usr/local/bin/fallow fallow-mcp

{
  "mcpServers": {
    "fallow": {
      "command": "npx",
      "args": ["--yes", "--package", "fallow", "fallow-mcp"]
    }
  }
}

Available MCP tools

Runtime source-map confidence

When the response capabilities array has function_identity_v2, cloud runtime tools can add source-map confidence metadata. Function list responses use resolutionStatus and mappingQuality. Runtime-context responses use resolution_status and mapping_quality. These fields tell you how much to trust the source map. They do not tell you if the function ran.

{
  "tool": "analyze",
  "arguments": {
    "production": true,
    "issue_types": ["unused-exports", "unused-files"]
  }
}

Tool hints

analyze, check_changed, find_dupes, and check_health can write a baseline or snapshot file. These four tools therefore declare readOnlyHint: false and destructiveHint: false. A host that approves read-only tools without a confirmation now asks before it runs them. code_execute stays read-only.

The save_baseline, save_regression_baseline, and save_snapshot parameters write only inside the project root, its Git work tree, the CI workspace (GITHUB_WORKSPACE, CI_PROJECT_DIR), RUNNER_TEMP, or the system temp directory. Another path returns a tool error. See Save destinations.

Review optional props absent from callers

To request absent component props, pass issue_types: ["absent-component-props"] to analyze:

{
  "name": "analyze",
  "arguments": {
    "root": "/path/to/project",
    "issue_types": ["absent-component-props"]
  }
}

The rule is off by default. Selecting it opts in to findings about optional props that the component reads but no inspected reachable caller supplies. A finding includes its declaration and inspected callers. Review defaults and API intent before proposing an edit. Every action requires manual review; no action automatically removes a prop or conditional UI.

Notable tool parameters

Some tools take more parameters than the common root, config, no_cache, and threads:

Structured actions in tool responses

Every finding from every tool has a structured actions array. An agent can use it to apply fixes or suppressions in code:

• Dead code (analyze, check_changed): a fix action (for example remove-export) and a suppress action. The auto_fixable flag tells the agent whether to call fix_apply or to handle the suggestion by hand. For the action types, see the dead-code CLI reference.
• Health (check_health, audit): complexity findings and styling findings have an actions array. For complexity findings, a CRAP and coverage formula picks the primary action from coverage_tier, cyclomatic, and max_crap_threshold. The action types include refactor-function, add-tests, increase-coverage, and suppress-line. Styling findings have read-only verification and suppression actions for styling. When you pass --baseline or --save-baseline, or set health.suggestInlineSuppression: false, fallow leaves out suppress-line. It then adds a top-level actions_meta: { suppression_hints_omitted: true, reason } field (under health.actions_meta in combined-mode and audit output). Targets get apply-refactoring and a suppress action (when evidence exists). Hotspots get refactor-file and add-tests.
• Duplication (find_dupes, audit): extract-shared and suppress actions on clone families and groups.
• Audit (audit): the actions from all three parts (dead code, health, duplication).

Command-level next_steps[]

The analyze, check_health, find_dupes, and audit responses (and combined output) also have a top-level next_steps[] array. It is separate from the per-finding actions[]. It lists read-only follow-up commands, based on the findings of the run. Each entry is { id, command, reason }:

• You can run command as-is. It is never a fix or another command that changes files. Fallow gives the evidence. The agent decides on the change and applies it.
• The stable kebab-case id (setup, impact-report, trace-unused-export, trace-clone, complexity-breakdown, scope-workspaces, audit-changed) names a verification step to run before you act. Through MCP, use the id to call the matching tool (trace_export, trace_clone, check_health with complexity_breakdown: true, audit) or a code_execute host call. Do not run the CLI command string in a shell.
• A setup step (command: fallow schema) comes first, and only on projects with findings, no config, and no CI. By design, no tool runs it for you. Read the manifest, then offer the guided-setup commands (fallow init --agents, fallow hooks install --target agent) to the user. Do not run them without asking. The step goes away when a config exists or after fallow init --decline.
• An impact-report step (command: fallow impact) shows at most once a week. It has the local value digest (commits contained at the gate, findings resolved) when impact tracking is enabled and the results are not zero. The impact store keeps the time of the last step, so the weekly limit is the same for all agents and sessions. The step can show even on a clean run. Tell the user the non-zero numbers in one line.

The array has no duplicates, is in priority order, and has at most three entries. When it is empty, fallow leaves it out. To turn it off, set FALLOW_SUGGESTIONS=off in the server env.

value_schema on add-to-config actions

Fallow emits add-to-config actions for findings that you resolve with a new entry in the fallow config, such as unused-dependency, type-only-dependency, test-only-dependency, and duplicate-export. These actions have an optional value_schema field next to value:

{
  "type": "add-to-config",
  "config_key": "ignoreDependencies",
  "value": "autoprefixer",
  "value_schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json#/properties/ignoreDependencies/items"
}

The value_schema URL is a JSON Pointer fragment into the published fallow schema.json. An agent can fetch the linked schema to validate value before it writes the value into the config of a user. For example, it can reject a malformed { file, exports } rule object on the ignoreExports action. The field only adds information. Actions without a schema still work, and agents that ignore the field work as before.

Run-level warnings[]

CLI-backed tool calls run fallow with --quiet, so the caller gets nothing that the CLI writes to stderr. In its place, the root warnings[] array has plain sentences about the run:

• a stale baseline
• each gate that reported fail or warn
• diagnostics that made the analysis less complete
• each request the run could not apply

A request that made the report wider and an output file that the run did not write each get their own sentence. Only a wider report means that the findings cover more than you asked for. A request that the run applied to an empty scope also gets its own sentence. An empty scope cannot have findings. An empty result there means there was nothing to analyze. It does not mean the code is clean.

When the command cannot read a baseline file as its own format, that gets its own sentence, before the staleness sentence. Read baseline_staleness.unrecognised_format first, because such a file suppresses nothing. When the file names a writer that fallow knows, baseline_staleness.saved_by and the warning name the command that saved it. Pass another path, and do not save the baseline again. The sentence also says that the run would fail the --fail-on-stale-baseline gate. Every tool says this except audit, because the audit stale-baseline gate does not apply to the baselines it loads.

The typed in-process route reads the same fields, so a tool gives the same answer on both routes. The warnings do not move or remove other fields. gate_outcomes, baseline_staleness, workspace_diagnostics and request_outcomes stay where they are in the response. A run with nothing to report adds no warnings. A warning never makes the call an error.

Resources

The server also gives read-only reference material as MCP resources. A resource read starts no subprocess and runs no analysis, and your client can cache it by URI. The client reads resources with its own resource tool, for example ReadMcpResourceTool in Claude Code. Each payload is plain JSON. The server version is in _meta.fallow_version of each content item, so a cached copy shows its own version, and the schema resources stay valid strict JSON Schema. The catalogue is fixed at build time, so there are no subscriptions and no list-changed notifications.

{issue_type} takes the bare id (unused-export), the namespaced id (fallow/unused-export), or the CLI filter spelling. An unknown URI returns a structured error, and its data lists the known URIs. For an unknown issue type, data lists the nearest matches. The numeric code is -32002 for clients on protocol versions before 2026-07-28 and -32602 from that version on. So check data, not the code. fallow schema also publishes the same catalogue as mcp_resources.

Combined output from bare fallow

To get a full picture of the codebase in one call, run fallow with no subcommand. It runs all analyses in one pass and returns one JSON object with dead_code, duplication, and health sections:

fallow --format json

The combined output has all dead-code issue types, the duplication findings, and the health metrics.

Environment variables

Diff and ref from the environment

FALLOW_DIFF_FILE and FALLOW_CHANGED_SINCE come from the server environment, not from the caller. When the server cannot use one of them, the call does not fail. It stands down to the full project, the same as the CLI:

• A FALLOW_DIFF_FILE that cannot be read, or that is too large, gives a report at full scope.
• A FALLOW_CHANGED_SINCE ref that does not resolve gives a report at full scope.

The response then has a not-applied entry in request_outcomes, with the reason token and the sentence of the CLI, and a sentence in warnings[]. An applied request gives an applied entry with scope_size. The typed route and the CLI route publish the same object, on the dead-code, dupes, health, flags, and combined responses.

A since or changed_since argument that the caller passes, and that does not resolve, still fails the call with FALLOW_CHANGED_FILES_FAILED, because the caller can fix it.

Some tools keep the hard error for a FALLOW_CHANGED_SINCE ref that does not resolve:

• audit and decision_surface read the variable as their base ref, not as a request to narrow the report.
• project_info, list_boundaries, and the trace tools have no request_outcomes in their response. A ref that stands down would make their result wider, and nothing in the response would say so.

Error handling

The MCP server returns structured JSON errors from both routes:

• Typed API timeout: returns the FALLOW_MCP_API_TIMEOUT code. The response comes back in time, but the in-process work can still finish in the background.
• CLI exit code 1: the server treats it as success (issues found, not an error) and returns the full JSON output.
• CLI exit code 2+: the server passes through the structured JSON error that the CLI writes to stdout, when there is one. If there is no JSON, the server builds {"error": true, "message": "...", "exit_code": N} from stderr.
• CLI timeout: kills the process tree and returns the FALLOW_MCP_SUBPROCESS_TIMEOUT code.

See also