Codebase intelligence for TypeScript and JavaScript.
One binary finds unused code, circular dependencies, duplication, complexity hotspots, boundary violations, and design-system styling drift. An optional paid layer, Fallow Runtime, adds production execution evidence. Deterministic findings and typed output contracts. No AI inside the analyzer, and no TypeScript compiler or Node.js runtime needed for static analysis.
Most repositories carry code nobody dares to delete, because deleting means proving a negative: fallow reads the repository as one dependency graph, from import edges to styling tokens, and reports what that graph shows.
Audit scope: 19 changed files vs HEAD~15 (8fbfcb054..HEAD)
● Unused files (2)
packages/vitest/src/public/reporters.ts
test/coverage-test/test/configuration-options.test-d.ts
● Circular dependencies (6)
packages/vitest/src/integrations/vi.ts
→ wait.ts → vi.ts
✗ dead code: 156 issues · complexity: 6 findings · duplication: 8 clone groups · 19 changed files (1.05s)
audit gate excluded 163 inherited findings (run with --gate all to enforce)
Excerpt from fallow audit on the vitest monorepo, auditing its last 15 commits. fallow 3.5.0, warm base-snapshot cache. The gate passed: the 163 inherited findings are pre-existing and excluded by design, so they do not block the change. The same run with --format json returns one typed JSON document.
Quick start
# Zero-install, full pipeline (dead code + duplication + health)
npx fallow
# Gate only what a PR changed
npx fallow audit
# Install as a devDependency
npm install --save-dev fallow
# For agents and scripts: exit 0 and 1 both mean the run succeeded (1 = findings);
# exit 2 is a real error, reported as a JSON envelope on stdout
npx fallow audit --format json --quiet 2>/dev/null
The npm package ships the fallow, fallow-lsp, and fallow-mcp launchers plus a version-matched agent skill, so the editor and agent integrations resolve the project-local binary instead of whatever happens to be on PATH. Runs are deterministic: the same input produces the same output with stable fingerprints. Re-running to verify an edit is safe. Other channels (pnpm, yarn, cargo install fallow-cli, and a local Docker build with a Compose example at examples/docker/compose.yaml) are covered in the installation guide.
Code duplication with a suffix-array detector covering JS/TS and CSS-family stylesheets, plus Vue/Svelte/Astro component regions
Opt-in semantic similar-code candidates for functions that may share intent despite different syntax, using a pinned local model and explicit review (fallow similar-code)
Opt-in security candidates ranked by reachability from entry points (fallow security)
Optional checker-backed TypeScript evidence for exact symbol usage, cross-file private type leaks, targeted tests, and public-signature coupling (--type-aware)
Over 100 built-in framework plugins detect entry points and framework-consumed exports automatically, so the first run needs no configuration. Fallow Runtime, the optional paid layer, merges production execution evidence into these same reports; see Runtime intelligence (optional) and static vs runtime.
Your first run
Findings on a first run usually mean fallow is missing an entry point or a framework convention, or is analyzing generated files you never meant to include. The built-in plugins take care of framework detection; it's generated code that usually needs a hint:
You do not have to author that config yourself. npx fallow recommend detects the stack (frameworks, workspace layout, test runner, package manager), prints a proposed config as a safe starting point, and ends with the few genuinely subjective choices it will not decide for you. For TypeScript projects it also points to the optional, slower --type-aware pass without enabling it. It is read-only and always exits 0; nothing changes until you save the config.
Patterns are relative to the project root and add to fallow's built-in ignore defaults (node_modules, dist, coverage, minified bundles). Config precedence is first match wins per directory, with no merging: .fallowrc.json (JSONC accepted) > .fallowrc.jsonc > fallow.toml > .fallow.toml. The full reference is the configuration overview; the boundaries of the default syntactic and optional type-aware analyses are documented in limitations; for a hung or failed run, see debugging.
Adopting on an existing codebase? fallow audit fails only on findings a change introduces, so a legacy backlog does not block day one, and --save-baseline / --baseline quarantine the existing findings for the standalone commands. The adoption guide covers the staged path.
Changed-file gate over dead code, complexity, duplication, and styling drift: verdict pass/warn/fail against a base ref. Fails only on findings the change introduced (--gate all widens)
Interactive HTML map with Unused, Duplication, Architecture, Health, and static Security lenses, plus dependency, framework, styling, and feature-flag analysis
Default analysis stays Rust-native, syntactic, and independent of Node.js or
the TypeScript compiler. Add --type-aware when a cleanup or refactor depends
on exact TypeScript identity across aliases, re-exports, packages, or tests:
This does not replace tsc --noEmit or Oxlint. Fallow does not emit compiler
diagnostics or duplicate local typed lint rules. It uses checker evidence only
for project-wide questions. It removes false positives caused by interfaces,
base classes, aliases, and re-exports. A class member becomes automatically
fixable only after every owning project reports complete negative evidence and
the exact declaration hash still matches. Otherwise Fallow keeps the finding
and explains the gap. See the type-aware analysis contract.
Per-command flags come from fallow schema (machine-readable) or the CLI reference.
Output and exit codes
For machine consumption, add --format json --quiet to any command, parse the JSON on stdout, and do not depend on whitespace. JSON is compact by default; add --pretty only for manual inspection. Exit 0 and 1 both mean the run succeeded (1 signals findings); exit 2 is a real error and still writes a JSON envelope to stdout. Branch on the code, treating 0 and 1 as success and 2 as failure, rather than blanket-suppressing with || true (which hides real errors from anything that checks the exit code).
--format
What you get
human (default)
Terminal report with a Next: suggestion line
json
The machine contract: one compact typed JSON document on stdout (--pretty indents it)
Typed CI feedback from final refined findings; supported by type-aware check and audit runs
badge
shields.io-compatible SVG health badge; fallow health only (fallow health --format badge > badge.svg)
human, json, sarif, compact, and markdown apply to every analysis command; the CI envelopes and badge belong to the command that produces them, as documented per format in the CI guide.
In CI, keep JSON as the provenance-bearing artifact and render presentation
surfaces from it. For example, analyze once with --format json -o results.json,
then run fallow report --from results.json --format pr-comment-gitlab and
fallow report --from results.json --format review-gitlab. This preserves
type-aware refinement, audit verdicts, and one authoritative finding set.
Exit code
Meaning
0
Clean, or audit verdict pass or warn
1
Findings, or audit verdict fail (a normal outcome)
2
Validation or runtime error (JSON error envelope on stdout with --format json)
3
Requested resource unavailable: config --path found no config, or a license is unavailable or invalid
4
Runtime coverage sidecar is unavailable, unverifiable, protocol-incompatible, or terminated unexpectedly
5
Runtime coverage input could not be prepared or parsed
6
Runtime coverage sidecar reported an internal error
7
Network failure (license and cloud operations)
8
Security gate hit (fallow security --gate)
10
Coverage inventory or static-findings upload input or project validation failed
11
Coverage inventory or static-findings upload exceeded the server payload limit
12
Coverage inventory or static-findings upload authentication or authorization was rejected
13
Coverage inventory or static-findings upload failed after retries or returned another server error
Rule severity maps onto exit codes: error fails CI (the default), warn exits 0, off skips the rule (rules reference).
The JSON contract, in short:
a root kind discriminator names the analysis that produced the document
per-issue actions[] with an auto_fixable flag, so a script knows which findings it can hand to fallow fix
root next_steps[] suggestions are runnable as-is
errors arrive as {"error": true, "message": "...", "exit_code": 2} on stdout, not as a stack trace
Typed contracts ship with the npm package: import type { CheckOutput, FallowJsonOutput } from "fallow/types". The generated schema lives at docs/output-schema.json. The output format is CLI-only, via --format or FALLOW_FORMAT, and is never set in config; all environment variables are listed in docs/environment-variables.md.
Built for agents
The JSON contract and exit codes above are the agent interface.
The MCP server covers analysis, audit, health, duplication, tracing, fix preview and apply, boundary guard checks, and target inspection; every tool documents its nearest CLI fallback, and a bounded read-only Code Mode sandbox composes analysis calls without filesystem or network access.
npx fallow agent install wires the detected harnesses (Claude Code, Codex, Cursor) in one pass: an AGENTS.md task map (plus a CLAUDE.md import), the fallow skill, the MCP server registration, and the commit/push gate. Every write is marked, --dry-run shows the plan, status and uninstall cover the same surfaces
npx fallow recommend --format json is the onboarding entry point: it returns the detected stack, a proposed config, and every decision with its tier and rationale, and it ships the subjective choices as ready-to-ask questions with options and tradeoffs. An agent authors .fallowrc.json from evidence and asks the user only what fallow will not decide
A version-matched agent skill ships in the npm package under node_modules/fallow/skills/fallow (agent skills, companion repo fallow-skills)
npx fallow init --agents scaffolds an AGENTS.md with a task-to-command matrix, and npx fallow hooks install --target agent gates git commit and git push on fallow audit ([hooks](https://docs.fallow.too
fallow (fallow-rs/fallow)
Choose a tag and it will appear here. With no tags selected, all catalog projects are shown.
Searching Database…
Choose a tag and it will appear here. With no tags selected, all catalog projects are shown.
Fallow 是一款基于 Rust 的 TypeScript/JavaScript 代码库智能分析工具。它会为代码仓库构建一张统一的依赖关系图，并报告未使用的代码、循环依赖、代码重复、复杂度热点、架构边界违规，以及设计系统样式偏离问题。