Fallow

Fallow: codebase intelligence for JavaScript and TypeScript

Codebase intelligence for JavaScript and TypeScript. The free static layer finds unused code, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, and feature flag patterns. Runtime coverage merges production execution data into the same fallow health report for hot-path review, cold-path deletion confidence, and stale-flag evidence: a single local capture is free, while continuous/cloud runtime monitoring is paid. 90 framework plugins, zero configuration, sub-second static analysis.

When to Use

• Finding dead code (unused files, exports, types, enum/class members)
• Finding unused or unlisted dependencies
• Detecting code duplication and clones
• Checking code health and complexity hotspots
• Cleaning up a codebase before a release or refactor
• Auditing a project for structural issues
• Setting up CI checks for dead code or duplication thresholds
• Auto-fixing unused exports and dependencies
• Detecting feature flag patterns (environment gates, SDK calls, config objects)
• Investigating why a specific export or file appears unused

When NOT to Use

• Runtime error analysis or debugging
• Type checking (use tsc for that)
• Linting style or formatting issues (use ESLint, Biome, Prettier)
• Security vulnerability scanning
• Bundle size analysis
• Projects that are not JavaScript or TypeScript

Prerequisites

Fallow must be installed. If not available, install it:

npm install -g fallow          # prebuilt binaries (fastest)
# or
npx fallow dead-code               # run without installing
# or
cargo install fallow-cli        # build from source

Agent Rules

1. Always use --format json --quiet 2>/dev/null for machine-readable output. The 2>/dev/null discards stderr so progress messages and threshold warnings don't corrupt the JSON on stdout. Never use 2>&1
2. Always append || true to every fallow command. Exit code 1 means "issues found" (normal), not a runtime error. Without || true, the Bash tool treats exit 1 as failure and cancels parallel commands. Only exit code 2 is a real error (invalid config, parse failure)
3. Use --explain to include a _meta object in JSON output with metric definitions, ranges, and interpretation hints
4. Use issue type filters (--unused-exports, --unused-files, etc.) to limit output scope
5. Always --dry-run before fix, then fix --yes to apply
6. All output paths are relative to the project root
7. Never run fallow watch. It is interactive and never exits

Commands

Issue Types

MCP Tools

When using fallow via MCP (fallow-mcp), the following tools are available:

All tools accept root, config, no_cache, and threads params. The MCP server subprocess timeout defaults to 120s, configurable via FALLOW_TIMEOUT_SECS.

All JSON responses include structured actions arrays on every finding (dead code, health, duplication), enabling programmatic fix application or suppression.

Node.js Bindings

When embedding fallow inside a Node.js process (editor extensions, long-running servers, custom tooling), prefer the NAPI bindings over spawning the CLI. Same analysis engine, same JSON envelopes, no subprocess or JSON parsing overhead.

npm install @fallow-cli/fallow-node

import { detectDeadCode, detectDuplication, computeHealth } from '@fallow-cli/fallow-node'

const deadCode = await detectDeadCode({ root: process.cwd(), explain: true })
const dupes = await detectDuplication({ root: process.cwd(), mode: 'mild', minTokens: 30 })
const health = await computeHealth({ root: process.cwd(), score: true, ownershipEmails: 'handle' })

Six async functions: detectDeadCode, detectCircularDependencies, detectBoundaryViolations, detectDuplication, computeComplexity, computeHealth. Each returns the same JSON envelope the CLI emits for --format json. Rejected promises throw a FallowNodeError with message, exitCode, and optional code, help, context fields that mirror the CLI's structured error surface.

Enum-like fields take lowercase CLI-style literals ("mild", "cyclomatic", "handle", "low"). Write-path commands (fix, init, setup-hooks, license activate, coverage setup) are not exposed; use the CLI for those.

See https://docs.fallow.tools/integrations/node-bindings for the full field reference.

References

• CLI Reference: complete command and flag specifications
• Gotchas: common pitfalls, edge cases, and correct usage patterns
• Patterns: workflow recipes for CI, monorepos, migration, and incremental adoption

Common Workflows

Audit a project for all dead code

fallow dead-code --format json --quiet

Parse the JSON output. It contains arrays for each issue type (unused_files, unused_exports, unused_types, unused_dependencies, etc.) plus total_issues and elapsed_ms metadata. Each issue object includes an actions array with structured fix suggestions (action type, auto_fixable flag, description, and optional suppression comment). For dependency findings, a non-empty used_in_workspaces array means the package is imported elsewhere in the monorepo

…(truncated)