# Fallow

> Fallow: codebase intelligence for JavaScript and TypeScript

- Skill: `sc30gsw/fallow` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add sc30gsw/fallow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sc30gsw/fallow/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: sc30gsw (https://skillmd.com/u/sc30gsw)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/sc30gsw/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:

```bash
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

| Command                       | Purpose                                                                                                                                                                                                                                                                                                                                                                                           | Key Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fallow`                      | Run all analyses: dead code + duplication + complexity (default)                                                                                                                                                                                                                                                                                                                                  | `--only`, `--skip`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--ci`, `--fail-on-issues`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline`, `--score`, `--trend`, `--save-snapshot`                                                                                                                                                                                                   |
| `dead-code`                   | Dead code analysis (`check` is an alias)                                                                                                                                                                                                                                                                                                                                                          | `--unused-exports`, `--changed-since`, `--changed-workspaces`, `--production`, `--file`, `--include-entry-exports`, `--stale-suppressions`, `--ci`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline`                                                                                                                                                                                                                               |
| `dupes`                       | Code duplication detection                                                                                                                                                                                                                                                                                                                                                                        | `--mode`, `--threshold`, `--top`, `--changed-since`, `--workspace`, `--changed-workspaces`, `--skip-local`, `--cross-language`, `--ignore-imports`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline`                                                                                                                                                                                                                                                          |
| `fix`                         | Auto-remove unused exports/deps                                                                                                                                                                                                                                                                                                                                                                   | `--dry-run`, `--yes` (required in non-TTY)                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `init`                        | Generate config file or pre-commit hook                                                                                                                                                                                                                                                                                                                                                           | `--toml`, `--hooks`, `--branch`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `migrate`                     | Convert knip/jscpd config                                                                                                                                                                                                                                                                                                                                                                         | `--dry-run`, `--from PATH`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `list`                        | Inspect project structure                                                                                                                                                                                                                                                                                                                                                                         | `--files`, `--entry-points`, `--plugins`, `--boundaries`                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `health`                      | Function complexity analysis (also covers Angular templates as synthetic `<template>` findings: external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })`literals; suppress external with`<!-- fallow-ignore-file complexity -->`at the top of the`.html`file, suppress inline with`// fallow-ignore-next-line complexity`directly above the`@Component` decorator) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
| `audit`                       | Combined dead-code + complexity + duplication for changed files                                                                                                                                                                                                                                                                                                                                   | `--base`, `--gate`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`                                                                                                                                                                                                                                  |
| `flags`                       | Detect feature flag patterns (env vars, SDK calls, config objects)                                                                                                                                                                                                                                                                                                                                | `--top`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `explain`                     | Explain one issue type without running analysis                                                                                                                                                                                                                                                                                                                                                   | `<issue-type>`, `--format json`                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `license`                     | Manage the local license JWT for continuous/cloud runtime monitoring (activate, status, refresh, deactivate)                                                                                                                                                                                                                                                                                      | `activate --trial --email <addr>`, `activate --from-file`, `activate --stdin`, `status`, `refresh`, `deactivate`                                                                                                                                                                                                                                                                                                                                                                                          |
| `coverage`                    | Runtime coverage setup, focused analysis, and cloud inventory workflow helper                                                                                                                                                                                                                                                                                                                     | `setup`, `setup --yes`, `setup --non-interactive`, `analyze --runtime-coverage <path>`, `analyze --cloud --repo owner/repo`, `upload-inventory`                                                                                                                                                                                                                                                                                                                                                           |
| `coverage upload-source-maps` | Upload build source maps from CI so bundled runtime coverage resolves to original source paths                                                                                                                                                                                                                                                                                                    | `--dir dist`, `--git-sha <sha>`, `--repo <name>`, `--strip-path=false`, `--dry-run`                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `schema`                      | Dump CLI definition as JSON                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `config`                      | Show the loaded config path and resolved config (verifies which `.fallowrc.json` is in effect)                                                                                                                                                                                                                                                                                                    | `--path`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Issue Types

| Type                   | Filter Flag              | Description                                                                                                                                                                                                                                                                                 |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unused files           | `--unused-files`         | Files unreachable from entry points                                                                                                                                                                                                                                                         |
| Unused exports         | `--unused-exports`       | Symbols never imported elsewhere                                                                                                                                                                                                                                                            |
| Unused types           | `--unused-types`         | Type aliases and interfaces                                                                                                                                                                                                                                                                 |
| Private type leaks     | `--private-type-leaks`   | Opt-in API hygiene check (default `off`) for exported signatures whose type references a same-file private type                                                                                                                                                                             |
| Unused dependencies    | `--unused-deps`          | Packages in `dependencies`, `devDependencies`, `optionalDependencies`, type-only production deps, and test-only production deps. In monorepos, internal workspace package names (e.g., `@repo/ui`) declared in another workspace's `package.json` but never imported are reported here too. |
| Unused enum members    | `--unused-enum-members`  | Enum values never referenced                                                                                                                                                                                                                                                                |
| Unused class members   | `--unused-class-members` | Methods and properties                                                                                                                                                                                                                                                                      |
| Unresolved imports     | `--unresolved-imports`   | Imports that can't be resolved                                                                                                                                                                                                                                                              |
| Unlisted dependencies  | `--unlisted-deps`        | Used packages missing from package.json. In monorepos, importing a workspace package from a workspace whose own `package.json` does not list it is reported here too; self-references stay allowed without requiring a package to depend on itself.                                         |
| Duplicate exports      | `--duplicate-exports`    | Same symbol exported from multiple modules                                                                                                                                                                                                                                                  |
| Circular dependencies  | `--circular-deps`        | Import cycles in the module graph                                                                                                                                                                                                                                                           |
| Boundary violations    | `--boundary-violations`  | Imports crossing architecture zone boundaries. Presets: `layered`, `hexagonal`, `feature-sliced`, `bulletproof`                                                                                                                                                                             |
| Stale suppressions     | `--stale-suppressions`   | `fallow-ignore` comments or `@expected-unused` JSDoc tags that no longer match any issue                                                                                                                                                                                                    |
| Test-only dependencies | n/a                      | Production deps only imported from test files (should be devDependencies)                                                                                                                                                                                                                   |

## MCP Tools

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

| Tool                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `analyze`                | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + boundary violations + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group                    |
| `check_changed`          | Incremental analysis of files changed since a git ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `find_dupes`             | Code duplication detection. Set `changed_since` to scope to changed files since a git ref                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `fix_preview`            | Dry-run auto-fix preview                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `fix_apply`              | Apply auto-fixes (destructive)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `check_health`           | Complexity metrics, health scores, hotspots, and refactoring targets. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field                                                                                                                                                                                                                                                                                         |
| `check_runtime_coverage` | Merge V8 or Istanbul runtime-coverage data into the health report. One local capture is free; continuous/cloud or multi-capture runtime monitoring is paid. Required `coverage` param (V8 dir, V8 JSON, or Istanbul `coverage-final.json`). Tuning knobs: `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), `low_traffic_threshold` (default 0.001), `max_crap` (default 30.0), `top`, `group_by`. Long dumps may exceed the 120s MCP timeout; raise `FALLOW_TIMEOUT_SECS`. Pick this over `check_health` when you have a coverage dump. |
| `get_hot_paths`          | Runtime-context slice over the same runtime coverage pipeline. Same params as `check_runtime_coverage`; read `runtime_coverage.hot_paths` for production hot paths.                                                                                                                                                                                                                                                                                                                                                                                                  |
| `get_blast_radius`       | Runtime-context slice for blast-radius review. Same params as `check_runtime_coverage`; until `runtime_coverage.blast_radius` ships, combine `file_scores[].fan_in`, `runtime_coverage.hot_paths`, and `runtime_coverage.findings`.                                                                                                                                                                                                                                                                                                                                  |
| `get_importance`         | Runtime-context slice for production-importance review. Same params as `check_runtime_coverage`; until `runtime_coverage.importance` ships, combine `runtime_coverage.hot_paths`, `file_scores`, `hotspots`, and `targets`.                                                                                                                                                                                                                                                                                                                                          |
| `get_cleanup_candidates` | Runtime-context slice for cleanup review. Same params as `check_runtime_coverage`; read `runtime_coverage.findings` for `safe_to_delete`, `review_required`, `low_traffic`, and `coverage_unavailable`.                                                                                                                                                                                                                                                                                                                                                              |
| `audit`                  | Combined dead-code + complexity + duplication for changed files, returns verdict. Set `gate` to `"new-only"` or `"all"`                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `fallow_explain`         | Explain one issue type without running analysis. Required `issue_type`; returns rationale, examples, fix guidance, and docs URL                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `project_info`           | Project metadata. Set `entry_points`, `files`, `plugins`, or `boundaries` to `true` to request specific sections                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `list_boundaries`        | Architecture boundary zones and access rules. Returns `{"configured": false}` if no boundaries configured                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `feature_flags`          | Detect feature flag patterns (env vars, SDK calls, config objects). Set `top` to limit results                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `trace_export`           | Trace why an export is used or unused (`fallow dead-code --trace FILE:EXPORT_NAME --format json`). Required `file` and `export_name`. Returns file reachability, entry-point status, direct references, re-export chains, and a reason string. Use before deleting a supposedly-unused export                                                                                                                                                                                                                                                                        |
| `trace_file`             | Trace all graph edges for a file (`fallow dead-code --trace-file PATH --format json`). Required `file`. Returns reachability, exports, imports-from, imported-by, and re-exports. Use to decide whether a file is isolated, barrel-only, or imported by live entry points                                                                                                                                                                                                                                                                                            |
| `trace_dependency`       | Trace where a dependency is imported (`fallow dead-code --trace-dependency PACKAGE --format json`). Required `package_name`. Returns importing files, type-only importers, total import count, `used_in_scripts` (true when invoked from package.json scripts or CI configs), and `is_used` (combined import + script signal; mirrors the unused-deps detector so build tools like `microbundle` or `vitest` are not falsely flagged as unused). Use before removing a dependency or moving between `dependencies` and `devDependencies`                             |
| `trace_clone`            | Trace duplicate-code groups at a location (`fallow dupes --trace FILE:LINE --format json`). Required `file` and `line`. Returns the matched clone instance plus every clone group containing it. Supports `mode`, `min_tokens`, `min_lines`, `threshold`, `skip_local`, `cross_language`, `ignore_imports`. Use to consolidate duplication when you need the exact sibling locations                                                                                                                                                                                 |

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.

```bash
npm install @fallow-cli/fallow-node
```

```ts
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](references/cli-reference.md): complete command and flag specifications
- [Gotchas](references/gotchas.md): common pitfalls, edge cases, and correct usage patterns
- [Patterns](references/patterns.md): workflow recipes for CI, monorepos, migration, and incremental adoption

## Common Workflows

### Audit a project for all dead code

```bash
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)