fallow MCP server
Commit Nov 15, 2026Analyzes TypeScript and JavaScript codebases to detect complexity, duplication, architecture drift, and unused code using a repository graph.
Also known as fallow-rs/fallow
- Stars
- 5,371
- Tools
- 44
- Downloads, 30 days
- —
- Latest version
- 3.43.1
- Last commit
- Nov 15, 2026
- License
- MIT
What is fallow MCP?
fallow analyzes TypeScript and JavaScript codebases to detect complexity, duplication, architecture drift, and unused code using a repository graph. It exposes 44 tools, such as analyze, audit, check_architecture.
Summary generated from the project's README
About fallow MCP server
Developers working with TypeScript and JavaScript can use fallow to maintain high code quality through deep repository analysis. By building a graph of modules, exports, and dependencies, it identifies issues like circular dependencies, high cyclomatic complexity, and code duplication across files and components. It is designed to run locally via npx or within CI/CD pipelines like GitHub Actions and GitLab CI to act as a pull request gate.
This tool operates as a fast Rust binary that requires no TypeScript compiler or complex configuration to begin. It provides specific commands such as audit to check for new issues introduced in changes, health to find refactoring targets, and dead-code to locate unused exports or types. Users can also utilize the viz command to generate an interactive HTML map of their project architecture. Because it uses a repository graph, it can detect architecture drift and styling inconsistencies in CSS or CSS-in-JS without needing a manual setup.
What you can do with it
- 1Preventing regression in pull requestsAn AI client can run an audit to ensure a new code change does not introduce any new complexity or duplication.
- 2Identifying refactoring targetsUse the tool to find functions with high cognitive complexity and low health scores to prioritize technical debt tasks.
Written from the project's README. Every use case is checked against a quote from it.
How to install fallow MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall fallow MCP in Claude Code
$ claude mcp add fallow -- npx -y fallow mcp-serverInstall fallow MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"fallow": {
"command": "npx",
"args": [
"-y",
"fallow",
"mcp-server"
]
}
}
}Install fallow MCP in VS Code
.vscode/mcp.json
{
"servers": {
"fallow": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"fallow",
"mcp-server"
]
}
}
}Install fallow MCP in VS Code CLI
$ code --add-mcp '{"name":"fallow","type":"stdio","command":"npx","args":["-y","fallow","mcp-server"]}'Install fallow MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"fallow": {
"command": "npx",
"args": [
"-y",
"fallow",
"mcp-server"
]
}
}
}Install fallow MCP in Codex
$ codex mcp add fallow -- npx -y fallow mcp-serverInstall fallow MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.fallow] command = "npx" args = ["-y", "fallow", "mcp-server"]
Install fallow MCP in Gemini CLI
$ gemini mcp add -s user fallow npx -- -y fallow mcp-serverInstall fallow MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"fallow": {
"command": "npx",
"args": [
"-y",
"fallow",
"mcp-server"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for fallow 3.43.1 in an isolated container with no network and no keys. It answered and listed 44 tools.
fallow MCP tools 44
Read from the server with tools/listanalyzeActionAnalyze a TypeScript/JavaScript project for unused code and dependency cycles. On a Rust root, it runs `cargo fallow check` (deps, visibility; no score) and takes only root. Detects unused files, exports, types, dependencies, enum/class members, unresolved imports, unlisted dependencies, duplicate exports, circular dependencies, re-export cycles (barrel files that form a structural loop, silently breaking re-exports), package cycles (workspace packages that import each other in a loop), boundary violations, rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the rulePacks config key), stale suppression comments, missing suppression reasons when rules.require-suppression-reason is enabled, unused pnpm catalog entries (entries in pnpm-workspace.yaml `catalog:` / `catalogs:` not referenced by any workspace package), empty pnpm catalog groups, unresolved catalog references (workspace package.json declares `catalog:` but the catalog has no entry), unused dependency overrides (entries in `pnpm-workspace.yaml#overrides`, `package.json#pnpm.overrides`, top-level `package.json#overrides`, or Bun `package.json#resolutions` whose target package no workspace package declares and the active readable lockfile does not resolve), and misconfigured dependency overrides (unparsable key or empty value; the active package manager may reject or ignore the entry). Opt-in issue_types: ["private-type-leaks"] (API hygiene), ["deprecated-exports-in-use"] (@deprecated in use), ["absent-component-props"] (optional-prop review), ["constant-parameters"] (parameter review). Returns structured JSON with all issues found, grouped by issue type. Each finding has a stable `finding_id`; an id absent from a scoped or differently configured run means unknown, not resolved. For code duplication use find_dupes, for complexity hotspots use check_health. Supports baselines, regression detection, performance tuning, boundary_violations, and group_by. Read the `fallow://tools/analyze` resource for the boundary_violations alias, the group_by modes, and how to dispatch the `next_steps[]` follow-up commands.
auditRead-onlyAudit changed files for dead code, complexity, duplication, styling, and diff risk. Purpose-built for reviewing AI-generated code. Combines the analyses scoped to changed files and returns a verdict (pass/warn/fail). Auto-detects the base branch if not specified. By default, audit runs the base ref too and gates only findings introduced by the changeset; inherited findings are annotated with introduced=false and counted under attribution. Set gate="all" or audit.gate="all" in config to gate every finding. Returns JSON with verdict, summary counts per category, attribution counts, and full issue details with actions array for remediation guidance. Per-analysis payloads nest under `dead_code`, `duplication`, and `complexity`; the `complexity` block carries the health sub-analysis output (audit JSON has no `health` key). The `diff_risk` section reports facts about the change itself, such as weakened tests, added suppressions, and a clone copy edited without its siblings. Styling analytics are on by default. Read the fallow://tools/audit guide for the diff-risk rules, styling, coverage, synthetic complexity units, grouping, baselines, runtime coverage, and `FALLOW_DIFF_FILE` scoping. Use this after generating code to verify quality before committing.
check_architectureRead-onlyCheck import cycles, boundary violations (with coverage and forbidden calls), and rule-pack policy violations. Returns the `kind: "architecture"` envelope: the finding arrays, `finding_id` values and actions of `analyze` for these issue types, with its own `schema_version`. Set `cycles`, `boundaries`, or `policy` to report one kind. Call `guard` before an edit and this tool after it. `baseline` takes a dead-code baseline. On a Rust root, it runs `cargo fallow boundaries`: `kind: "boundaries"`.
check_changedActionAnalyze only files changed since a git ref. Useful for incremental CI checks on pull requests. Returns the same structured JSON as analyze, but filtered to only include issues in changed files. Each finding keeps its `finding_id` from analyze; an id absent here means unknown, not resolved. Supports baseline comparisons (baseline/save_baseline), regression detection (fail_on_regression, tolerance, regression_baseline, save_regression_baseline), and performance tuning (no_cache, threads).
check_healthActionCheck code health metrics (cyclomatic and cognitive complexity) for functions in the project. Returns structured JSON with complexity scores per function, sorted by severity. On a Rust root, it runs `cargo fallow complexity` (max_cyclomatic, max_cognitive; no score). Set score=true for a single 0-100 health score with letter grade (A/B/C/D/F); runs duplication analysis automatically, but the churn-backed hotspot penalty requires hotspots=true (or targets=true). Set min_score=N to fail only when the score drops below a threshold (CI quality gate); min_score is authoritative, so complexity findings become informational and min_score=0 never fails. Exit codes are not surfaced over MCP, but the verdict is: a gated run publishes `gate_outcomes`, where `health-min-score` and `health-min-severity` carry a status, whether it was enforced, and the numbers compared. min_severity composes with min_score. Set file_scores=true for per-file health scores (maintainability index, fan-in, fan-out, dead code ratio, complexity density, CRAP risk), sorted in risk-aware triage order so lower MI and higher CRAP risk appear first. Set css=true to add a `css_analytics` section (specificity hotspots, `!important` density, over-complex selectors, deep nesting, design-token sprawl, unreferenced custom properties and `@keyframes`); opt-in because it parses every project stylesheet. Set complexity_breakdown=true to add a per-decision-point `contributions[]` array to each complexity finding, so you can explain WHY a function scored high and which lines to refactor. Set coverage_gaps=true to explicitly include static test coverage gaps: runtime files and exports with no test dependency path (not line-level coverage). A provided config file may also enable coverage gaps via rules.coverage-gaps when no health sections are explicitly selected. Set hotspots=true to identify files that are both complex and frequently changing (combines git churn with complexity). Set churn_file to a `fallow-churn/v1` JSON path to power the churn-backed signals (hotspots, ownership, refactoring targets) from imported VCS history instead of git. Set ownership=true (implies hotspots) to attach per-file ownership signals: bus factor, contributor count, declared CODEOWNERS owner, ownership_state, drift, and unowned-hotspot flag. Use ownership_email_mode=raw|handle|anonymized|hash for author email privacy (default handle; hash is the legacy spelling for anonymized output). Set targets=true for ranked refactoring recommendations sorted by efficiency (quick wins first), with confidence scores and adaptive percentile-based thresholds. Set trend=true to compare current metrics against the most recent saved snapshot and show per-metric deltas with directional indicators (improving/declining/stable). Implies --score. Requires prior snapshots saved with save_snapshot. Set effort to control analysis depth: 'low' (fast, surface-level), 'medium' (balanced, default), or 'high' (thorough, all heuristics). Set summary=true to include a natural-language summary of findings alongside the structured JSON. Set coverage to a path to Istanbul-format coverage data (coverage-final.json from Jest, Vitest, c8, nyc) for accurate per-function CRAP scores instead of the default estimated coverage. CRAP findings carry a `coverage_source` discriminator and the summary reports whether emitted sources are uniform or mixed. Besides real functions, health scores synthetic `<template>`, `<snippet:NAME>`, `<module>`, and Angular `<component>` rollup units, each with its own suppression placement and dimension rules. Set runtime_coverage to a path (V8 coverage directory, V8 JSON file, or Istanbul JSON file) for merged runtime-coverage findings (a single local capture is free; continuous or multi-capture runtime monitoring requires an active license via `fallow license activate`). Runtime-coverage tuning: set min_invocations_hot=N to tune the hot-path threshold (default 100), min_observation_volume=N to tune the high-confidence verdict floor (default 5000), and low_traffic_threshold=RATIO to tune the active/low-traffic split (default 0.001). Set group_by to "owner" (CODEOWNERS), "directory", "package" (workspace), or "section" (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata per group) to partition results. Each group recomputes its own metrics against its files. When config health.thresholdOverrides is set, health findings use the resolved local thresholds and JSON includes threshold_overrides state so agents can see active, stale, and full-run no-match exceptions. For code duplication use find_dupes, for changed-file review use audit, and for execution-backed dead-or-hot verdicts use check_runtime_coverage. Read the `fallow://tools/check_health` resource for the per-flag detail this summary omits: the per-group metrics, `css_analytics` contents, `contributions[]` entries, the React `react_hook_profile` and render-fan-in vital signs, churn-file import, `coverage_source` values, the synthetic `<template>` / `<snippet:NAME>` / `<module>` / `<component>` units and their suppression placements, and the `threshold_overrides` row semantics. Supports config, baseline comparisons, and performance tuning (no_cache, threads). Useful for identifying hard-to-maintain code and prioritizing refactoring.
check_runtime_coverageRead-onlyMerge runtime-coverage data into the health report. Focused entry point for the runtime-coverage pipeline: pass a V8 coverage directory (`NODE_V8_COVERAGE=<dir>`), a single V8 coverage JSON file, or an Istanbul `coverage-final.json` via the required `coverage` field. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring (multiple JSON files in a V8 directory) requires an active license JWT (start a 30-day trial with `fallow license activate --trial --email <addr>`; check state with `fallow license status`). Returns structured JSON with a `runtime_coverage` block containing surfaced `findings` verdicts (`safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable`), stable content-hash IDs (`fallow:prod:<hash>`), evidence, percentile-ranked hot paths (each with `start_line` and `end_line` so consumers can match against a PR diff), and on protocol-0.3+ sidecars a `summary.capture_quality` block that flags short-window captures. The sidecar may still classify other functions as `active`, but the CLI omits those from `runtime_coverage.findings` to keep the surfaced list actionable. Tunable via `min_invocations_hot` (hot-path threshold, default 100), `min_observation_volume` (high-confidence verdict floor, default 5000), and `low_traffic_threshold` (active/low_traffic split, default 0.001). `group_by` partitions results by CODEOWNERS / directory / package / section. PR-context behavior: when `FALLOW_DIFF_FILE` (path to a unified diff) is set in the agent's process environment, the top-level `runtime_coverage.verdict` promotes `hot-path-touched` over `cold-code-detected` so reviewers see the diff-tied signal first, AND every hot path is narrowed to functions whose `[start_line, end_line]` overlaps an added hunk. `FALLOW_CHANGED_SINCE` (git ref) also scopes (file-level). Without a change scope the verdict stays cold-code-primary and all hot paths are returned. The full unprioritized list is always in `runtime_coverage.signals[]` (kebab-case strings, severity-descending). Runtime coverage can exceed the default 120s MCP subprocess timeout on multi-megabyte dumps; raise `FALLOW_TIMEOUT_SECS` accordingly. For general complexity / hotspot / CRAP analysis without a production dump, use `check_health` instead.
code_executeRead-onlyExecute a bounded, read-only JavaScript Code Mode snippet against fallow's MCP host API. `code` must be a JavaScript function expression or function body that receives `{ fallow, root }` and returns a JSON-serializable value. The embedded sandbox exposes only a typed `fallow` object with read-only analysis calls: analyze, combined, checkChanged, checkArchitecture, securityCandidates, findDupes, projectInfo, traceExport, traceFile, impactClosure, traceDependency, traceClone, checkHealth, audit, explain, listBoundaries, featureFlags, impact, checkRuntimeCoverage, getHotPaths, getBlastRadius, getImportance, getCleanupCandidates, plus `fallow.run(tool, params)` for the same allowlist. Similar-code (15-minute timeouts) and mutation are excluded; use the standalone find_similar_code, inspect_similar_code, mutation_plan, and mutation_inspect MCP tools. Mutating fix tools are intentionally not exposed. The sandbox has no filesystem, network, module imports, process, require, Deno, Bun, or shell access, and no dynamic code compilation: eval, Function, and the async and generator function constructors are removed, including the `constructor` route reachable through function prototypes. `root` is injected into host calls that omit params.root. `timeout_ms` caps JS execution and subprocess-backed host calls. In Code Mode, analyze, checkArchitecture, securityCandidates, findDupes, impactClosure, checkHealth, audit, impact, checkRuntimeCoverage, getHotPaths, getBlastRadius, getImportance, and getCleanupCandidates stay subprocess-backed and are killed on timeout. Every other host call runs in this process, where `timeout_ms` both answers you on time and sets that call's cancellation token: the analysis is asked to stop rather than only abandoned. The stop is cooperative and has no upper bound, because a token set inside a long analysis stage is not read until that stage ends, so the work may still be winding down after the call returns, and while it is the next in-process call falls back to the killable subprocess. `max_output_bytes` caps the total fallow JSON read by host calls and, separately, the serialized snippet result: a larger result is refused with `ok:false`, `truncated:true`, `result_bytes`, and a short `result_preview` in place of the value, so return a projection rather than a whole report; an oversized thrown error message is clamped too, at `max_output_bytes` or 4096 bytes, whichever is larger, and reported with `truncated:true` and `error_bytes`. Host calls refused before dispatch (unknown tool name, malformed params, an output budget with nothing left) run nothing and do not spend the `max_host_calls` budget; `limits.max_rejected_host_calls` bounds how many of them `calls[]` records. Host calls are memoized for the duration of one snippet: repeating the same tool with the same params (key order does not matter) is served from that snippet's own cache, spends no `max_host_calls` slot and no output budget, and still appears in `calls[]` marked `cache_hit: true`; nothing is cached between invocations. The trace itself is bounded at `limits.max_recorded_calls` entries: beyond that the host calls still run and still return, only their trace entries are dropped, and `calls_omitted` reports how many, so a snippet looping one cached call cannot grow the response without limit. `fallow.all(requests)` fans out independent host calls in one go: `requests` is an array of `{ tool, params }` objects whose `tool` is the same wire name `fallow.run` takes, and the return value is an array positionally aligned with it whose elements are `{ ok: true, value }` or `{ ok: false, error }`, so one failing element never hides the others. Every batch element goes through the same tool validation, `root` injection, memoization, shared deadline, and output-byte accounting as a single call, and each element that actually dispatches spends one `max_host_calls` slot. The output budget is shared rather than per element: what is left of `max_output_bytes` is divided evenly across the dispatches a batch makes, so a fan-out reads at most `max_output_bytes` in total. A batch is refused whole, before anything runs, when an element is not an object carrying a `tool` string, when it holds more than `max_host_calls` elements, or when it needs more dispatches than the budget has left. The snippet stays synchronous, with no promises in the sandbox: `fallow.all` blocks until every element has resolved, overlapping the subprocess-backed elements while in-process ones run one at a time, so a fan-out cannot stack in-process analyses whose only stop is cooperative.
decision_surfaceRead-onlySurface the consequential structural DECISIONS a change embeds, each framed as a judgment question for a human with taste (`fallow decision-surface --format json`). The apex of the review brief and the single call that puts taste-decisions in front of a reviewer; separable and cheap, it runs the same changed-code analysis as the brief, NOT the full project pipeline. Returns `kind: "decision-surface"` with `schema_version`, a ranked `decisions[]` list, an optional `truncated` note, and `signal_count`. Each decision carries a `signal_id` (a deterministic anchor to the fallow-emitted candidate it frames; an agent decision whose `signal_id` fallow did not emit must be REJECTED, this is the anti-hallucination contract), a `category` (EXACTLY the SOLID-3: `coupling-boundary`, `public-api-contract`, `dependency`, nothing else), the framed `question`, the `anchor_file`/`anchor_line`, the `blast` (modules affected beyond the diff) and `consequence` rank, the routed `expert[]` (who to ask) with a `bus_factor_one` flag, and structured `actions[]` (`ask-expert`, `suppress`). The surface is CAPPED to a working-memory-sized handful (4 plus or minus 1, configurable via `max_decisions`, clamped to 3-5); decisions beyond the cap collapse into `truncated`. Every `coupling-boundary` and `public-api-contract` decision is suppressible with a `// fallow-ignore` comment on the anchor file (the `suppress` action carries the paste-ready comment); a `dependency` decision anchors on a `package.json`, which cannot carry a comment, so it has no `suppress` action. Always exits 0 (advisory, never a gate). Use `base` to pick the comparison point (defaults to the git merge-base). Use this to answer "what are the few decisions in this change that actually need human judgment?" rather than scanning the whole diff.
fallow_explainRead-onlyExplain one fallow issue type without running analysis. Returns the rule id, name, rationale, worked example, fix guidance, and docs URL as JSON. Use this before applying fixes when an agent or reviewer needs to understand what a finding means. If your client exposes MCP resources, `fallow://explain/{issue_type}` serves the same document as a cacheable resource read.
feature_flagsRead-onlyDetect feature flag patterns in a TypeScript/JavaScript project. Identifies environment variable flags (process.env.FEATURE_*), SDK calls from common providers, and config object patterns. Returns flag locations, detection confidence, and cross-reference with dead code findings. `retirement: true` adds advisory retirement rows (reasons, git age, evidence).
find_dupesActionFind code duplication across the project. Detects clone groups (identical or similar code blocks) with configurable detection modes and thresholds. Returns clone families with refactoring suggestions. On a Rust root, it runs `cargo fallow dupes` (mode, min_tokens, min_lines, threshold). Each clone_groups[] entry carries a stable `fingerprint` (dup:<id>); pass it to the trace_clone tool to deep-dive that group (locations, an extract-function suggestion with estimated savings, and a best-effort suggested name). Set top=N to show only the N highest-ranked clone groups. Ranking combines token count, occurrence count, and a capped spread boost for distant files or same-file locations. Set group_by to "owner" (CODEOWNERS), "directory", "package" (workspace), or "section" (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata per group) to partition results. Import declarations are excluded from clone detection by default (sorted import blocks are a formatting artifact, not copy-paste); pass ignore_imports=false to count them again. Clone instances omit their verbatim `fragment` text over MCP (it was most of the payload, and `file` plus the line/column range addresses the same code); set include_fragments=true to get it back. explain_skipped only changes the human-format skipped-default-ignores note (human/markdown CLI output); MCP JSON responses stay clean. Supports config, workspace scoping, baseline comparisons, and performance tuning (no_cache, threads).
find_similar_codeRead-onlyFind semantically similar functions with Fallow's exact pinned local model. Results are unverified candidates, not probabilities, duplication findings, refactor instructions, or CI gates. Source stays on the local machine. Each candidate carries stable candidate_id and review_key identities, exact locations, reproducible provider/model provenance, completion accounting, and read-only inspect/review actions. The command never downloads a model: if explicit setup has not happened, it returns structured guidance to run `fallow similar-code setup --local`. Use threshold only as a candidate-retrieval cutoff, then call inspect_similar_code before deciding whether two functions are behaviorally equivalent or safe to consolidate. Supports root, config, workspace, changed_since, changed_workspaces, paths, threshold, min_lines, top, no_cache, and threads. Cold local inference has a dedicated 15-minute subprocess window; FALLOW_TIMEOUT_SECS still overrides it when an operator needs a different bound.
| analyze | Analyze a TypeScript/JavaScript project for unused code and dependency cycles. On a Rust root, it runs `cargo fallow check` (deps, visibility; no score) and takes only root. Detects unused files, exports, types, dependencies, enum/class members, unresolved imports, unlisted dependencies, duplicate exports, circular dependencies, re-export cycles (barrel files that form a structural loop, silently breaking re-exports), package cycles (workspace packages that import each other in a loop), boundary violations, rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the rulePacks config key), stale suppression comments, missing suppression reasons when rules.require-suppression-reason is enabled, unused pnpm catalog entries (entries in pnpm-workspace.yaml `catalog:` / `catalogs:` not referenced by any workspace package), empty pnpm catalog groups, unresolved catalog references (workspace package.json declares `catalog:` but the catalog has no entry), unused dependency overrides (entries in `pnpm-workspace.yaml#overrides`, `package.json#pnpm.overrides`, top-level `package.json#overrides`, or Bun `package.json#resolutions` whose target package no workspace package declares and the active readable lockfile does not resolve), and misconfigured dependency overrides (unparsable key or empty value; the active package manager may reject or ignore the entry). Opt-in issue_types: ["private-type-leaks"] (API hygiene), ["deprecated-exports-in-use"] (@deprecated in use), ["absent-component-props"] (optional-prop review), ["constant-parameters"] (parameter review). Returns structured JSON with all issues found, grouped by issue type. Each finding has a stable `finding_id`; an id absent from a scoped or differently configured run means unknown, not resolved. For code duplication use find_dupes, for complexity hotspots use check_health. Supports baselines, regression detection, performance tuning, boundary_violations, and group_by. Read the `fallow://tools/analyze` resource for the boundary_violations alias, the group_by modes, and how to dispatch the `next_steps[]` follow-up commands. | Action |
| audit | Audit changed files for dead code, complexity, duplication, styling, and diff risk. Purpose-built for reviewing AI-generated code. Combines the analyses scoped to changed files and returns a verdict (pass/warn/fail). Auto-detects the base branch if not specified. By default, audit runs the base ref too and gates only findings introduced by the changeset; inherited findings are annotated with introduced=false and counted under attribution. Set gate="all" or audit.gate="all" in config to gate every finding. Returns JSON with verdict, summary counts per category, attribution counts, and full issue details with actions array for remediation guidance. Per-analysis payloads nest under `dead_code`, `duplication`, and `complexity`; the `complexity` block carries the health sub-analysis output (audit JSON has no `health` key). The `diff_risk` section reports facts about the change itself, such as weakened tests, added suppressions, and a clone copy edited without its siblings. Styling analytics are on by default. Read the fallow://tools/audit guide for the diff-risk rules, styling, coverage, synthetic complexity units, grouping, baselines, runtime coverage, and `FALLOW_DIFF_FILE` scoping. Use this after generating code to verify quality before committing. | Read-only |
| check_architecture | Check import cycles, boundary violations (with coverage and forbidden calls), and rule-pack policy violations. Returns the `kind: "architecture"` envelope: the finding arrays, `finding_id` values and actions of `analyze` for these issue types, with its own `schema_version`. Set `cycles`, `boundaries`, or `policy` to report one kind. Call `guard` before an edit and this tool after it. `baseline` takes a dead-code baseline. On a Rust root, it runs `cargo fallow boundaries`: `kind: "boundaries"`. | Read-only |
| check_changed | Analyze only files changed since a git ref. Useful for incremental CI checks on pull requests. Returns the same structured JSON as analyze, but filtered to only include issues in changed files. Each finding keeps its `finding_id` from analyze; an id absent here means unknown, not resolved. Supports baseline comparisons (baseline/save_baseline), regression detection (fail_on_regression, tolerance, regression_baseline, save_regression_baseline), and performance tuning (no_cache, threads). | Action |
| check_health | Check code health metrics (cyclomatic and cognitive complexity) for functions in the project. Returns structured JSON with complexity scores per function, sorted by severity. On a Rust root, it runs `cargo fallow complexity` (max_cyclomatic, max_cognitive; no score). Set score=true for a single 0-100 health score with letter grade (A/B/C/D/F); runs duplication analysis automatically, but the churn-backed hotspot penalty requires hotspots=true (or targets=true). Set min_score=N to fail only when the score drops below a threshold (CI quality gate); min_score is authoritative, so complexity findings become informational and min_score=0 never fails. Exit codes are not surfaced over MCP, but the verdict is: a gated run publishes `gate_outcomes`, where `health-min-score` and `health-min-severity` carry a status, whether it was enforced, and the numbers compared. min_severity composes with min_score. Set file_scores=true for per-file health scores (maintainability index, fan-in, fan-out, dead code ratio, complexity density, CRAP risk), sorted in risk-aware triage order so lower MI and higher CRAP risk appear first. Set css=true to add a `css_analytics` section (specificity hotspots, `!important` density, over-complex selectors, deep nesting, design-token sprawl, unreferenced custom properties and `@keyframes`); opt-in because it parses every project stylesheet. Set complexity_breakdown=true to add a per-decision-point `contributions[]` array to each complexity finding, so you can explain WHY a function scored high and which lines to refactor. Set coverage_gaps=true to explicitly include static test coverage gaps: runtime files and exports with no test dependency path (not line-level coverage). A provided config file may also enable coverage gaps via rules.coverage-gaps when no health sections are explicitly selected. Set hotspots=true to identify files that are both complex and frequently changing (combines git churn with complexity). Set churn_file to a `fallow-churn/v1` JSON path to power the churn-backed signals (hotspots, ownership, refactoring targets) from imported VCS history instead of git. Set ownership=true (implies hotspots) to attach per-file ownership signals: bus factor, contributor count, declared CODEOWNERS owner, ownership_state, drift, and unowned-hotspot flag. Use ownership_email_mode=raw|handle|anonymized|hash for author email privacy (default handle; hash is the legacy spelling for anonymized output). Set targets=true for ranked refactoring recommendations sorted by efficiency (quick wins first), with confidence scores and adaptive percentile-based thresholds. Set trend=true to compare current metrics against the most recent saved snapshot and show per-metric deltas with directional indicators (improving/declining/stable). Implies --score. Requires prior snapshots saved with save_snapshot. Set effort to control analysis depth: 'low' (fast, surface-level), 'medium' (balanced, default), or 'high' (thorough, all heuristics). Set summary=true to include a natural-language summary of findings alongside the structured JSON. Set coverage to a path to Istanbul-format coverage data (coverage-final.json from Jest, Vitest, c8, nyc) for accurate per-function CRAP scores instead of the default estimated coverage. CRAP findings carry a `coverage_source` discriminator and the summary reports whether emitted sources are uniform or mixed. Besides real functions, health scores synthetic `<template>`, `<snippet:NAME>`, `<module>`, and Angular `<component>` rollup units, each with its own suppression placement and dimension rules. Set runtime_coverage to a path (V8 coverage directory, V8 JSON file, or Istanbul JSON file) for merged runtime-coverage findings (a single local capture is free; continuous or multi-capture runtime monitoring requires an active license via `fallow license activate`). Runtime-coverage tuning: set min_invocations_hot=N to tune the hot-path threshold (default 100), min_observation_volume=N to tune the high-confidence verdict floor (default 5000), and low_traffic_threshold=RATIO to tune the active/low-traffic split (default 0.001). Set group_by to "owner" (CODEOWNERS), "directory", "package" (workspace), or "section" (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata per group) to partition results. Each group recomputes its own metrics against its files. When config health.thresholdOverrides is set, health findings use the resolved local thresholds and JSON includes threshold_overrides state so agents can see active, stale, and full-run no-match exceptions. For code duplication use find_dupes, for changed-file review use audit, and for execution-backed dead-or-hot verdicts use check_runtime_coverage. Read the `fallow://tools/check_health` resource for the per-flag detail this summary omits: the per-group metrics, `css_analytics` contents, `contributions[]` entries, the React `react_hook_profile` and render-fan-in vital signs, churn-file import, `coverage_source` values, the synthetic `<template>` / `<snippet:NAME>` / `<module>` / `<component>` units and their suppression placements, and the `threshold_overrides` row semantics. Supports config, baseline comparisons, and performance tuning (no_cache, threads). Useful for identifying hard-to-maintain code and prioritizing refactoring. | Action |
| check_runtime_coverage | Merge runtime-coverage data into the health report. Focused entry point for the runtime-coverage pipeline: pass a V8 coverage directory (`NODE_V8_COVERAGE=<dir>`), a single V8 coverage JSON file, or an Istanbul `coverage-final.json` via the required `coverage` field. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring (multiple JSON files in a V8 directory) requires an active license JWT (start a 30-day trial with `fallow license activate --trial --email <addr>`; check state with `fallow license status`). Returns structured JSON with a `runtime_coverage` block containing surfaced `findings` verdicts (`safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable`), stable content-hash IDs (`fallow:prod:<hash>`), evidence, percentile-ranked hot paths (each with `start_line` and `end_line` so consumers can match against a PR diff), and on protocol-0.3+ sidecars a `summary.capture_quality` block that flags short-window captures. The sidecar may still classify other functions as `active`, but the CLI omits those from `runtime_coverage.findings` to keep the surfaced list actionable. Tunable via `min_invocations_hot` (hot-path threshold, default 100), `min_observation_volume` (high-confidence verdict floor, default 5000), and `low_traffic_threshold` (active/low_traffic split, default 0.001). `group_by` partitions results by CODEOWNERS / directory / package / section. PR-context behavior: when `FALLOW_DIFF_FILE` (path to a unified diff) is set in the agent's process environment, the top-level `runtime_coverage.verdict` promotes `hot-path-touched` over `cold-code-detected` so reviewers see the diff-tied signal first, AND every hot path is narrowed to functions whose `[start_line, end_line]` overlaps an added hunk. `FALLOW_CHANGED_SINCE` (git ref) also scopes (file-level). Without a change scope the verdict stays cold-code-primary and all hot paths are returned. The full unprioritized list is always in `runtime_coverage.signals[]` (kebab-case strings, severity-descending). Runtime coverage can exceed the default 120s MCP subprocess timeout on multi-megabyte dumps; raise `FALLOW_TIMEOUT_SECS` accordingly. For general complexity / hotspot / CRAP analysis without a production dump, use `check_health` instead. | Read-only |
| code_execute | Execute a bounded, read-only JavaScript Code Mode snippet against fallow's MCP host API. `code` must be a JavaScript function expression or function body that receives `{ fallow, root }` and returns a JSON-serializable value. The embedded sandbox exposes only a typed `fallow` object with read-only analysis calls: analyze, combined, checkChanged, checkArchitecture, securityCandidates, findDupes, projectInfo, traceExport, traceFile, impactClosure, traceDependency, traceClone, checkHealth, audit, explain, listBoundaries, featureFlags, impact, checkRuntimeCoverage, getHotPaths, getBlastRadius, getImportance, getCleanupCandidates, plus `fallow.run(tool, params)` for the same allowlist. Similar-code (15-minute timeouts) and mutation are excluded; use the standalone find_similar_code, inspect_similar_code, mutation_plan, and mutation_inspect MCP tools. Mutating fix tools are intentionally not exposed. The sandbox has no filesystem, network, module imports, process, require, Deno, Bun, or shell access, and no dynamic code compilation: eval, Function, and the async and generator function constructors are removed, including the `constructor` route reachable through function prototypes. `root` is injected into host calls that omit params.root. `timeout_ms` caps JS execution and subprocess-backed host calls. In Code Mode, analyze, checkArchitecture, securityCandidates, findDupes, impactClosure, checkHealth, audit, impact, checkRuntimeCoverage, getHotPaths, getBlastRadius, getImportance, and getCleanupCandidates stay subprocess-backed and are killed on timeout. Every other host call runs in this process, where `timeout_ms` both answers you on time and sets that call's cancellation token: the analysis is asked to stop rather than only abandoned. The stop is cooperative and has no upper bound, because a token set inside a long analysis stage is not read until that stage ends, so the work may still be winding down after the call returns, and while it is the next in-process call falls back to the killable subprocess. `max_output_bytes` caps the total fallow JSON read by host calls and, separately, the serialized snippet result: a larger result is refused with `ok:false`, `truncated:true`, `result_bytes`, and a short `result_preview` in place of the value, so return a projection rather than a whole report; an oversized thrown error message is clamped too, at `max_output_bytes` or 4096 bytes, whichever is larger, and reported with `truncated:true` and `error_bytes`. Host calls refused before dispatch (unknown tool name, malformed params, an output budget with nothing left) run nothing and do not spend the `max_host_calls` budget; `limits.max_rejected_host_calls` bounds how many of them `calls[]` records. Host calls are memoized for the duration of one snippet: repeating the same tool with the same params (key order does not matter) is served from that snippet's own cache, spends no `max_host_calls` slot and no output budget, and still appears in `calls[]` marked `cache_hit: true`; nothing is cached between invocations. The trace itself is bounded at `limits.max_recorded_calls` entries: beyond that the host calls still run and still return, only their trace entries are dropped, and `calls_omitted` reports how many, so a snippet looping one cached call cannot grow the response without limit. `fallow.all(requests)` fans out independent host calls in one go: `requests` is an array of `{ tool, params }` objects whose `tool` is the same wire name `fallow.run` takes, and the return value is an array positionally aligned with it whose elements are `{ ok: true, value }` or `{ ok: false, error }`, so one failing element never hides the others. Every batch element goes through the same tool validation, `root` injection, memoization, shared deadline, and output-byte accounting as a single call, and each element that actually dispatches spends one `max_host_calls` slot. The output budget is shared rather than per element: what is left of `max_output_bytes` is divided evenly across the dispatches a batch makes, so a fan-out reads at most `max_output_bytes` in total. A batch is refused whole, before anything runs, when an element is not an object carrying a `tool` string, when it holds more than `max_host_calls` elements, or when it needs more dispatches than the budget has left. The snippet stays synchronous, with no promises in the sandbox: `fallow.all` blocks until every element has resolved, overlapping the subprocess-backed elements while in-process ones run one at a time, so a fan-out cannot stack in-process analyses whose only stop is cooperative. | Read-only |
| decision_surface | Surface the consequential structural DECISIONS a change embeds, each framed as a judgment question for a human with taste (`fallow decision-surface --format json`). The apex of the review brief and the single call that puts taste-decisions in front of a reviewer; separable and cheap, it runs the same changed-code analysis as the brief, NOT the full project pipeline. Returns `kind: "decision-surface"` with `schema_version`, a ranked `decisions[]` list, an optional `truncated` note, and `signal_count`. Each decision carries a `signal_id` (a deterministic anchor to the fallow-emitted candidate it frames; an agent decision whose `signal_id` fallow did not emit must be REJECTED, this is the anti-hallucination contract), a `category` (EXACTLY the SOLID-3: `coupling-boundary`, `public-api-contract`, `dependency`, nothing else), the framed `question`, the `anchor_file`/`anchor_line`, the `blast` (modules affected beyond the diff) and `consequence` rank, the routed `expert[]` (who to ask) with a `bus_factor_one` flag, and structured `actions[]` (`ask-expert`, `suppress`). The surface is CAPPED to a working-memory-sized handful (4 plus or minus 1, configurable via `max_decisions`, clamped to 3-5); decisions beyond the cap collapse into `truncated`. Every `coupling-boundary` and `public-api-contract` decision is suppressible with a `// fallow-ignore` comment on the anchor file (the `suppress` action carries the paste-ready comment); a `dependency` decision anchors on a `package.json`, which cannot carry a comment, so it has no `suppress` action. Always exits 0 (advisory, never a gate). Use `base` to pick the comparison point (defaults to the git merge-base). Use this to answer "what are the few decisions in this change that actually need human judgment?" rather than scanning the whole diff. | Read-only |
| fallow_explain | Explain one fallow issue type without running analysis. Returns the rule id, name, rationale, worked example, fix guidance, and docs URL as JSON. Use this before applying fixes when an agent or reviewer needs to understand what a finding means. If your client exposes MCP resources, `fallow://explain/{issue_type}` serves the same document as a cacheable resource read. | Read-only |
| feature_flags | Detect feature flag patterns in a TypeScript/JavaScript project. Identifies environment variable flags (process.env.FEATURE_*), SDK calls from common providers, and config object patterns. Returns flag locations, detection confidence, and cross-reference with dead code findings. `retirement: true` adds advisory retirement rows (reasons, git age, evidence). | Read-only |
| find_dupes | Find code duplication across the project. Detects clone groups (identical or similar code blocks) with configurable detection modes and thresholds. Returns clone families with refactoring suggestions. On a Rust root, it runs `cargo fallow dupes` (mode, min_tokens, min_lines, threshold). Each clone_groups[] entry carries a stable `fingerprint` (dup:<id>); pass it to the trace_clone tool to deep-dive that group (locations, an extract-function suggestion with estimated savings, and a best-effort suggested name). Set top=N to show only the N highest-ranked clone groups. Ranking combines token count, occurrence count, and a capped spread boost for distant files or same-file locations. Set group_by to "owner" (CODEOWNERS), "directory", "package" (workspace), or "section" (GitLab CODEOWNERS `[Section]` headers, with `owners` metadata per group) to partition results. Import declarations are excluded from clone detection by default (sorted import blocks are a formatting artifact, not copy-paste); pass ignore_imports=false to count them again. Clone instances omit their verbatim `fragment` text over MCP (it was most of the payload, and `file` plus the line/column range addresses the same code); set include_fragments=true to get it back. explain_skipped only changes the human-format skipped-default-ignores note (human/markdown CLI output); MCP JSON responses stay clean. Supports config, workspace scoping, baseline comparisons, and performance tuning (no_cache, threads). | Action |
| find_similar_code | Find semantically similar functions with Fallow's exact pinned local model. Results are unverified candidates, not probabilities, duplication findings, refactor instructions, or CI gates. Source stays on the local machine. Each candidate carries stable candidate_id and review_key identities, exact locations, reproducible provider/model provenance, completion accounting, and read-only inspect/review actions. The command never downloads a model: if explicit setup has not happened, it returns structured guidance to run `fallow similar-code setup --local`. Use threshold only as a candidate-retrieval cutoff, then call inspect_similar_code before deciding whether two functions are behaviorally equivalent or safe to consolidate. Supports root, config, workspace, changed_since, changed_workspaces, paths, threshold, min_lines, top, no_cache, and threads. Cold local inference has a dedicated 15-minute subprocess window; FALLOW_TIMEOUT_SECS still overrides it when an operator needs a different bound. | Read-only |
Show all 44 toolsShow fewer tools
fix_applyActionApply auto-fixes to the project. Removes unused exports from the public API, may delete dead exported enum declarations, deletes unused dependencies from package.json, removes unused enum members, removes unused pnpm catalog entries (rewriting empty groups to `{}` so pnpm install does not reject null), and appends duplicate-export `ignoreExports` rules to the fallow config file. When no fallow config exists outside a monorepo subpackage, this CREATES `.fallowrc.json` using `fallow init`'s framework-aware scaffolding (`$schema`, `entry`, `ignorePatterns`, framework defaults) and layers the `ignoreExports` rules on top. Inside a monorepo subpackage (workspace marker `pnpm-workspace.yaml` / `package.json#workspaces` / `turbo.json` / `lerna.json` / `rush.json` above the invocation directory) the create-fallback refuses and emits `skip_reason: "monorepo_subpackage"` with a relative `workspace_root` path; the agent should re-run `fallow init` at the workspace root or invoke from there. Set `no_create_config: true` to opt out of the create-fallback entirely (recommended for CI and unattended use); the duplicate-export path is skipped with `skip_reason: "no_create_config"` and source-file edits proceed normally. When a source file's xxh3 content hash at fix time differs from the hash captured during the in-process analysis (parallel editor save, CI rebase, or other tool mutated the file between analysis and write), the per-file fix is skipped with `skip_reason: "content_changed"`; the envelope's top-level `skipped_content_changed` count is incremented and the run exits with code 2 so CI surfaces the mismatch instead of treating the partial run as a clean no-op. When a source file mixes CRLF and bare-LF line endings, the per-file fix is skipped with `skip_reason: "mixed_line_endings"`; the envelope's top-level `skipped_mixed_line_endings` count is incremented and the run exits with code 2. This skip is NOT self-healing: re-running fallow alone does not normalize the file and will loop. The agent must run `dos2unix <path>` (or instruct the user to set `git config core.autocrlf input` and re-checkout) before re-running. When an unused export lives in a test, mock, or fixture directory (`__mocks__`, `e2e`, `e2e-tests`, `cypress`, `playwright`, `examples`, `fixtures`, `__fixtures__`, `evals`, `golden`), or in a file that itself has an unresolved import, its removal is withheld as low confidence because the consumer may be invisible to static analysis (Vitest mock aliases, off-workspace e2e trees, fixture build steps): the per-file fix carries `skip_reason: "low_confidence_off_graph"` or `"low_confidence_unresolved_imports"` and the envelope's top-level `skipped_low_confidence_exports` count is incremented. A finding carrying `reachability_caveats` (a source file was skipped, unreadable, or unparseable, so the reference that would credit it may never have been seen) is withheld the same way, `remove-dependency`, `remove-enum-member` and `remove-class-member` included, under `skip_reason: "low_confidence_incomplete_analysis"` and the counts `skipped_low_confidence_dependencies` and `skipped_low_confidence_members` (the member count covers both kinds; a class-member removal is only ever opened by the type-aware pass, so only members it had approved can be withheld here); read `workspace_diagnostics[]`, resolve those files, and re-run. Unlike the two skips above these are INTENTIONAL: they do NOT change the exit code, and the finding stays reported by `fallow dead-code` for manual confirmation. Writes are batched: each per-file rewrite is staged to a sibling temp file, and the orchestrator promotes the batch only after every stage succeeds, so a single stage failure leaves the project untouched. Files with a UTF-8 BOM are read with the BOM stripped (so line offsets align with the parser) and written with the BOM re-prepended (so Windows-authored files round-trip unchanged); fallow does not add or remove a BOM. This modifies files on disk. Use fix_preview first to review planned changes including any `proposed_diff` and `created_files` fields. Supports workspace scoping and performance tuning (no_cache, threads).
fix_previewRead-onlyPreview auto-fixes without modifying any files. Shows what would be changed: which unused exports would be removed, which unused dependencies would be deleted from package.json, which unused enum members would be removed, which unused pnpm catalog entries would be cleaned up, and which duplicate-export `ignoreExports` rules would be added to the fallow config file. For `add-to-config` actions, each fix entry carries a `proposed_diff` field with the unified-diff preview of the proposed config write. When no fallow config exists outside a monorepo subpackage, fix_apply would CREATE `.fallowrc.json` using `fallow init`'s framework-aware scaffolding (`$schema`, `entry`, `ignorePatterns`, etc.) and layer the `ignoreExports` rules on top; preview entries on that path carry `created_files: [".fallowrc.json"]`. Set `no_create_config: true` to skip the config-creation path with `skip_reason: "no_create_config"`; source-file previews are unaffected. When a source file's xxh3 content hash at preview time differs from the hash captured during the in-process analysis (a concurrent source edit), the per-file entry is emitted with `skip_reason: "content_changed"` and the envelope's top-level `skipped_content_changed` count is incremented; re-run after refreshing analysis. When a source file mixes CRLF and bare-LF line endings, the per-file entry is emitted with `skip_reason: "mixed_line_endings"` and the envelope's top-level `skipped_mixed_line_endings` count is incremented; this skip is NOT self-healing because re-running fallow alone does not normalize the file. The agent must run `dos2unix <path>` (or instruct the user to set `git config core.autocrlf input` and re-checkout) before re-running. When an unused export lives in a test, mock, or fixture directory, or in a file that itself has an unresolved import, its removal is withheld as low confidence because the consumer may be invisible to static analysis: the per-file entry carries `skip_reason: "low_confidence_off_graph"` or `"low_confidence_unresolved_imports"` and the envelope's top-level `skipped_low_confidence_exports` count is incremented. A finding carrying `reachability_caveats` (a file the run did not fully analyze may hold the crediting reference) is withheld the same way, `remove-dependency`, `remove-enum-member` and `remove-class-member` too, under `skip_reason: "low_confidence_incomplete_analysis"`, counted by `skipped_low_confidence_dependencies` and `skipped_low_confidence_members` (which counts both member kinds). Unlike the two skips above these are INTENTIONAL and do NOT change the exit code; the finding stays reported by `fallow dead-code` for manual confirmation. Supports workspace scoping and performance tuning (no_cache, threads).
get_blast_radiusRead-onlyReturn first-class blast-radius context alongside local runtime coverage. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.blast_radius`, which contains stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, and low/medium/high risk bands. This blast-radius signal augments context only: it scores the RISK of changing a function. It MUST NOT gate `safe_to_delete` or a confidence score (a function having callers does not make it 'keep'); only the three-state runtime tracking signal (called / never_called / untracked) can issue a deletion verdict.
get_cleanup_candidatesRead-onlyReturn cleanup candidates grounded in local runtime coverage. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.findings` for `safe_to_delete`, `review_required`, `low_traffic`, and `coverage_unavailable` verdicts.
get_cloud_deployment_changesRead-onlyRead how production behavior changed between two deployments from Fallow Cloud. Backed by `fallow coverage deployment-changes --format json`. `repo` is required; `sha` defaults to `HEAD` of `root`, `base` to the previous deployment with production runtime. Each function has a change kind (`new_called`, `new_not_called`, `heated_up`, `cooled_down`, `stopped`, `unchanged`); `change`, `limit` and `cursor` filter and page. Read `comparable` first. Context only, never a deletion verdict. Needs `FALLOW_API_KEY` in the server environment.
get_cloud_review_packetRead-onlyRead production facts for a few changed files or functions from Fallow Cloud, with no full pull and no local analysis. Backed by `fallow coverage review-packet --format json`. `repo` is required; pass `files` and/or `functions` (`{file, name, line?}`), or neither to send the files changed against `base`. Rows carry `repo_path`, `tracking_state` (current deployment) and `period_tracking_state` (whole period); `evidence_window` is the real evidence span. A current `never_called` with `period_tracking_state: called` is not dead code. Needs `FALLOW_API_KEY` in the server environment; see `fallow://tools/get_cloud_review_packet`.
get_cloud_runtime_contextRead-onlyPull runtime coverage for a repository from Fallow Cloud instead of a local V8 or Istanbul dump, and return the same `runtime_coverage` block the local runtime-coverage tools return. Backed by `fallow coverage analyze --cloud --format json`: Fallow Cloud is asked for the repository's runtime facts over the requested window, and the answer is joined against this project's static analysis, so `root` must be a checkout of the same repository. It makes a network call and needs a Fallow Cloud account (for a scoped question, get_cloud_review_packet is smaller); cloud pull is a Team-tier feature, and a repository your org cannot see is refused by the cloud rather than returned empty. The API key is never a parameter: the CLI reads `FALLOW_API_KEY` in the server's own environment, else the key that `fallow cloud login` stored. A call without a key stops before the analysis, with `isError`, `exit_code: 2`, and `code: "cloud_api_key_missing"`. `repo` (`owner/repo`) is required. `project_id`, `period_days` (1-90, default 30), `environment`, and `commit_sha` narrow what the cloud returns; `production`, `top`, and `min_invocations_hot` behave as they do on check_runtime_coverage. Read `runtime_coverage.findings` for `safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable` verdicts, `runtime_coverage.hot_paths` for production hot paths, `runtime_coverage.blast_radius` and `runtime_coverage.importance` for review context that never gates a deletion verdict, `runtime_coverage.summary.data_source` to confirm the evidence is `cloud`, and `runtime_coverage.warnings` for the codes that explain a thin answer (`no_runtime_data`, `cloud_functions_unmatched`).
get_hot_pathsRead-onlyReturn production hot paths from a local V8 or Istanbul runtime coverage dump. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.hot_paths`, which is sorted by percentile and invocation count. Each entry carries `start_line` and `end_line` so agents can match the function's full body against a PR diff. Use `top` to cap the returned hot paths. Each hot path with a static counterpart also carries `optimization_target`: `cost_score` (invocations multiplied by the per-call cost), `cost_basis` (`inner_iterations` from V8 block counts, else `cognitive`), `cognitive`, `cyclomatic`, `line_count`, and `inner_iterations_per_call`. To pick speed work, sort by `cost_basis` (`inner_iterations` first), then by `cost_score` descending: scores on different bases do not compare. The hot paths are selected and capped by invocations, so a function with fewer calls but more work per call can be absent. Use `get_importance` to judge the risk of a change. Environment-driven scoping: if `FALLOW_DIFF_FILE` (path to a unified diff) is set in the agent's process env, hot paths are narrowed to functions whose `[start_line, end_line]` overlaps an added hunk; a file the diff touched but with no added lines (deletion-only / pure-rename) drops its hot paths rather than falling through to changed-since file-level matching. `FALLOW_CHANGED_SINCE` (git ref) covers the fallback case (file-level match for files NOT in the diff at all). Unset both for project-wide hot paths.
get_importanceRead-onlyReturn first-class production-importance context from local runtime coverage plus static health signals. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.importance`, which contains stable `fallow:importance:<hash>` IDs, invocations, cyclomatic complexity, owner count, a 0-100 score, and a templated reason. This importance signal augments context only. It MUST NOT gate `safe_to_delete` or a confidence score (a high or low score never decides deletion); only the three-state runtime tracking signal (called / never_called / untracked) can issue a deletion verdict.
get_token_blast_radiusRead-onlyReturn design-token blast radius from static analysis. Runs `fallow health --css --format json`; agents should read `css_analytics.token_consumers`, a reverse index keyed by each token of its defining site plus a `consumer_count` and a capped located `consumers[]` sample of `{path,line,kind}`. Covers TWO token origins, disambiguated by token shape and consumer `kind`: Tailwind v4 `@theme` tokens (`token` is the `--`-prefixed custom property like `--color-brand`; `kind` in `theme-var` / `css-var` / `utility` / `apply`) AND CSS-in-JS token definitions (StyleX `defineVars` / `unstable_defineVarsNested`, vanilla-extract `createTheme` / `createThemeContract` / `createGlobalTheme`; `token` is the binding-qualified dotted access path like `vars.color.primary`, `namespace` is the defining binding, member reads use `js-member`, and StyleX theme-group calls use `js-call`). StyleX theme-group calls credit the complete resolved contract, including partial overrides and empty reset themes. The index is empty or absent on projects using neither. `consumer_count` is a static lower bound because computed class names, dynamic token structures, unresolved imports, and computed token access cannot always be counted. For Tailwind a `consumer_count` of 0 mirrors the unused-theme-token population (the dead-token verdict stays on `unused_theme_tokens` via check_health); CSS-in-JS tokens have no corroborating dead-token finding, so treat a CSS-in-JS 0 as weaker. Use this tool to scope the impact of editing or renaming a token, not to decide deletion.
guardRead-onlyReport the architecture rules that apply to specific files before editing them: the file's boundary zone, which zones it may import from (same-zone imports are always allowed), forbidden call patterns, and every rule-pack policy in scope with its severity and suppression token. Works for files that do not exist yet, so it can be called before writing new code. A path that matches no configured zone returns an empty rule set rather than an error. It reads config only and runs no analysis; to find existing violations use `analyze` or `list_boundaries`.
impactRead-onlyRead fallow's local value-tracking report. Runs NO analysis: it reads a per-project history file from the user's private config dir (never inside the repo), answering "what has fallow done for me over time" rather than "what is wrong now" (for live findings use analyze / audit / check_health). LOCAL-DEV ONLY: history accrues only on a developer's machine (local dev, or a persistent pre-commit gate); fallow never records in CI, so in CI / ephemeral runners this returns an empty report (enabled:false) and must NOT be used as a CI metric. Always returns a populated JSON object (never {}): branch on `enabled` and `enabled_source` (`project` = an explicit per-repo enable/disable, `user` = the user-global default, `default` = off). When `enabled:false`, use `explicit_decision` to decide what to say: `explicit_decision:false` means tracking was never set up here, so recommend the user run `fallow impact enable` (do not run it yourself); `explicit_decision:true` means the user deliberately disabled it here, so do NOT nag. Also branch on `record_count` (0 with enabled:true = set up but awaiting gate runs). When enabled with history it returns `surfacing` (issue counts from the most recent recorded run), `trend` (count delta vs the previous run; improving/declining/stable on the wire), `containment_count` + `recent_containment` (pre-commit gate runs that blocked a commit then later cleared), and a short-SHA `latest_git_sha` for correlation. On fallow with impact v1.5+ the report also carries `resolved_total` / `suppressed_total` / `recent_resolved` / `attribution_active`, crediting findings fallow saw genuinely fixed (code removed or refactored) and never counting a fallow-ignore suppression as a win; older fallow binaries omit these fields. On fallow with impact v1.6+ the report also carries `project_surfacing` / `project_trend`: a WHOLE-PROJECT view from the last full `fallow` run (additive optional under the same `schema_version`, omitted by older binaries). Treat changed-file `surfacing` as the actionable count for the current change and `project_surfacing` as whole-repo context, not a to-do list. Read-only; the mutating `fallow impact enable` / `disable` / `default` lifecycle is intentionally not exposed over MCP.
impact_allRead-onlyRoll EVERY tracked fallow project on this machine into one cross-repo value report (`fallow impact --all --format json`). Runs NO analysis: it reads the per-project history files in the user's private config dir, answering "what has fallow done for me across all my repos". Use this instead of `impact` when the agent wants a portfolio view rather than one repo; use `impact` (with `root`) for a single project. Returns `kind: "impact-cross-repo"` with `schema_version` "2", `project_count` (stores enumerated), `tracked_count` (projects with recorded history shown as rows), `unreadable_count` (corrupt/newer-schema stores skipped), a `totals` roll-up (resolved/contained/surfacing summed over ALL tracked projects, including repos since deleted from disk), and a `projects[]` array. Each project row carries a hashed `project_key` (never a filesystem path, and the only always-present identifier), an optional human `label` (the repo's directory basename; omitted on rows recorded by older fallow binaries, so fall back to `project_key` when `label` is null/absent), `last_recorded`, and a nested per-project `report`. Privacy: the aggregate exposes NO absolute paths, only the hash key plus the basename label. Projects that are enabled but have no recorded history yet are counted in `project_count` but excluded from `projects[]` rows. `sort` orders rows (`recent` default / `resolved` / `contained` / `name`); `limit` caps the rows returned while `totals` still reflect every tracked project. LOCAL-DEV ONLY: history accrues only on developer machines (fallow never records in CI), so in CI / ephemeral runners this returns zero tracked projects and must NOT be used as a CI metric. When `project_count` is 0, no project on this machine has tracking enabled yet: in a local dev session suggest the user run `fallow impact enable` in a repo they care about (do not run it yourself), but in CI stay silent because zero is the expected, non-actionable result. Read-only; the mutating enable / disable / default / reset lifecycle is intentionally not exposed over MCP.
impact_closureRead-onlyTrace a file's impact closure. Runs `fallow dead-code --impact-closure <path> --format json --quiet` and returns the transitive affected-but-not-in-diff set plus coordination gaps for file-contract consumers. Evidence for review planning, not proof that affected files are wrong. Gaps carry `search_visibility`; see fallow://tools/impact_closure. Supports root, config, production, workspace, no_cache, and threads.
inspect_similar_codeRead-onlyInspect one exact unverified candidate from find_similar_code without rerunning provider retrieval or global ranking. Pass candidate_id plus a bounded snapshot containing the unchanged discovery schema_version, generation, selected candidate, completion, and diagnostics fields. Current source is re-extracted and both source_sha256 values must still match before bounded source windows, syntactic behavior hints, graph relationships, reachability, callers/callees, ownership, churn, tests, and deterministic clone overlap are returned. Stale source fails closed. Missing evidence is represented explicitly, never inferred. This remains read-only and never declares behavioral equivalence or refactor safety.
inspect_targetRead-onlyInspect one file or exported symbol and return one typed evidence bundle. Address a file with target={type:"file", file:"src/a.ts"}; address a symbol with target={type:"symbol", file:"src/a.ts", export_name:"foo"}. Composes existing read-only analysis systems only: trace_file, trace_export for symbols, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, security candidates scoped to the file, and the impact closure for the file (the transitive affected-but-not-in-diff set plus the coordination gap: modules that consume this file's contract but are not shown alongside it; a syntactic attention pointer, not a correctness proof). Set include_churn=true to attach target-level git churn from the in-process health hotspot subsystem; it is off by default, and missing git history is reported explicitly. Set cloud=true on a file target to attach the `cloud` evidence section of `fallow inspect --cloud` (Fallow Cloud production data per local function); repo selects the `owner/repo`. The key comes from the server environment or `fallow cloud login`, never from the call. The section status is ok, no_key, plan_required, unavailable, or untracked, and a status other than ok does not fail the call; see fallow://tools/inspect_target. Set format="compact" to get the plain text of `fallow inspect --format compact` (about 1 KB, no JSON) instead of the bundle. production is forwarded only to child analyses that support it: trace, dead-code, and health. Symbol targets include file-scoped evidence with explicit scope fields because file:line enclosing-symbol mapping is a follow-up. This bundled query runs independent evidence analyses in parallel; large repositories can exceed the default 120s subprocess timeout, so raise FALLOW_TIMEOUT_SECS when needed.
list_boundariesRead-onlyList architecture boundary zones and access rules configured for the project. Returns zone definitions (name, glob patterns, matched file count), access rules (which zones may import from which), and `logical_groups[]` (one entry per pre-expansion `autoDiscover` zone, surfacing the user-authored parent name, verbatim `auto_discover` paths, discovered `children`, `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule`, optional `fallback_zone` cross-reference for the Bulletproof case, optional `merged_from` when the parent name was declared multiple times, optional `original_zone_root` echo for monorepo subtree scopes, and optional `child_source_indices` attribution when multiple paths were authored). If boundaries are not configured, returns {"configured": false}; in that case, boundary violation checks will find no issues and can be skipped. Use this to understand the project's architecture constraints before running analysis.
list_suppressionsRead-onlyList active fallow-ignore suppression markers grouped per file with line, kind, level, reason, and a stale cross-reference. Runs `fallow suppressions --format json` and returns the `kind: "suppression-inventory"` envelope verbatim (a `summary` roll-up plus `files[]`); a governance surface for distrusting a clean verdict by seeing what is suppressed, not a gate, so it always exits 0 even when suppressions exist. Scope with `workspace`, `changed_since` (the natural pull-request review scope), or repeated `file` entries. Read-only. It runs a full analysis to populate the inventory, so on large repos raise `FALLOW_TIMEOUT_SECS` above the default 120s if it times out.
mutation_inspectRead-onlyInspect one mutant of a saved `fallow mutation` JSON report (default: the report that the last run saved in the Fallow cache): original and mutated code, covering tests, and the killing test. A source_sha256 mismatch with the current file gives a stale status, not a wrong answer. This tool never runs tests. A report needs the CLI command `fallow mutation`, which executes the project's tests, so ask your host first. On a Rust root, it reads only the cached map of `cargo fallow mutants`.
mutation_planRead-onlyPlan mutation testing and return the plan envelope: each mutant's id, position, operator, disposition, and static test files, plus a source_sha256 per file. Scope: changed code by default, or `all`, or `paths`. This tool never runs tests. Running the mutants needs the CLI command `fallow mutation`, which executes the project's tests, so ask your host first. On a Rust root, it runs `cargo fallow mutants --list` for one `package`, by default all of it.
mutation_tasksRead-onlyList the open tasks of a saved `fallow mutation` JSON report as one batch (default: the report that the last run saved in the Fallow cache). A task is a survived or no_coverage mutant: a small change to the code that no test detected. Each task has the mutant_id, file, line, function, operator, status, the source lines before and after the change (original_lines, mutated_lines), and the covering test files. After `fallow mutation --record-args values`, a task can have witness; only witness.verdict witness gives a test input (args, original, mutant), and a verdict is never equivalent; see fallow://tools/mutation_tasks. Write tests that pass on the current code and fail on the changed code; one test can cover several tasks, and a task that no input can detect can be skipped. A task whose file changed after the report is stale and has no code. This tool never runs tests. A report needs the CLI command `fallow mutation`, which executes the project's tests, so ask your host first. A Rust root is not supported yet.
project_infoRead-onlyGet project metadata: active framework plugins, discovered source files, and detected entry points. Useful for understanding how fallow sees the project before running analysis. Supports performance tuning (no_cache, threads).
recommendRead-onlyRecommend a project-tailored fallow config for an agent to author (`fallow recommend --format json`). Read-only: runs project detection (frameworks, workspace layout, tooling) but NOT the analysis pipeline, and always exits 0. Returns `{detected, proposed_config, decisions[]}`. `detected` is what fallow saw; `proposed_config` is a safe starting config that BOTH validates against config-schema AND loads through fallow's real config loader; `decisions[]` is THREE-valued: `auto` (decided from unambiguous detection and applied silently), `default` (a disclosed, overridable default carrying a quantified `rationale`), and `taste` (a genuinely subjective choice surfaced as an open, AskUserQuestion-shaped `question` with 2-4 options and NO baked-in recommended answer, per fallow's taste-ownership principle). Framework rules are never uniformly auto-enabled on a heterogeneous monorepo; entry points beyond the obvious fall back to fallow's own defaults rather than a baked-in guess. Zero-config is a valid stop: the proposed config is an optional refinement over already-strong defaults, not a requirement. Pair with `fallow schema` (the capability manifest carrying per-rule default severity + opt-in) for the full cold-start discover -> recommend -> ask-taste -> author sequence. Honors `root`.
security_candidatesRead-onlyReturns unverified security candidates, not confirmed vulnerabilities. Runs `fallow security --format json` and returns `kind: "security"`, `security_findings`, category, CWE, severity, evidence, structural trace, reachability ranking context, blind-spot counters, and optional unresolved-callee diagnostics for agent verification. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` record (`source_kind`, the untrusted-input kind as a stable catalogue id or null; a self-contained `sink` with the captured callee and optional `url_shape` for URL candidates; and the `boundary` crossed), an optional `taint_flow` source-to-sink triple (present only when an untrusted source is import-reachable to the sink), a `finding_id` (the SARIF fingerprint), and a `stable_finding_id` that survives line moves, for verdicts. Set `surface: true` to include the top-level `attack_surface` inventory with source-to-sink paths and defensive-boundary verification prompts. Set gate to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires changed_since. There is no `impact` field: deciding exploitability is the agent's job. `reachability.untrusted_source_trace` is module-level context only and does not prove value flow. `reachability.taint_confidence` tiers reachable candidates as `arg-level` or `module-level`; tier from that field rather than evidence prose. Verify trace, reachability context, severity, and evidence before editing code or presenting a finding as a vulnerability. Supports root, config, workspace, changed_since, paths, changed_workspaces, surface, gate, no_cache, and threads. Use paths for the agent edit loop: it forwards to `fallow security --file` and scopes returned candidates to matching finding anchors, trace hops, untrusted-source reachability trace hops, or unresolved-callee diagnostics while cached analysis keeps reruns fast. The CLI also honors `FALLOW_DIFF_FILE` from the MCP server environment for line-level diff scoping. Security analysis can exceed the default 120s subprocess timeout on large repos; raise `FALLOW_TIMEOUT_SECS` accordingly.
symbol_impactRead-onlyReturn exact-symbol consumers, transitive affected files, and targeted tests for a TypeScript export or exported class method. Select either export_name, or both class_name and member_name. The result is advisory project-impact evidence and does not duplicate tsc or Oxlint diagnostics.
trace_cloneRead-onlyDeep-dive a duplicate-code clone group. Address it either by a source location (file + line) or by a stable fingerprint (fingerprint="dup:<id>" from a find_dupes clone_groups[].fingerprint, usually dup:<8hex> and widened only on rare report collisions). Returns the matched clone instance, every sibling clone group / location, plus per group an extract-function suggestion with estimated line savings and a best-effort suggested_name (the field is omitted, not null, when there is no confident name, so branch on key presence; advisory, verify before applying, never auto-apply). Provide exactly one addressing form. Import declarations are excluded from clone detection by default; pass ignore_imports=false to count them again. Use after find_dupes when consolidating duplication and you need exact sibling locations and a refactor target.
trace_dependencyRead-onlyTrace where a dependency is used. Returns which files import the package, which imports are type-only, whether the package is referenced from package.json scripts or CI configs (`used_in_scripts`), and whether the dependency is used at all (`is_used` accounts for imports, script usage, and the used packages that list it as a peer (`peer_of`), matching the unused-deps detector). `unused_in` names each manifest that the detector still flags, because an import credits only the nearest manifest that installs the package. Set `usage`, `specifiers`, `sites` (paged with `limit` and `cursor`) or `closure_depth` to add a `usage` object: per imported name, the file, call and unresolved counts, one hop through project wrappers, and the usage sites. Useful before removing a dependency, moving it between dependencies and devDependencies, or migrating its API.
trace_errorRead-onlyResolve a runtime stack trace against the project graph: paste the trace text in `trace` and get, per frame, which definitions in THIS project the frame's identifier names. The verb for "my service threw this in production, what code is that". Returns `kind: "trace-error"` with retained frames in input order, each carrying an `origin` (`in_project`, `node_modules`, `out_of_corpus`) and a `resolution` (`resolved`, `ambiguous`, `not_found`, `not_attempted`), plus `candidates[]` naming the file, symbol, member and declaration line. It is built to refuse overclaiming: a frame matching several definitions is `ambiguous`, with bounded candidates and `candidates_omitted` instead of a preferred match, a frame the graph was never asked about is `not_attempted` rather than a softer `not_found`, and `line_mismatch` marks a resolved frame whose own line sits at a different declaration, so a name-only match is visible instead of implied. `counts` closes over the reported frames and publishes `frames_omitted` and `unparsed_lines`, so a capped or unreadable input cannot look complete. No source maps are read: a frame inside built output says so instead of being rebound through a map that may be stale, so give it a trace from unbundled source or the source paths a map already resolved. The RESOLUTION outcome never fails the call: a trace in which nothing resolves is an ANSWER, and exits 0. A refused input still is a refusal: an empty or oversized `trace` returns `isError` with `FALLOW_INVALID_TRACE_OPTIONS`.
trace_exportRead-onlyTrace why an export is considered used or unused. Returns file reachability, entry-point status, direct references, re-export chains, the framework plugin rules that mark the export as used (`plugin_credits`), and a concise reason string. If export_name is a class / enum / store MEMBER rather than a top-level export, returns a member trace instead (carrying member_name, member_kind, owner_export, owner_is_used) that reports the owning class's reachability and usage plus a pointer to the matching --unused-<kind>-members command, so a class-member finding can be debugged too. Use this when an agent needs evidence before deleting or rewriting a supposedly unused export or class member. References carry `search_visibility`; see fallow://tools/trace_export. When the config or FALLOW_TYPE_AWARE turns type-aware analysis on, the trace also carries a `semantic` block with checker-backed evidence, as `fallow dead-code --trace` does.
trace_fileRead-onlyTrace a file's graph context. Returns whether the file is reachable or an entry point, what it exports, what it imports, what imports it, and which re-exports it declares. Use this to understand whether a file is isolated, barrel-only, or imported by live entry points.
trace_import_pathRead-onlyShortest import path from one module to another, hop by hop with each hop's import line and whether the hop is type-only. Unreachable answers `reachable: false`; the same module answers `reachable: true`. Both report `hops: 0`, so branch on `reachable`, not the count. Exact project paths take priority; ambiguous abbreviations are refused. Use trace_file for one file's direct neighbours.
trace_symbolRead-onlyTrace an exact TypeScript symbol with checker-backed references, namespace identity, aliases, and re-export hops. Root trace fields preserve syntactic context; treat `semantic.references`, `semantic.status`, and `semantic.identity` as the authoritative exact evidence. The proof covers only the lane named by `semantic.target.namespace`, so a root trace that lists a reference the proof does not is wider evidence rather than stale. This is project-wide evidence for Fallow decisions, not a compiler-diagnostic or lint-rule surface.
| fix_apply | Apply auto-fixes to the project. Removes unused exports from the public API, may delete dead exported enum declarations, deletes unused dependencies from package.json, removes unused enum members, removes unused pnpm catalog entries (rewriting empty groups to `{}` so pnpm install does not reject null), and appends duplicate-export `ignoreExports` rules to the fallow config file. When no fallow config exists outside a monorepo subpackage, this CREATES `.fallowrc.json` using `fallow init`'s framework-aware scaffolding (`$schema`, `entry`, `ignorePatterns`, framework defaults) and layers the `ignoreExports` rules on top. Inside a monorepo subpackage (workspace marker `pnpm-workspace.yaml` / `package.json#workspaces` / `turbo.json` / `lerna.json` / `rush.json` above the invocation directory) the create-fallback refuses and emits `skip_reason: "monorepo_subpackage"` with a relative `workspace_root` path; the agent should re-run `fallow init` at the workspace root or invoke from there. Set `no_create_config: true` to opt out of the create-fallback entirely (recommended for CI and unattended use); the duplicate-export path is skipped with `skip_reason: "no_create_config"` and source-file edits proceed normally. When a source file's xxh3 content hash at fix time differs from the hash captured during the in-process analysis (parallel editor save, CI rebase, or other tool mutated the file between analysis and write), the per-file fix is skipped with `skip_reason: "content_changed"`; the envelope's top-level `skipped_content_changed` count is incremented and the run exits with code 2 so CI surfaces the mismatch instead of treating the partial run as a clean no-op. When a source file mixes CRLF and bare-LF line endings, the per-file fix is skipped with `skip_reason: "mixed_line_endings"`; the envelope's top-level `skipped_mixed_line_endings` count is incremented and the run exits with code 2. This skip is NOT self-healing: re-running fallow alone does not normalize the file and will loop. The agent must run `dos2unix <path>` (or instruct the user to set `git config core.autocrlf input` and re-checkout) before re-running. When an unused export lives in a test, mock, or fixture directory (`__mocks__`, `e2e`, `e2e-tests`, `cypress`, `playwright`, `examples`, `fixtures`, `__fixtures__`, `evals`, `golden`), or in a file that itself has an unresolved import, its removal is withheld as low confidence because the consumer may be invisible to static analysis (Vitest mock aliases, off-workspace e2e trees, fixture build steps): the per-file fix carries `skip_reason: "low_confidence_off_graph"` or `"low_confidence_unresolved_imports"` and the envelope's top-level `skipped_low_confidence_exports` count is incremented. A finding carrying `reachability_caveats` (a source file was skipped, unreadable, or unparseable, so the reference that would credit it may never have been seen) is withheld the same way, `remove-dependency`, `remove-enum-member` and `remove-class-member` included, under `skip_reason: "low_confidence_incomplete_analysis"` and the counts `skipped_low_confidence_dependencies` and `skipped_low_confidence_members` (the member count covers both kinds; a class-member removal is only ever opened by the type-aware pass, so only members it had approved can be withheld here); read `workspace_diagnostics[]`, resolve those files, and re-run. Unlike the two skips above these are INTENTIONAL: they do NOT change the exit code, and the finding stays reported by `fallow dead-code` for manual confirmation. Writes are batched: each per-file rewrite is staged to a sibling temp file, and the orchestrator promotes the batch only after every stage succeeds, so a single stage failure leaves the project untouched. Files with a UTF-8 BOM are read with the BOM stripped (so line offsets align with the parser) and written with the BOM re-prepended (so Windows-authored files round-trip unchanged); fallow does not add or remove a BOM. This modifies files on disk. Use fix_preview first to review planned changes including any `proposed_diff` and `created_files` fields. Supports workspace scoping and performance tuning (no_cache, threads). | Action |
| fix_preview | Preview auto-fixes without modifying any files. Shows what would be changed: which unused exports would be removed, which unused dependencies would be deleted from package.json, which unused enum members would be removed, which unused pnpm catalog entries would be cleaned up, and which duplicate-export `ignoreExports` rules would be added to the fallow config file. For `add-to-config` actions, each fix entry carries a `proposed_diff` field with the unified-diff preview of the proposed config write. When no fallow config exists outside a monorepo subpackage, fix_apply would CREATE `.fallowrc.json` using `fallow init`'s framework-aware scaffolding (`$schema`, `entry`, `ignorePatterns`, etc.) and layer the `ignoreExports` rules on top; preview entries on that path carry `created_files: [".fallowrc.json"]`. Set `no_create_config: true` to skip the config-creation path with `skip_reason: "no_create_config"`; source-file previews are unaffected. When a source file's xxh3 content hash at preview time differs from the hash captured during the in-process analysis (a concurrent source edit), the per-file entry is emitted with `skip_reason: "content_changed"` and the envelope's top-level `skipped_content_changed` count is incremented; re-run after refreshing analysis. When a source file mixes CRLF and bare-LF line endings, the per-file entry is emitted with `skip_reason: "mixed_line_endings"` and the envelope's top-level `skipped_mixed_line_endings` count is incremented; this skip is NOT self-healing because re-running fallow alone does not normalize the file. The agent must run `dos2unix <path>` (or instruct the user to set `git config core.autocrlf input` and re-checkout) before re-running. When an unused export lives in a test, mock, or fixture directory, or in a file that itself has an unresolved import, its removal is withheld as low confidence because the consumer may be invisible to static analysis: the per-file entry carries `skip_reason: "low_confidence_off_graph"` or `"low_confidence_unresolved_imports"` and the envelope's top-level `skipped_low_confidence_exports` count is incremented. A finding carrying `reachability_caveats` (a file the run did not fully analyze may hold the crediting reference) is withheld the same way, `remove-dependency`, `remove-enum-member` and `remove-class-member` too, under `skip_reason: "low_confidence_incomplete_analysis"`, counted by `skipped_low_confidence_dependencies` and `skipped_low_confidence_members` (which counts both member kinds). Unlike the two skips above these are INTENTIONAL and do NOT change the exit code; the finding stays reported by `fallow dead-code` for manual confirmation. Supports workspace scoping and performance tuning (no_cache, threads). | Read-only |
| get_blast_radius | Return first-class blast-radius context alongside local runtime coverage. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.blast_radius`, which contains stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, and low/medium/high risk bands. This blast-radius signal augments context only: it scores the RISK of changing a function. It MUST NOT gate `safe_to_delete` or a confidence score (a function having callers does not make it 'keep'); only the three-state runtime tracking signal (called / never_called / untracked) can issue a deletion verdict. | Read-only |
| get_cleanup_candidates | Return cleanup candidates grounded in local runtime coverage. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.findings` for `safe_to_delete`, `review_required`, `low_traffic`, and `coverage_unavailable` verdicts. | Read-only |
| get_cloud_deployment_changes | Read how production behavior changed between two deployments from Fallow Cloud. Backed by `fallow coverage deployment-changes --format json`. `repo` is required; `sha` defaults to `HEAD` of `root`, `base` to the previous deployment with production runtime. Each function has a change kind (`new_called`, `new_not_called`, `heated_up`, `cooled_down`, `stopped`, `unchanged`); `change`, `limit` and `cursor` filter and page. Read `comparable` first. Context only, never a deletion verdict. Needs `FALLOW_API_KEY` in the server environment. | Read-only |
| get_cloud_review_packet | Read production facts for a few changed files or functions from Fallow Cloud, with no full pull and no local analysis. Backed by `fallow coverage review-packet --format json`. `repo` is required; pass `files` and/or `functions` (`{file, name, line?}`), or neither to send the files changed against `base`. Rows carry `repo_path`, `tracking_state` (current deployment) and `period_tracking_state` (whole period); `evidence_window` is the real evidence span. A current `never_called` with `period_tracking_state: called` is not dead code. Needs `FALLOW_API_KEY` in the server environment; see `fallow://tools/get_cloud_review_packet`. | Read-only |
| get_cloud_runtime_context | Pull runtime coverage for a repository from Fallow Cloud instead of a local V8 or Istanbul dump, and return the same `runtime_coverage` block the local runtime-coverage tools return. Backed by `fallow coverage analyze --cloud --format json`: Fallow Cloud is asked for the repository's runtime facts over the requested window, and the answer is joined against this project's static analysis, so `root` must be a checkout of the same repository. It makes a network call and needs a Fallow Cloud account (for a scoped question, get_cloud_review_packet is smaller); cloud pull is a Team-tier feature, and a repository your org cannot see is refused by the cloud rather than returned empty. The API key is never a parameter: the CLI reads `FALLOW_API_KEY` in the server's own environment, else the key that `fallow cloud login` stored. A call without a key stops before the analysis, with `isError`, `exit_code: 2`, and `code: "cloud_api_key_missing"`. `repo` (`owner/repo`) is required. `project_id`, `period_days` (1-90, default 30), `environment`, and `commit_sha` narrow what the cloud returns; `production`, `top`, and `min_invocations_hot` behave as they do on check_runtime_coverage. Read `runtime_coverage.findings` for `safe_to_delete` / `review_required` / `low_traffic` / `coverage_unavailable` verdicts, `runtime_coverage.hot_paths` for production hot paths, `runtime_coverage.blast_radius` and `runtime_coverage.importance` for review context that never gates a deletion verdict, `runtime_coverage.summary.data_source` to confirm the evidence is `cloud`, and `runtime_coverage.warnings` for the codes that explain a thin answer (`no_runtime_data`, `cloud_functions_unmatched`). | Read-only |
| get_hot_paths | Return production hot paths from a local V8 or Istanbul runtime coverage dump. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.hot_paths`, which is sorted by percentile and invocation count. Each entry carries `start_line` and `end_line` so agents can match the function's full body against a PR diff. Use `top` to cap the returned hot paths. Each hot path with a static counterpart also carries `optimization_target`: `cost_score` (invocations multiplied by the per-call cost), `cost_basis` (`inner_iterations` from V8 block counts, else `cognitive`), `cognitive`, `cyclomatic`, `line_count`, and `inner_iterations_per_call`. To pick speed work, sort by `cost_basis` (`inner_iterations` first), then by `cost_score` descending: scores on different bases do not compare. The hot paths are selected and capped by invocations, so a function with fewer calls but more work per call can be absent. Use `get_importance` to judge the risk of a change. Environment-driven scoping: if `FALLOW_DIFF_FILE` (path to a unified diff) is set in the agent's process env, hot paths are narrowed to functions whose `[start_line, end_line]` overlaps an added hunk; a file the diff touched but with no added lines (deletion-only / pure-rename) drops its hot paths rather than falling through to changed-since file-level matching. `FALLOW_CHANGED_SINCE` (git ref) covers the fallback case (file-level match for files NOT in the diff at all). Unset both for project-wide hot paths. | Read-only |
| get_importance | Return first-class production-importance context from local runtime coverage plus static health signals. Pass `coverage` as a V8 coverage directory, single V8 JSON file, or Istanbul `coverage-final.json`. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring requires an active license. Returns the standard health JSON; agents should read `runtime_coverage.importance`, which contains stable `fallow:importance:<hash>` IDs, invocations, cyclomatic complexity, owner count, a 0-100 score, and a templated reason. This importance signal augments context only. It MUST NOT gate `safe_to_delete` or a confidence score (a high or low score never decides deletion); only the three-state runtime tracking signal (called / never_called / untracked) can issue a deletion verdict. | Read-only |
| get_token_blast_radius | Return design-token blast radius from static analysis. Runs `fallow health --css --format json`; agents should read `css_analytics.token_consumers`, a reverse index keyed by each token of its defining site plus a `consumer_count` and a capped located `consumers[]` sample of `{path,line,kind}`. Covers TWO token origins, disambiguated by token shape and consumer `kind`: Tailwind v4 `@theme` tokens (`token` is the `--`-prefixed custom property like `--color-brand`; `kind` in `theme-var` / `css-var` / `utility` / `apply`) AND CSS-in-JS token definitions (StyleX `defineVars` / `unstable_defineVarsNested`, vanilla-extract `createTheme` / `createThemeContract` / `createGlobalTheme`; `token` is the binding-qualified dotted access path like `vars.color.primary`, `namespace` is the defining binding, member reads use `js-member`, and StyleX theme-group calls use `js-call`). StyleX theme-group calls credit the complete resolved contract, including partial overrides and empty reset themes. The index is empty or absent on projects using neither. `consumer_count` is a static lower bound because computed class names, dynamic token structures, unresolved imports, and computed token access cannot always be counted. For Tailwind a `consumer_count` of 0 mirrors the unused-theme-token population (the dead-token verdict stays on `unused_theme_tokens` via check_health); CSS-in-JS tokens have no corroborating dead-token finding, so treat a CSS-in-JS 0 as weaker. Use this tool to scope the impact of editing or renaming a token, not to decide deletion. | Read-only |
| guard | Report the architecture rules that apply to specific files before editing them: the file's boundary zone, which zones it may import from (same-zone imports are always allowed), forbidden call patterns, and every rule-pack policy in scope with its severity and suppression token. Works for files that do not exist yet, so it can be called before writing new code. A path that matches no configured zone returns an empty rule set rather than an error. It reads config only and runs no analysis; to find existing violations use `analyze` or `list_boundaries`. | Read-only |
| impact | Read fallow's local value-tracking report. Runs NO analysis: it reads a per-project history file from the user's private config dir (never inside the repo), answering "what has fallow done for me over time" rather than "what is wrong now" (for live findings use analyze / audit / check_health). LOCAL-DEV ONLY: history accrues only on a developer's machine (local dev, or a persistent pre-commit gate); fallow never records in CI, so in CI / ephemeral runners this returns an empty report (enabled:false) and must NOT be used as a CI metric. Always returns a populated JSON object (never {}): branch on `enabled` and `enabled_source` (`project` = an explicit per-repo enable/disable, `user` = the user-global default, `default` = off). When `enabled:false`, use `explicit_decision` to decide what to say: `explicit_decision:false` means tracking was never set up here, so recommend the user run `fallow impact enable` (do not run it yourself); `explicit_decision:true` means the user deliberately disabled it here, so do NOT nag. Also branch on `record_count` (0 with enabled:true = set up but awaiting gate runs). When enabled with history it returns `surfacing` (issue counts from the most recent recorded run), `trend` (count delta vs the previous run; improving/declining/stable on the wire), `containment_count` + `recent_containment` (pre-commit gate runs that blocked a commit then later cleared), and a short-SHA `latest_git_sha` for correlation. On fallow with impact v1.5+ the report also carries `resolved_total` / `suppressed_total` / `recent_resolved` / `attribution_active`, crediting findings fallow saw genuinely fixed (code removed or refactored) and never counting a fallow-ignore suppression as a win; older fallow binaries omit these fields. On fallow with impact v1.6+ the report also carries `project_surfacing` / `project_trend`: a WHOLE-PROJECT view from the last full `fallow` run (additive optional under the same `schema_version`, omitted by older binaries). Treat changed-file `surfacing` as the actionable count for the current change and `project_surfacing` as whole-repo context, not a to-do list. Read-only; the mutating `fallow impact enable` / `disable` / `default` lifecycle is intentionally not exposed over MCP. | Read-only |
| impact_all | Roll EVERY tracked fallow project on this machine into one cross-repo value report (`fallow impact --all --format json`). Runs NO analysis: it reads the per-project history files in the user's private config dir, answering "what has fallow done for me across all my repos". Use this instead of `impact` when the agent wants a portfolio view rather than one repo; use `impact` (with `root`) for a single project. Returns `kind: "impact-cross-repo"` with `schema_version` "2", `project_count` (stores enumerated), `tracked_count` (projects with recorded history shown as rows), `unreadable_count` (corrupt/newer-schema stores skipped), a `totals` roll-up (resolved/contained/surfacing summed over ALL tracked projects, including repos since deleted from disk), and a `projects[]` array. Each project row carries a hashed `project_key` (never a filesystem path, and the only always-present identifier), an optional human `label` (the repo's directory basename; omitted on rows recorded by older fallow binaries, so fall back to `project_key` when `label` is null/absent), `last_recorded`, and a nested per-project `report`. Privacy: the aggregate exposes NO absolute paths, only the hash key plus the basename label. Projects that are enabled but have no recorded history yet are counted in `project_count` but excluded from `projects[]` rows. `sort` orders rows (`recent` default / `resolved` / `contained` / `name`); `limit` caps the rows returned while `totals` still reflect every tracked project. LOCAL-DEV ONLY: history accrues only on developer machines (fallow never records in CI), so in CI / ephemeral runners this returns zero tracked projects and must NOT be used as a CI metric. When `project_count` is 0, no project on this machine has tracking enabled yet: in a local dev session suggest the user run `fallow impact enable` in a repo they care about (do not run it yourself), but in CI stay silent because zero is the expected, non-actionable result. Read-only; the mutating enable / disable / default / reset lifecycle is intentionally not exposed over MCP. | Read-only |
| impact_closure | Trace a file's impact closure. Runs `fallow dead-code --impact-closure <path> --format json --quiet` and returns the transitive affected-but-not-in-diff set plus coordination gaps for file-contract consumers. Evidence for review planning, not proof that affected files are wrong. Gaps carry `search_visibility`; see fallow://tools/impact_closure. Supports root, config, production, workspace, no_cache, and threads. | Read-only |
| inspect_similar_code | Inspect one exact unverified candidate from find_similar_code without rerunning provider retrieval or global ranking. Pass candidate_id plus a bounded snapshot containing the unchanged discovery schema_version, generation, selected candidate, completion, and diagnostics fields. Current source is re-extracted and both source_sha256 values must still match before bounded source windows, syntactic behavior hints, graph relationships, reachability, callers/callees, ownership, churn, tests, and deterministic clone overlap are returned. Stale source fails closed. Missing evidence is represented explicitly, never inferred. This remains read-only and never declares behavioral equivalence or refactor safety. | Read-only |
| inspect_target | Inspect one file or exported symbol and return one typed evidence bundle. Address a file with target={type:"file", file:"src/a.ts"}; address a symbol with target={type:"symbol", file:"src/a.ts", export_name:"foo"}. Composes existing read-only analysis systems only: trace_file, trace_export for symbols, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, security candidates scoped to the file, and the impact closure for the file (the transitive affected-but-not-in-diff set plus the coordination gap: modules that consume this file's contract but are not shown alongside it; a syntactic attention pointer, not a correctness proof). Set include_churn=true to attach target-level git churn from the in-process health hotspot subsystem; it is off by default, and missing git history is reported explicitly. Set cloud=true on a file target to attach the `cloud` evidence section of `fallow inspect --cloud` (Fallow Cloud production data per local function); repo selects the `owner/repo`. The key comes from the server environment or `fallow cloud login`, never from the call. The section status is ok, no_key, plan_required, unavailable, or untracked, and a status other than ok does not fail the call; see fallow://tools/inspect_target. Set format="compact" to get the plain text of `fallow inspect --format compact` (about 1 KB, no JSON) instead of the bundle. production is forwarded only to child analyses that support it: trace, dead-code, and health. Symbol targets include file-scoped evidence with explicit scope fields because file:line enclosing-symbol mapping is a follow-up. This bundled query runs independent evidence analyses in parallel; large repositories can exceed the default 120s subprocess timeout, so raise FALLOW_TIMEOUT_SECS when needed. | Read-only |
| list_boundaries | List architecture boundary zones and access rules configured for the project. Returns zone definitions (name, glob patterns, matched file count), access rules (which zones may import from which), and `logical_groups[]` (one entry per pre-expansion `autoDiscover` zone, surfacing the user-authored parent name, verbatim `auto_discover` paths, discovered `children`, `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule`, optional `fallback_zone` cross-reference for the Bulletproof case, optional `merged_from` when the parent name was declared multiple times, optional `original_zone_root` echo for monorepo subtree scopes, and optional `child_source_indices` attribution when multiple paths were authored). If boundaries are not configured, returns {"configured": false}; in that case, boundary violation checks will find no issues and can be skipped. Use this to understand the project's architecture constraints before running analysis. | Read-only |
| list_suppressions | List active fallow-ignore suppression markers grouped per file with line, kind, level, reason, and a stale cross-reference. Runs `fallow suppressions --format json` and returns the `kind: "suppression-inventory"` envelope verbatim (a `summary` roll-up plus `files[]`); a governance surface for distrusting a clean verdict by seeing what is suppressed, not a gate, so it always exits 0 even when suppressions exist. Scope with `workspace`, `changed_since` (the natural pull-request review scope), or repeated `file` entries. Read-only. It runs a full analysis to populate the inventory, so on large repos raise `FALLOW_TIMEOUT_SECS` above the default 120s if it times out. | Read-only |
| mutation_inspect | Inspect one mutant of a saved `fallow mutation` JSON report (default: the report that the last run saved in the Fallow cache): original and mutated code, covering tests, and the killing test. A source_sha256 mismatch with the current file gives a stale status, not a wrong answer. This tool never runs tests. A report needs the CLI command `fallow mutation`, which executes the project's tests, so ask your host first. On a Rust root, it reads only the cached map of `cargo fallow mutants`. | Read-only |
| mutation_plan | Plan mutation testing and return the plan envelope: each mutant's id, position, operator, disposition, and static test files, plus a source_sha256 per file. Scope: changed code by default, or `all`, or `paths`. This tool never runs tests. Running the mutants needs the CLI command `fallow mutation`, which executes the project's tests, so ask your host first. On a Rust root, it runs `cargo fallow mutants --list` for one `package`, by default all of it. | Read-only |
| mutation_tasks | List the open tasks of a saved `fallow mutation` JSON report as one batch (default: the report that the last run saved in the Fallow cache). A task is a survived or no_coverage mutant: a small change to the code that no test detected. Each task has the mutant_id, file, line, function, operator, status, the source lines before and after the change (original_lines, mutated_lines), and the covering test files. After `fallow mutation --record-args values`, a task can have witness; only witness.verdict witness gives a test input (args, original, mutant), and a verdict is never equivalent; see fallow://tools/mutation_tasks. Write tests that pass on the current code and fail on the changed code; one test can cover several tasks, and a task that no input can detect can be skipped. A task whose file changed after the report is stale and has no code. This tool never runs tests. A report needs the CLI command `fallow mutation`, which executes the project's tests, so ask your host first. A Rust root is not supported yet. | Read-only |
| project_info | Get project metadata: active framework plugins, discovered source files, and detected entry points. Useful for understanding how fallow sees the project before running analysis. Supports performance tuning (no_cache, threads). | Read-only |
| recommend | Recommend a project-tailored fallow config for an agent to author (`fallow recommend --format json`). Read-only: runs project detection (frameworks, workspace layout, tooling) but NOT the analysis pipeline, and always exits 0. Returns `{detected, proposed_config, decisions[]}`. `detected` is what fallow saw; `proposed_config` is a safe starting config that BOTH validates against config-schema AND loads through fallow's real config loader; `decisions[]` is THREE-valued: `auto` (decided from unambiguous detection and applied silently), `default` (a disclosed, overridable default carrying a quantified `rationale`), and `taste` (a genuinely subjective choice surfaced as an open, AskUserQuestion-shaped `question` with 2-4 options and NO baked-in recommended answer, per fallow's taste-ownership principle). Framework rules are never uniformly auto-enabled on a heterogeneous monorepo; entry points beyond the obvious fall back to fallow's own defaults rather than a baked-in guess. Zero-config is a valid stop: the proposed config is an optional refinement over already-strong defaults, not a requirement. Pair with `fallow schema` (the capability manifest carrying per-rule default severity + opt-in) for the full cold-start discover -> recommend -> ask-taste -> author sequence. Honors `root`. | Read-only |
| security_candidates | Returns unverified security candidates, not confirmed vulnerabilities. Runs `fallow security --format json` and returns `kind: "security"`, `security_findings`, category, CWE, severity, evidence, structural trace, reachability ranking context, blind-spot counters, and optional unresolved-callee diagnostics for agent verification. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` record (`source_kind`, the untrusted-input kind as a stable catalogue id or null; a self-contained `sink` with the captured callee and optional `url_shape` for URL candidates; and the `boundary` crossed), an optional `taint_flow` source-to-sink triple (present only when an untrusted source is import-reachable to the sink), a `finding_id` (the SARIF fingerprint), and a `stable_finding_id` that survives line moves, for verdicts. Set `surface: true` to include the top-level `attack_surface` inventory with source-to-sink paths and defensive-boundary verification prompts. Set gate to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires changed_since. There is no `impact` field: deciding exploitability is the agent's job. `reachability.untrusted_source_trace` is module-level context only and does not prove value flow. `reachability.taint_confidence` tiers reachable candidates as `arg-level` or `module-level`; tier from that field rather than evidence prose. Verify trace, reachability context, severity, and evidence before editing code or presenting a finding as a vulnerability. Supports root, config, workspace, changed_since, paths, changed_workspaces, surface, gate, no_cache, and threads. Use paths for the agent edit loop: it forwards to `fallow security --file` and scopes returned candidates to matching finding anchors, trace hops, untrusted-source reachability trace hops, or unresolved-callee diagnostics while cached analysis keeps reruns fast. The CLI also honors `FALLOW_DIFF_FILE` from the MCP server environment for line-level diff scoping. Security analysis can exceed the default 120s subprocess timeout on large repos; raise `FALLOW_TIMEOUT_SECS` accordingly. | Read-only |
| symbol_impact | Return exact-symbol consumers, transitive affected files, and targeted tests for a TypeScript export or exported class method. Select either export_name, or both class_name and member_name. The result is advisory project-impact evidence and does not duplicate tsc or Oxlint diagnostics. | Read-only |
| trace_clone | Deep-dive a duplicate-code clone group. Address it either by a source location (file + line) or by a stable fingerprint (fingerprint="dup:<id>" from a find_dupes clone_groups[].fingerprint, usually dup:<8hex> and widened only on rare report collisions). Returns the matched clone instance, every sibling clone group / location, plus per group an extract-function suggestion with estimated line savings and a best-effort suggested_name (the field is omitted, not null, when there is no confident name, so branch on key presence; advisory, verify before applying, never auto-apply). Provide exactly one addressing form. Import declarations are excluded from clone detection by default; pass ignore_imports=false to count them again. Use after find_dupes when consolidating duplication and you need exact sibling locations and a refactor target. | Read-only |
| trace_dependency | Trace where a dependency is used. Returns which files import the package, which imports are type-only, whether the package is referenced from package.json scripts or CI configs (`used_in_scripts`), and whether the dependency is used at all (`is_used` accounts for imports, script usage, and the used packages that list it as a peer (`peer_of`), matching the unused-deps detector). `unused_in` names each manifest that the detector still flags, because an import credits only the nearest manifest that installs the package. Set `usage`, `specifiers`, `sites` (paged with `limit` and `cursor`) or `closure_depth` to add a `usage` object: per imported name, the file, call and unresolved counts, one hop through project wrappers, and the usage sites. Useful before removing a dependency, moving it between dependencies and devDependencies, or migrating its API. | Read-only |
| trace_error | Resolve a runtime stack trace against the project graph: paste the trace text in `trace` and get, per frame, which definitions in THIS project the frame's identifier names. The verb for "my service threw this in production, what code is that". Returns `kind: "trace-error"` with retained frames in input order, each carrying an `origin` (`in_project`, `node_modules`, `out_of_corpus`) and a `resolution` (`resolved`, `ambiguous`, `not_found`, `not_attempted`), plus `candidates[]` naming the file, symbol, member and declaration line. It is built to refuse overclaiming: a frame matching several definitions is `ambiguous`, with bounded candidates and `candidates_omitted` instead of a preferred match, a frame the graph was never asked about is `not_attempted` rather than a softer `not_found`, and `line_mismatch` marks a resolved frame whose own line sits at a different declaration, so a name-only match is visible instead of implied. `counts` closes over the reported frames and publishes `frames_omitted` and `unparsed_lines`, so a capped or unreadable input cannot look complete. No source maps are read: a frame inside built output says so instead of being rebound through a map that may be stale, so give it a trace from unbundled source or the source paths a map already resolved. The RESOLUTION outcome never fails the call: a trace in which nothing resolves is an ANSWER, and exits 0. A refused input still is a refusal: an empty or oversized `trace` returns `isError` with `FALLOW_INVALID_TRACE_OPTIONS`. | Read-only |
| trace_export | Trace why an export is considered used or unused. Returns file reachability, entry-point status, direct references, re-export chains, the framework plugin rules that mark the export as used (`plugin_credits`), and a concise reason string. If export_name is a class / enum / store MEMBER rather than a top-level export, returns a member trace instead (carrying member_name, member_kind, owner_export, owner_is_used) that reports the owning class's reachability and usage plus a pointer to the matching --unused-<kind>-members command, so a class-member finding can be debugged too. Use this when an agent needs evidence before deleting or rewriting a supposedly unused export or class member. References carry `search_visibility`; see fallow://tools/trace_export. When the config or FALLOW_TYPE_AWARE turns type-aware analysis on, the trace also carries a `semantic` block with checker-backed evidence, as `fallow dead-code --trace` does. | Read-only |
| trace_file | Trace a file's graph context. Returns whether the file is reachable or an entry point, what it exports, what it imports, what imports it, and which re-exports it declares. Use this to understand whether a file is isolated, barrel-only, or imported by live entry points. | Read-only |
| trace_import_path | Shortest import path from one module to another, hop by hop with each hop's import line and whether the hop is type-only. Unreachable answers `reachable: false`; the same module answers `reachable: true`. Both report `hops: 0`, so branch on `reachable`, not the count. Exact project paths take priority; ambiguous abbreviations are refused. Use trace_file for one file's direct neighbours. | Read-only |
| trace_symbol | Trace an exact TypeScript symbol with checker-backed references, namespace identity, aliases, and re-export hops. Root trace fields preserve syntactic context; treat `semantic.references`, `semantic.status`, and `semantic.identity` as the authoritative exact evidence. The proof covers only the lane named by `semantic.target.namespace`, so a root trace that lists a reference the proof does not is wider evidence rather than stale. This is project-wide evidence for Fallow decisions, not a compiler-diagnostic or lint-rule surface. | Read-only |
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefallow-rs/fallow is public and reachablegithub.com/fallow-rs/fallow ↗Pass
- Package names this repository as its sourcefallow names fallow-rs/fallow as sourcenpmjs.com/package/fallow ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for fallownpmjs.com/package/fallow/v/3.43.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/fallow-rs/fallow ↗Pass
- OpenSSF ScorecardOpenSSF Scorecard 8.4 / 10; weakest: Code-Review 0, Branch-Protection 3scorecard.dev/viewer/?uri=github.com/fallow-rs/fallow ↗Pass
- Package name not close to a popular packageNo popular package one edit away from fallowPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the modelA tool description points at credential filesFinding
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRun it in the root of any JS or TS project:
npx fallow
A pull request gate on a fictional storefront monorepo might look like this:
$ npx fallow audit --base HEAD~15
Audit scope: 73 changed files vs HEAD~15
● Circular dependencies (24)
packages/storefront/src/orders/process.ts (6 cycles)
→ payment.ts → context.ts → process.ts
── Duplication ────────────────────────────────────
⚠ 185 lines (0.2%) duplicated across 6 files
● High complexity functions (28)
packages/storefront/src/orders/payment.ts
:566 processPayment CRITICAL
32 ! cyclomatic 47 ! cognitive 203 lines
── Styling ────────────────────────────────────────
font sizes mix 3 units (3 px, 2 rem, 1 em; candidate, standardize unless intentional)
✗ dead code: 68 issues · complexity: 28 findings · duplication: 7 clone groups · 73 changed files
audit gate excluded 98 inherited findings (run with --gate all to enforce)
Illustrative output for a fictional project. The gate fails (exit code 1) on findings in changed files. Findings that existed before the change are excluded.
fallow builds a repository graph of modules, exports, dependencies, functions, and styling tokens. Its analyses use that graph to find complexity, architecture drift, duplication, unused code, and risks in a pull request.
fallow runs in four places. All four read the same config file and use the same analysis engine.
| Where | Start with |
|---|---|
| Your terminal | npx fallow |
| Pull requests | uses: fallow-rs/fallow@v3 |
| Your editor | The VS Code extension or fallow-lsp |
| Coding agents | npx fallow agent install |
What fallow finds
| Question | Analysis | Command |
|---|---|---|
| Is this change safe to merge? | Changed-file gate over complexity, duplication, unused code, and styling drift, with a pass, warn, or fail result | fallow audit |
| Where is the code hard to change? | Complexity hotspots, a 0 to 100 health score, and refactoring targets, with git churn and ownership | fallow health |
| Does the architecture hold? | Boundary violations with bulletproof, layered, hexagonal, and feature-sliced presets, and circular dependencies |
fallow architecture, fallow guard |
| What is copied? | Code duplication in JS, TS, CSS, and Vue, Svelte, and Astro components | fallow dupes |
| Does the UI follow the design system? | Styling drift in CSS and CSS-in-JS | fallow health --css |
| What does nothing use? | Unused files, exports, types, class and enum members, and dependencies, with an auto-fix and a dry-run preview | fallow dead-code, fallow fix |
| Do the tests detect a code change? | Mutation testing: small changes in the source that no test detects (opt-in, runs the project tests) | fallow mutation |
| Which code paths are risky? | Security candidates, ranked by reachability from entry points (opt-in) | fallow security |
| Which functions do the same job? | Functions with the same intent and different syntax (opt-in, uses a local model that you download once) | fallow similar-code |
| Where are the feature flags? | Feature-flag patterns across the codebase | fallow flags |
npx fallow viz opens an interactive HTML map of the project with lenses for health, duplication, architecture, and unused code.
Add --type-aware for exact TypeScript symbol identity across aliases, re-exports, and packages. This optional pass removes false positives from interfaces and base classes (how type-aware analysis works). Runtime coverage from production is an optional add-on that fallow merges into health and audit reports.
The CLI reference lists every command. fallow schema prints all commands, flags, output formats, and exit codes as JSON.
Why teams can depend on fallow
fallow keeps these properties from release to release:
- The same input gives the same output, with a stable fingerprint for each finding. There is no AI inside the analyzer. Only the opt-in
similar-codecommand uses a pinned local model. fallow auditfails only on findings that a change introduces. Existing findings do not fail the check.- It is fast on large codebases. fallow finds the unused code in the next.js monorepo (20,558 files) in 2.95s. Measured on fallow 2.100.0. BENCHMARKS.md has the method and all results, and CodSpeed tracks performance on each change.
- fallow reads npm, yarn, and pnpm workspaces, and
--workspace <name>scopes a run to one package. - Over 100 built-in framework plugins find entry points and framework conventions, so the first run needs no config.
- Each command has a typed JSON output, documented exit codes, and a published output schema.
- Analysis runs on your machine or CI runner. Telemetry is opt-in (what fallow collects).
- The project has a public issue tracker, a public roadmap, and a security policy.
The analyzer is written in Rust and uses Oxc for syntactic analysis. Static analysis needs no TypeScript compiler and no Node.js runtime.
In your terminal
npx fallow # health, duplication, and unused code in one run
npx fallow audit # only the findings that your change introduces
npx fallow fix --dry-run # preview the auto-fixes, then run `npx fallow fix`
npx fallow health --score # health score with the largest deductions
npx fallow dead-code --trace src/api.ts:client # prove an export is unused before you delete it
To keep fallow in the project, install it as a dev dependency:
npm install --save-dev fallow
The npm package includes the fallow, fallow-lsp, and fallow-mcp launchers. For pnpm, yarn, cargo install fallow-cli, and Docker, see the installation guide.
To check each commit before it leaves your machine, install the managed pre-commit hook:
npx fallow hooks install --target git
Adopt fallow on an existing codebase
You do not have to fix every finding before you add fallow to CI.
- Run
npx fallow recommend. It detects the stack and proposes a config. It changes no files. - Use
fallow auditin pull requests. It compares each pull request with its base branch and blocks only the findings that the pull request adds. It needs no baseline file. - For full runs of
fallow,dead-code,dupes, orhealth, save a baseline once withnpx fallow --save-baseline fallow-baseline.json. Pass--baseline fallow-baseline.jsonon each later run, so that only new findings fail. - Reduce the backlog when your team has time.
fallow fix --dry-runshows the fixes and changes no files.fallow fixapplies them.
If findings are caused by missing entry points or generated files, add the missing entry points and exclude the generated files in the config:
{
"$schema": "./node_modules/fallow/schema.json",
"entry": ["src/cli.ts"],
"ignorePatterns": ["**/*.generated.ts"]
}
To keep an intentional export, add a suppression comment:
// fallow-ignore-next-line unused-export -- kept for plugin consumers
export const keepThis = 1;
// fallow-ignore-file <issue-type> suppresses a whole file. JSDoc tags (@public, @internal) keep intentional library API quiet. npx fallow suppressions lists every suppression in the project.
The adoption guide shows the staged path. Configuration has the full reference.
In pull requests
GitHub Actions:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: fallow-rs/fallow@v3
with:
command: audit
GitLab CI:
include:
- remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/v3.42.0/ci/gitlab-ci.yml'
fallow:
extends: .fallow
fetch-depth: 0 is the recommended setup. A default shallow checkout also works for command: audit: the Action fetches the commits that it needs to find the merge base.
To start in report-only mode, add fail-on-issues: false. Remove it when the team is ready for a gate. With command: audit, a pull request fails only on findings that it introduces. Without command: audit, the Action runs the full pipeline, and any finding fails the job (fail-on-issues defaults to true). In a pull request, the Action scopes the analysis to the changed files, so its output can differ from a full local run.
The Action installs the fallow version that the project's package.json names. Pin an exact version there to use the same version in CI and on your machine. It can post a PR comment and inline review comments, and it can upload SARIF to GitHub Code Scanning. Other output formats are CodeClimate, GitHub annotations, and Markdown. The GitLab template URL names a release tag, because GitLab includes a file from a fixed ref. The CI guide covers inputs, permissions, and a staged rollout.
For a PR comment or review comments, give the job these permissions. id-token: write is optional: it lets the Action post as the fallow bot. Without it, the comments come from github-actions[bot].
permissions:
contents: read
id-token: write
pull-requests: write
checks: write
Exit code 0 means no error-severity findings, or an audit result of pass or warn. Exit code 1 means error-severity findings, or an audit result of fail. In CI, exit code 1 fails the job, and that is the gate. The rule severity in the config (error, warn, off) sets which findings count. Exit code 2 means invalid input or an execution error. A script that reads the JSON output can treat 0 and 1 as a completed run, but must not hide exit code 2 with || true.
| Exit code | Meaning |
|---|---|
| 0 | Clean, or audit result pass or warn |
| 1 | Findings, or audit result fail (a normal outcome) |
| 2 | Validation or runtime error (JSON error on stdout with --format json) |
| 3 | A requested resource is unavailable, for example when config --path finds no config |
| 8 | Security gate hit (fallow security --gate) |
| 4 to 7, 10 to 13 | Runtime coverage, license, network, and upload errors |
With --format json, an error arrives on stdout as {"error": true, "message": "...", "exit_code": 2}, not as a stack trace.
Editors and integrations
- The VS Code extension shows findings in the editor.
fallow-lspgives diagnostics, hover, code actions, and code lenses in any LSP editor.editors/has setups for Zed and Neovim.- The Node API
@fallow-cli/fallow-nodeexportsdetectDeadCode,detectCircularDependencies,detectBoundaryViolations,detectArchitecture,detectDuplication,detectSimilarCode,detectFeatureFlags,computeComplexity, andcomputeHealth. The package API reference has the options and return types. fallow health --format badge > badge.svgwrites a health badge for your README.
With coding agents
npx fallow agent install --dry-run # show the plan
npx fallow agent install # apply it
fallow agent install sets up the agents that it detects (Claude Code, Codex, and Cursor) in one pass. It writes an AGENTS.md task map, installs the fallow and fallow-setup skills, registers the MCP server, and adds a gate on git commit and git push. Run npx fallow agent status to see these changes. Run npx fallow agent uninstall to remove them.
To register only the MCP server:
{ "mcpServers": { "fallow": { "command": "npx", "args": ["--yes", "--package", "fallow", "fallow-mcp"] } } }
--package fallow selects the npm package that provides the fallow-mcp launcher.
Scripts and agents that call the CLI directly add --format json --quiet. Each command then writes one typed JSON document to stdout:
- A root
kindfield names the analysis that made the document. - Each finding has an
actions[]array and anauto_fixableflag, so a script knows whatfallow fixcan do. - Root
next_steps[]suggestions are commands that run as written. - The types ship as
fallow/types, and docs/output-schema.json is the full schema.
Do not run fallow watch in an agent loop, because it does not exit.
Exit codes and the JSON error format are in In pull requests. The agent skills guide has the details.
Migrate existing config
npx fallow migrate converts knip, jscpd, and stylelint config into fallow config. The migration guides for knip and jscpd show each step.
Contributing
To report a missing framework plugin or a false positive, open an issue. CONTRIBUTING.md covers the development setup. docs/README.md is the entry point for maintainer documentation.
Thank you to everyone who contributes code, bug reports and ideas.
License
MIT. See LICENSE.
If fallow helps you or your team, you can support its development through GitHub Sponsors.
fallow MCP questions
How do I add fallow MCP to Claude Code?
Run claude mcp add fallow -- npx -y fallow mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add fallow MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does fallow MCP provide?
It exposes 44 tools, including analyze, audit, check_architecture, check_changed, check_health.
Does fallow require a TypeScript compiler?
No, it is a single Rust binary that requires no TypeScript compiler or configuration to start.
How does fallow handle existing code issues in pull requests?
The audit command only fails on findings that a specific change introduces, meaning existing issues do not block the gate.
Is the analysis AI-driven?
The core analyzer does not use AI; only the optional similar-code command uses a pinned local model.