fallow-graph 2.44.1

npx fallow --summary

Dead Code Summary

      12  Unused files
      47  Unused exports
       8  Unused types
       3  Unused dependencies
       2  Circular dependencies

      72  Total

Duplication Summary

      18  Clone families
      53  Clone groups
   2,140  Duplicated lines
    4.2%  Duplication rate

Health Summary

     612  Functions analyzed
       9  Above threshold
    89.4  Average maintainability (good)

Static analysis is free and open source. Runtime intelligence is optional.

90 framework plugins. No Node.js runtime required for static analysis. No config needed for the first run.

Fallow builds a project-wide understanding of your TS/JS codebase instead of checking one file at a time. Use it to review AI-generated changes faster, clean up dead code, reduce duplication, find risky complexity, and enforce architecture boundaries. Add the runtime layer when you want to know what actually executed in production.

Fallow is the codebase truth layer your coding agent can call. It is not an AI assistant.

Install

npx fallow                  # Run without installing
npm install -g fallow       # Or install globally (macOS, Linux, Windows)
cargo install fallow-cli    # Or via Cargo

Start here

fallow                      # Dead code + duplication + health
fallow dead-code            # Cleanup candidates
fallow dupes                # Repeated logic
fallow health               # Complexity + refactor targets
fallow fix --dry-run        # Preview automatic cleanup

What it finds

Dead code: unused files, exports, dependencies, types, cycles, boundaries, stale suppressions
Duplication: repeated blocks from exact to semantic clones
Complexity: high-risk functions, file scores, hotspots, and refactor targets
Architecture drift: boundary violations across layers and modules

Why Fallow exists

Linters check files. TypeScript checks types. Fallow checks the codebase.

It builds a module graph across the whole project so it can find problems that file-local tools cannot:

What	Linter	Fallow
Unused variable in a function	yes	no
Unused export that nothing imports	no	yes
File that nothing imports	no	yes
Circular dependency across modules	no	yes
Duplicate code blocks across files	no	yes
Dependency in package.json never imported	no	yes

Full comparison: fallow vs ESLint, Biome, knip, ts-prune

Why teams using AI need Fallow

AI accelerates code creation. It does not eliminate review, cleanup, or architecture drift.

When Claude Code, Codex, Cursor, or other tools generate changes, teams still need to know:

did this introduce dead code?
did it duplicate logic that already existed?
did complexity get worse?
did the change cross a boundary it should not cross?
is this code on a hot path or a cold one?
what should the reviewer read closely first?

Fallow answers those questions with deterministic, graph-based analysis and structured output, so both humans and agents can act on facts instead of guesses.

How agents use Fallow

Agents do not need to guess from limited context. They can call Fallow directly via the CLI or MCP.

Common agent workflow:

generate or edit code
run fallow --format json
inspect dead code, duplication, health findings, and per-issue actions
apply safe fixes or adjust the patch before opening a PR
hand the result to a human reviewer with better evidence

npx fallow --format json
npx fallow audit --format json
npx fallow fix --dry-run --format json

See Agent integration for MCP setup and the full list of structured tools.

More static commands

fallow audit                # Audit changed files (verdict: pass/warn/fail)
fallow watch                # Re-analyze on file changes
fallow fix                  # Apply automatic cleanup after previewing

Dead code

Finds unused files, exports, dependencies, types, enum members, class members, unresolved imports, unlisted dependencies, duplicate exports, circular dependencies (including cross-package cycles in monorepos), boundary violations, type-only dependencies, test-only production dependencies, and stale suppression comments. Entry points are auto-detected from package.json fields, framework conventions, and plugin patterns. Arrow-wrapped dynamic imports (React.lazy, loadable, defineAsyncComponent) are tracked as references. Script multiplexers (concurrently, npm-run-all) are analyzed to discover transitive script dependencies. JSDoc tags (@public, @internal, @beta, @alpha, @expected-unused) control export visibility.

fallow dead-code                          # All dead code issues
fallow dead-code --unused-exports         # Only unused exports
fallow dead-code --circular-deps          # Only circular dependencies
fallow dead-code --boundary-violations    # Only boundary violations
fallow dead-code --stale-suppressions     # Only stale suppression comments
fallow dead-code --production             # Exclude test/dev files
fallow dead-code --changed-since main     # Only changed files (for PRs)
fallow dead-code --file src/utils.ts       # Single file (lint-staged integration)
fallow dead-code --include-entry-exports  # Also check exports from entry files
fallow dead-code --group-by owner         # Group by CODEOWNERS for team triage
fallow dead-code --group-by directory     # Group by first directory component
fallow dead-code --group-by package       # Group by workspace package (monorepo)
fallow dead-code --group-by section       # Group by GitLab CODEOWNERS section

Duplication

Finds copy-pasted code blocks across your codebase. Suffix-array algorithm -- no quadratic pairwise comparison.

fallow dupes                              # Default (mild mode)
fallow dupes --mode semantic              # Catch clones with renamed variables
fallow dupes --skip-local                 # Only cross-directory duplicates
fallow dupes --trace src/utils.ts:42      # Show all clones of code at this location

Four detection modes: strict (exact tokens), mild (default, AST-based), weak (different string literals), semantic (renamed variables and literals).

Complexity

Surfaces the most complex functions in your codebase and identifies where to spend refactoring effort.

fallow health                             # Functions exceeding thresholds
fallow health --score                     # Project health score (0-100) with letter grade
fallow health --min-score 70              # CI gate: fail if score drops below 70
fallow health --top 20                    # 20 most complex functions
fallow health --file-scores               # Per-file maintainability index (0-100)
fallow health --hotspots                  # Riskiest files (git churn x complexity)
fallow health --hotspots --ownership      # Add bus factor, owner, drift signals
fallow health --targets                   # Ranked refactoring recommendations
fallow health --targets --effort low      # Only quick-win refactoring targets
fallow health --coverage-gaps             # Static test coverage gaps
fallow health --coverage coverage/coverage-final.json
fallow health --coverage artifacts/coverage.json --coverage-root /home/runner/work/myapp
fallow health --production-coverage ./coverage
fallow health --production-coverage ./coverage --min-invocations-hot 250
fallow health --trend                     # Compare against saved snapshot
fallow health --changed-since main        # Only changed files

Runtime intelligence (optional)

Static analysis answers: what is connected to what?

Runtime intelligence answers: what actually ran?

Fallow Runtime is the optional paid team layer. It uses production coverage as the collection engine (V8 dumps via NODE_V8_COVERAGE=... and Istanbul coverage-final.json files), then merges that evidence into fallow health so teams and coding agents can:

review changes on hot production paths more carefully
delete cold code with stronger evidence
prioritize refactors by runtime importance
spot stale feature-flag branches and stale runtime code
give agents factual usage data instead of assumptions

fallow license activate --trial --email you@company.com
fallow coverage setup
fallow health --production-coverage ./coverage

Static coverage_gaps and runtime production_coverage are separate layers in the same health surface:

Surface	Flag	Input	Answers	License
Static test reachability	`--coverage-gaps`	none	which runtime files/exports have no test dependency path	no
Exact CRAP scoring	`--coverage`	Istanbul JSON file or `coverage-final.json` directory	how covered each function is for CRAP computation	no
Runtime production coverage	`--production-coverage`	V8 directory, V8 JSON file, or Istanbul JSON file	which functions actually executed, which stayed cold, which are hot	yes

Setup details:

fallow license activate --trial --email ... starts a trial and stores the signed license locally
fallow license refresh refreshes the stored license before the hard-fail window
fallow coverage setup detects your framework and package manager, installs the sidecar if needed, writes a collection recipe, and resumes from the current setup state on re-run
The sidecar can be installed globally or as a project devDependency; fallow resolves FALLOW_COV_BIN, project-local shims, package-manager bin lookups, ~/.fallow/bin/fallow-cov, and PATH
fallow health --production-coverage <path> accepts a V8 directory, a single V8 JSON file, or a single Istanbul coverage map JSON file (commonly coverage-final.json)
fallow health --coverage <path> accepts a single Istanbul coverage map JSON file or a directory containing coverage-final.json
--coverage-root <path> rebases Istanbul file paths before CRAP matching. Use it when coverage was generated in CI or Docker with a different checkout root, for example fallow health --coverage artifacts/coverage-final.json --coverage-root /home/runner/work/myapp
V8 dumps that include Node's source-map-cache are remapped through supported source-map paths before analysis, including file paths, relative paths, webpack://..., and vite://...; unsupported virtual schemes safely fall back to raw V8 handling
fallow health --changed-since <ref> --production-coverage <path> promotes touched hot paths to a hot-path-changes-needed verdict during change review

Production coverage is merged into the same human, JSON, SARIF, compact, markdown, and CodeClimate outputs as the rest of the health report.

Audit

Quality gate for AI-generated code and PRs. Combines dead code + complexity + duplication scoped to changed files.

fallow audit                              # Auto-detects base branch
fallow audit --base main                  # Explicit base ref
fallow audit --base HEAD~3               # Audit last 3 commits
fallow audit --format json                # Structured output with verdict

Returns a verdict: pass (exit 0), warn (exit 0, warn-severity only), or fail (exit 1). JSON output includes a verdict field for CI and agent integration.

Per-analysis baselines. When touching legacy files with pre-existing issues, reuse the baselines saved by the individual subcommands so audit only fails on genuinely new findings:

# Save once from a clean ref
fallow dead-code --save-baseline .fallow/dead-code-baseline.json
fallow health    --save-baseline .fallow/health-baseline.json
fallow dupes     --save-baseline .fallow/dupes-baseline.json

# Feed into audit on every PR
fallow audit \
  --dead-code-baseline .fallow/dead-code-baseline.json \
  --health-baseline    .fallow/health-baseline.json \
  --dupes-baseline     .fallow/dupes-baseline.json

Configure defaults in .fallowrc.json under audit.deadCodeBaseline / audit.healthBaseline / audit.dupesBaseline so CI stays one command (fallow audit). CLI flags override config.

CI integration

# GitHub Action
- uses: fallow-rs/fallow@v2

# GitLab CI -- include the template and extend
include:
  - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'
fallow:
  extends: .fallow

# Or run directly on any CI
- run: npx fallow --ci

--ci enables SARIF output, quiet mode, and non-zero exit on issues. Also supports:

--group-by owner|directory|package|section -- group output by CODEOWNERS ownership, directory, workspace package, or GitLab CODEOWNERS [Section] headers for team-level triage
--summary -- show only category counts (no individual issues)
--changed-since main -- analyze only files touched in a PR
--changed-workspaces origin/main -- scope monorepo analysis to workspaces containing any changed file (CI primitive; fails hard on git errors so CI never silently widens back to the full repo)
--baseline / --save-baseline -- fail only on new issues
--fail-on-regression / --tolerance 2% -- fail only if issues grew beyond tolerance
--format sarif -- upload to GitHub Code Scanning
--format codeclimate -- GitLab Code Quality inline MR annotations
--format annotations -- GitHub Actions inline PR annotations (no Action required)
--format json / --format markdown -- for custom workflows (JSON includes machine-actionable actions per issue)
--format badge -- shields.io-compatible SVG health badge (fallow health --format badge > badge.svg)

Both the GitHub Action and GitLab CI template auto-detect your package manager (npm/pnpm/yarn) from lock files, so install/uninstall commands in review comments match your project.

Adopt incrementally -- surface issues without blocking CI, then promote when ready:

{ "rules": { "unused-files": "error", "unused-exports": "warn", "circular-dependencies": "off" } }

GitLab CI rich MR comments

The GitLab CI template can post rich comments directly on merge requests -- summary comments with collapsible sections and inline review discussions with suggestion blocks.

Variable	Default	Description
`FALLOW_COMMENT`	`"false"`	Post a summary comment on the MR with collapsible sections per analysis
`FALLOW_REVIEW`	`"false"`	Post inline MR discussions at the relevant lines, with `suggestion` blocks for unused exports
`FALLOW_MAX_COMMENTS`	`"50"`	Maximum number of inline review comments

In MR pipelines, --changed-since is set automatically to scope analysis to changed files. Previous fallow comments are cleaned up on re-runs.

The comment merging pipeline groups unused exports per file and deduplicates clone reports, keeping MR threads readable.

A GITLAB_TOKEN (PAT with api scope) is recommended for full features (suggestion blocks, cleanup of previous comments). CI_JOB_TOKEN works for posting but cannot delete comments from prior runs.

# .gitlab-ci.yml -- full example with rich MR comments
include:
  - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/main/ci/gitlab-ci.yml'

fallow:
  extends: .fallow
  variables:
    FALLOW_COMMENT: "true"       # Summary comment with collapsible sections
    FALLOW_REVIEW: "true"        # Inline discussions with suggestion blocks
    FALLOW_MAX_COMMENTS: "30"    # Cap inline comments (default: 50)
    FALLOW_FAIL_ON_ISSUES: "true"

Configuration

Works out of the box. When you need to customize, create .fallowrc.json or run fallow init:

// .fallowrc.json
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "entry": ["src/workers/*.ts", "scripts/*.ts"],
  "ignorePatterns": ["**/*.generated.ts"],
  "ignoreDependencies": ["autoprefixer"],
  "rules": {
    "unused-files": "error",
    "unused-exports": "warn",
    "unused-types": "off"
  },
  "health": {
    "maxCyclomatic": 20,
    "maxCognitive": 15,
    "maxCrap": 30
  }
}

Architecture boundary presets enforce import rules between layers with zero manual config:

{ "boundaries": { "preset": "bulletproof" } } // or: layered, hexagonal, feature-sliced

Run fallow list --boundaries to inspect the expanded rules. TOML also supported (fallow init --toml). The init command auto-detects your project structure (monorepo layout, frameworks, existing config) and generates a tailored config. It also adds .fallow/ to your .gitignore (cache and local data). Scaffold a pre-commit hook with fallow init --hooks. Migrating from knip or jscpd? Run fallow migrate.

See the full configuration reference for all options.

Framework plugins

90 built-in plugins detect entry points, convention exports, config-defined aliases, and template-visible usage for your framework automatically.

Category	Plugins
Frameworks	Next.js, Nuxt, Remix, Qwik, SvelteKit, Gatsby, Astro, Angular, NestJS, Expo, Expo Router, Electron, and more
Bundlers	Vite, Webpack, Rspack, Rsbuild, Rollup, Rolldown, Tsup, Tsdown, Parcel
Testing	Vitest, Jest, Playwright, Cypress, Storybook, Mocha, Ava
CSS	Tailwind, PostCSS, UnoCSS
Databases & Backend	Prisma, Drizzle, Knex, TypeORM, Kysely, Convex
Blockchain	Hardhat
Monorepos	Turborepo, Nx, Changesets, Syncpack, pnpm

Full plugin list -- missing one? Add a custom plugin or open an issue.

Editor & AI support

Fallow is not an AI assistant. It is the codebase truth layer your assistant can call.

VS Code extension -- tree views, status bar, one-click fixes, auto-download LSP binary (Marketplace)
LSP server -- real-time diagnostics, hover info, code actions, Code Lens with reference counts
MCP server -- AI agent integration for Claude Code, Cursor, Windsurf (fallow-skills)
JSON actions array -- every issue in --format json output includes fix suggestions with auto_fixable flag, so agents can self-correct

Performance

Benchmarked on real open-source projects (median of 5 runs, Apple M5).

Dead code: fallow vs knip

Project	Files	fallow	knip v5	knip v6	vs v5	vs v6
zod	174	17ms	577ms	300ms	34x	18x
fastify	286	19ms	791ms	232ms	41x	12x
preact	244	20ms	767ms	2.02s	39x	103x
TanStack/query	901	170ms	2.50s	1.28s	15x	8x
svelte	3,337	359ms	1.73s	749ms	5x	2x
next.js	20,416	1.66s	--	--	--	--

knip errors out on next.js. fallow completes in under 2 seconds.

Duplication: fallow vs jscpd

Project	Files	fallow	jscpd	Speedup
fastify	286	76ms	1.96s	26x
vue/core	522	124ms	3.11s	25x
next.js	20,416	2.89s	24.37s	8x

No TypeScript compiler, no Node.js runtime needed to analyze your code. Fallow vs linters | Reproduce benchmarks

Suppressing findings

// fallow-ignore-next-line unused-export
export const keepThis = 1;

// fallow-ignore-file
// Suppress all issues in this file

Also supports JSDoc visibility tags (/** @public */, /** @internal */, /** @beta */, /** @alpha */) to suppress unused export reports for library APIs consumed externally.

Limitations

fallow uses syntactic analysis -- no type information. This is what makes it fast, but type-level dead code is out of scope. Use inline suppression comments or ignoreExports for edge cases.

Documentation

Contributing

Missing a framework plugin? Found a false positive? Open an issue.

cargo build --workspace && cargo test --workspace

License

MIT