fallow

---

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.

What fallow reports

• Unused files, exports, types, enum and class members, and dependencies
• Circular dependencies and re-export cycles, part of fallow dead-code
• Code duplication with a suffix-array detector covering JS/TS and CSS-family stylesheets, plus Vue/Svelte/Astro component regions
• Complexity hotspots and a 0 to 100 health score with a letter grade
• Architecture boundary violations with bulletproof, layered, hexagonal, and feature-sliced presets
• Design-system styling drift for CSS and CSS-in-JS
• A changed-file PR gate with a pass, warn, or fail verdict (fallow audit)
• Auto-fix with a dry-run preview
• Opt-in security candidates ranked by reachability from entry points (fallow security)

Over 100 built-in framework plugins detect entry points 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:

{
  "$schema": "./node_modules/fallow/schema.json",
  "ignorePatterns": ["**/*.generated.ts"]
}

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. 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; known limits (syntactic analysis, no type resolution) 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.

Commands

Command	What it does
npx fallow	Full pipeline: dead code, duplication, health
npx fallow audit	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)
npx fallow dead-code	Unused code and circular dependencies (alias: check)
npx fallow dead-code --trace src/file.ts:symbol	Prove a symbol is unused before deleting it
npx fallow dupes	Duplication; modes strict, mild (default), weak, semantic
npx fallow health --score	Complexity, 0 to 100 health score, hotspots; --css adds structural CSS analytics
npx fallow fix --dry-run	Preview auto-fixes; apply with npx fallow fix
npx fallow guard src/file.ts	Which boundary rules apply to a file before editing
npx fallow security	Opt-in security candidates; --gate new --changed-since <ref> fails only on introduced ones
npx fallow explain <issue-type>	Explain a rule without analyzing
npx fallow recommend	Detect the stack and propose a config; subjective choices stay open questions
npx fallow init	Scaffold config; --agents scaffolds an AGENTS.md
npx fallow migrate	Migrate from knip, jscpd, or stylelint config

Command	Purpose
fallow review --brief	Advisory orientation brief over changed files; always exits 0
fallow inspect --file src/api.ts	Evidence bundle for one file, or one symbol via --symbol src/api.ts:client
fallow trace src/utils.ts:formatDate	Symbol-level call chains: callers up, callees down
fallow watch	Re-run analysis on file changes (interactive use; agents should not run it)
fallow flags	Detect feature-flag patterns
fallow suppressions	Inventory of fallow-ignore markers
fallow list	Entry points, files, plugins, and boundaries (--boundaries)
fallow workspaces	Monorepo workspace discovery diagnostics
fallow config	Resolved configuration and which file provided it
fallow decision-surface	Ranked structural decisions a change embeds
fallow impact	Opt-in, local-only report of what fallow caught; --all spans repos
fallow report --from results.json	Re-render a saved JSON result in another output format
fallow ci ...	PR/MR feedback helpers (comments, reviews, check runs)
fallow ci-template gitlab --vendor	Vendor the GitLab CI template for offline runners
fallow hooks install --target git	Managed pre-commit hook; --target agent writes agent-gate hooks
fallow rule-pack init	Declarative policy rule packs (list, test, schema)
fallow plugin-check	Dry-run an external framework plugin
fallow config-schema	JSON Schema for config; also plugin-schema and rule-pack schema
fallow license activate --trial --email you@company.com

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 JS