Agent integration

AI coding agents generate code at scale, but they don't perform codebase-level analysis. Building a module graph, tracing re-export chains, detecting duplication across thousands of files, scoring complexity hotspots: these require a dedicated tool. Fallow provides deterministic, exhaustive codebase analysis that agents call via CLI or MCP.

Why agents need fallow

Codebase analysis means building and traversing a graph, not reading files in a context window.

CLI: the primary agent interface

Every AI coding agent can run shell commands. No MCP required:

# 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 exposes analysis as structured tools. Agents get typed inputs and outputs instead of parsing CLI text.

The MCP server uses stdio transport and a hybrid adapter. Supported requests run in process, while command-owned options use a managed fallow CLI subprocess. Set FALLOW_BIN only when CLI-backed calls need a specific binary (defaults to fallow in PATH).

Install with cargo install fallow-mcp or grab 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": "npx",
      "args": ["fallow-mcp"]
    }
  }
}

Available MCP tools

Runtime source-map confidence

Cloud runtime tools can include source-map confidence metadata when the response capabilities array contains function_identity_v2. Function list responses use resolutionStatus and mappingQuality; runtime-context responses use resolution_status and mapping_quality. These fields describe source-map confidence, not whether the function ran.

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

Notable tool parameters

Some tools accept additional parameters beyond the common root, config, no_cache, and threads:

Structured actions in tool responses

All tools return structured actions arrays on every finding, enabling agents to programmatically apply fixes or suppressions:

• Dead code (analyze, check_changed): fix action (e.g. remove-export) + suppress action. Agents can use the auto_fixable flag to decide whether to call fix_apply or handle the suggestion manually. See the dead-code CLI reference for action type details.
• Health (check_health, audit): complexity findings and styling findings carry an actions array. Complexity findings select their primary action with the CRAP/coverage formula keyed off coverage_tier, cyclomatic, and max_crap_threshold; possible action types include refactor-function, add-tests, increase-coverage, and suppress-line. Styling findings use styling-specific read-only verification and suppression actions. When --baseline/--save-baseline is passed OR health.suggestInlineSuppression: false, suppress-line is omitted and a top-level actions_meta: { suppression_hints_omitted: true, reason } breadcrumb is added (under health.actions_meta in combined-mode and audit output). Targets get apply-refactoring + suppress (when evidence exists). Hotspots get refactor-file + add-tests.
• Duplication (find_dupes, audit): extract-shared + suppress actions on clone families and groups.
• Audit (audit): inherits actions from all three sub-analyses (dead code, health, duplication).

Command-level next_steps[]

Distinct from the per-finding actions[], the analyze, check_health, find_dupes, and audit responses (and combined output) carry a top-level next_steps[] array of read-only follow-up commands computed from the run's findings. Each entry is { id, command, reason }:

• command is runnable as-is and never a fix or any other mutating command (fallow surfaces evidence; deciding and applying the change is the agent's job).
• 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 acting. When working through MCP, dispatch on the id to the matching tool (trace_export, trace_clone, check_health with complexity_breakdown: true, audit) or code_execute host call rather than shelling out the CLI command string.
• A leading setup step (command: fallow schema) appears only on unconfigured, non-CI projects with findings. It has no mutating tool equivalent by design: read the manifest, then offer the guided-setup commands (fallow init --agents, fallow hooks install --target agent) to the user instead of running them unprompted. It disappears once a config exists or after fallow init --decline.
• An at-most-weekly impact-report step (command: fallow impact) carries the local value digest (commits contained at the gate, findings resolved) when impact tracking is enabled and has non-zero results. The cadence stamp lives in the impact store, so it is consistent across agents and sessions, and the step may appear even on a clean run. Relay the non-zero numbers to the user in one line.

The array is deduplicated, priority-ordered, capped at three, and omitted when empty. Set FALLOW_SUGGESTIONS=off in the server env to suppress it.

value_schema on add-to-config actions

add-to-config actions (emitted for unused-dependency, type-only-dependency, test-only-dependency, duplicate-export, and similar findings where the resolution is "add an entry to the fallow config") carry an optional value_schema field alongside 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 fallow's published schema.json. Agents that want to validate value before writing it into a user's config (for example, to reject a malformed { file, exports } rule object on the ignoreExports action) can fetch the linked schema and apply it locally. The field is strictly additive: actions that did not have a schema before continue to work without one, and agents that ignore the field keep working unchanged.

Resources

Besides tools, the server exposes read-only reference material as MCP resources: no subprocess, no analysis run, cacheable by URI (your client reads them through its own resource tool, for example ReadMcpResourceTool in Claude Code). Every payload is plain JSON; the server version travels in each content item's _meta.fallow_version, so a cached copy is self-describing and the schema resources stay valid strict JSON Schema. The catalogue is fixed at build time (no subscriptions, no list-changed notifications).

{issue_type} accepts the bare id (unused-export), the namespaced id (fallow/unused-export), or the CLI filter spelling. Unknown URIs return a structured error whose data lists the known URIs; an unknown issue type lists the nearest matches. The numeric code is -32002 for clients on protocol versions before 2026-07-28 and -32602 from then on, so key on data rather than the code. The same catalogue is published as mcp_resources in fallow schema.

Combined output from bare fallow

Running bare fallow (no subcommand) executes all analyses in one pass and returns a combined JSON object with dead_code, duplication, and health sections:

fallow --format json

This is the most efficient way for agents to get a full picture of the codebase in a single call. The combined output includes all issue types from dead code, duplication findings, and health metrics.

Environment variables

Error handling

The MCP server returns structured JSON errors from both adapter paths:

• Typed API timeout: returns the FALLOW_MCP_API_TIMEOUT code. The response is bounded, although in-process work may finish in the background.
• CLI exit code 1: treated as success (issues found, not an error). The full JSON output is returned.
• CLI exit code 2+: passes through the CLI's structured JSON error from stdout when available. If no JSON is available, the server constructs {"error": true, "message": "...", "exit_code": N} from stderr.
• CLI timeout: kills the process tree and returns the FALLOW_MCP_SUBPROCESS_TIMEOUT code.

See also