stolinski/s-stack/fallow

Fallow: Codebase Analyzer

The codebase analyzer for JavaScript and TypeScript. Finds unused code, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, and feature flag patterns. 90 framework plugins, zero configuration, sub-second performance.

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.

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).

Find only unused exports (smaller output)

fallow dead-code --format json --quiet --unused-exports

Check if a PR introduces dead code

fallow dead-code --format json --quiet --changed-since main --fail-on-issues

Exit code 1 if new dead code is introduced. Only analyzes files changed since the main branch.

Find code duplication

fallow dupes --format json --quiet
fallow dupes --format json --quiet --mode semantic

The semantic mode detects renamed variables. Other modes: strict (exact), mild (default, syntax normalized), weak (different literals).

Safe auto-fix cycle

# 1. Preview what will be removed
fallow fix --dry-run --format json --quiet
 
# 2. Review the output, then apply
fallow fix --yes --format json --quiet
 
# 3. Verify the fix worked
fallow dead-code --format json --quiet

The --yes flag is required in non-TTY environments (agent subprocesses). Without it, fix exits with code 2.

Discover project structure

fallow list --entry-points --format json --quiet
fallow list --plugins --format json --quiet

Shows detected entry points and active framework plugins (90 built-in: Next.js, Vite, Jest, Storybook, Tailwind, etc.).

Production-only analysis

fallow dead-code --format json --quiet --production

Excludes test/dev files (*.test.*, *.spec.*, *.stories.*) and only analyzes production scripts.

Analyze a single workspace package

fallow dead-code --format json --quiet --workspace my-package

Scopes output to one package while keeping the full cross-workspace graph.

Scope to specific files (lint-staged)

fallow dead-code --format json --quiet --file src/utils.ts --file src/helpers.ts

Only reports issues in the specified files. Project-wide dependency issues are suppressed. Warns on non-existent paths.

Catch typos in entry file exports

fallow dead-code --format json --quiet --include-entry-exports

Reports unused exports in entry files (package.json main/exports, framework pages). By default, exports in entry files are assumed externally consumed. This flag catches typos like meatdata instead of metadata.

Debug why something is flagged

# Trace an export's usage chain
fallow dead-code --format json --quiet --trace src/utils.ts:myFunction
 
# Trace all edges for a file
fallow dead-code --format json --quiet --trace-file src/utils.ts
 
# Trace where a dependency is used
fallow dead-code --format json --quiet --trace-dependency lodash

Migrate from knip or jscpd

# Preview migration
fallow migrate --dry-run
 
# Apply migration (creates .fallowrc.json)
fallow migrate
 
# Migrate to TOML (creates fallow.toml)
fallow migrate --toml

Auto-detects knip.json, .knip.json, .jscpd.json, and package.json embedded configs.

Initialize a new config

fallow init              # creates .fallowrc.json, adds .fallow/ to .gitignore
fallow init --toml       # creates fallow.toml, adds .fallow/ to .gitignore
fallow init --hooks      # scaffold a pre-commit git hook
fallow init --hooks --branch develop  # hook using custom base branch

Exit Codes

When --format json is active and exit code is 2, errors are emitted as JSON on stdout:

{"error": true, "message": "invalid config: ...", "exit_code": 2}

Configuration

Fallow reads config from project root: .fallowrc.json > fallow.toml > .fallow.toml. Most projects work with zero configuration thanks to 90 auto-detecting framework plugins.