Skip to content
Back to search

fallow

Codebase intelligence for TypeScript and JavaScript. Health, complexity hotspots, duplication, architecture boundaries, circular dependencies, design-system drift, and unused code, from one graph. CLI, GitHub Action, LSP, MCP, and VS Code. Rust, MIT licensed.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 14 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/fallow-rs/fallow with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/fallow-rs/fallow'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fallow-rs--fallow/badge.svg)](/listings/fallow-rs--fallow)

HTML

<a href="/listings/fallow-rs--fallow"><img src="/api/listings/fallow-rs--fallow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 281 lines
  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fallow-rs/fallow/main/assets/logo-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/fallow-rs/fallow/main/assets/logo.svg">
  5. <img src="https://raw.githubusercontent.com/fallow-rs/fallow/main/assets/logo.svg" alt="fallow" width="290">
  6. </picture>
  7. </p>
  8. <p align="center">
  9. <strong>Codebase intelligence for TypeScript and JavaScript.</strong><br>
  10. Health, complexity, duplication, architecture, styling, and unused code, from one graph of your repository.<br>
  11. One Rust binary. It needs no TypeScript compiler and no configuration to start.
  12. </p>
  13. <p align="center">
  14. <a href="https://www.npmjs.com/package/fallow"><img src="https://img.shields.io/npm/v/fallow.svg" alt="npm"></a>
  15. <a href="https://www.npmjs.com/package/fallow"><img src="https://img.shields.io/npm/dm/fallow.svg" alt="npm downloads"></a>
  16. <a href="https://github.com/fallow-rs/fallow/actions/workflows/ci.yml"><img src="https://github.com/fallow-rs/fallow/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  17. <a href="https://github.com/fallow-rs/fallow/actions/workflows/coverage.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/fallow-rs/fallow/badges/coverage.json" alt="Coverage"></a>
  18. <a href="https://app.codspeed.io/fallow-rs/fallow?utm_source=badge"><img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed"></a>
  19. <a href="https://socket.dev/npm/package/fallow"><img src="https://img.shields.io/badge/socket-report-6e56cf" alt="Socket"></a>
  20. <a href="https://github.com/fallow-rs/fallow/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
  21. <a href="https://www.bestpractices.dev/projects/15640"><img src="https://www.bestpractices.dev/projects/15640/baseline" alt="OpenSSF Baseline"></a>
  22. </p>
  23. <p align="center">
  24. <a href="https://fallow.tools/docs/">Docs</a> ·
  25. <a href="https://fallow.tools/docs/quickstart/">Quickstart</a> ·
  26. <a href="#in-your-terminal">Terminal</a> ·
  27. <a href="#in-pull-requests">Pull requests</a> ·
  28. <a href="#editors-and-integrations">Editors</a> ·
  29. <a href="#with-coding-agents">Agents</a>
  30. </p>
  31. ---
  32. Run it in the root of any JS or TS project:
  33. ```bash
  34. npx fallow
  35. ```
  36. A pull request gate on a fictional storefront monorepo might look like this:
  37. ```
  38. $ npx fallow audit --base HEAD~15
  39. Audit scope: 73 changed files vs HEAD~15
  40. ● Circular dependencies (24)
  41. packages/storefront/src/orders/process.ts (6 cycles)
  42. → payment.ts → context.ts → process.ts
  43. ── Duplication ────────────────────────────────────
  44. ⚠ 185 lines (0.2%) duplicated across 6 files
  45. ● High complexity functions (28)
  46. packages/storefront/src/orders/payment.ts
  47. :566 processPayment CRITICAL
  48. 32 ! cyclomatic 47 ! cognitive 203 lines
  49. ── Styling ────────────────────────────────────────
  50. font sizes mix 3 units (3 px, 2 rem, 1 em; candidate, standardize unless intentional)
  51. ✗ dead code: 68 issues · complexity: 28 findings · duplication: 7 clone groups · 73 changed files
  52. audit gate excluded 98 inherited findings (run with --gate all to enforce)
  53. ```
  54. <sub>Illustrative output for a fictional project. The gate fails (exit code 1) on findings in changed files. Findings that existed before the change are excluded.</sub>
  55. fallow builds a repository graph of modules, exports, dependencies, functions, and styling tokens. Its analyses use that graph to find complexity, architecture drift, duplication, unused code, and risks in a pull request.
  56. fallow runs in four places. All four read the same config file and use the same analysis engine.
  57. | Where | Start with |
  58. |---|---|
  59. | [Your terminal](#in-your-terminal) | `npx fallow` |
  60. | [Pull requests](#in-pull-requests) | `uses: fallow-rs/fallow@v3` |
  61. | [Your editor](#editors-and-integrations) | The VS Code extension or `fallow-lsp` |
  62. | [Coding agents](#with-coding-agents) | `npx fallow agent install` |
  63. ## What fallow finds
  64. | Question | Analysis | Command |
  65. |---|---|---|
  66. | Is this change safe to merge? | [Changed-file gate](https://fallow.tools/docs/cli/audit/) over complexity, duplication, unused code, and styling drift, with a pass, warn, or fail result | `fallow audit` |
  67. | Where is the code hard to change? | [Complexity hotspots, a 0 to 100 health score, and refactoring targets](https://fallow.tools/docs/explanations/health/), with git churn and ownership | `fallow health` |
  68. | Does the architecture hold? | [Boundary violations](https://fallow.tools/docs/analysis/boundaries/) with `bulletproof`, `layered`, `hexagonal`, and `feature-sliced` presets, and circular dependencies | `fallow architecture`, `fallow guard` |
  69. | What is copied? | [Code duplication](https://fallow.tools/docs/analysis/duplication/) in JS, TS, CSS, and Vue, Svelte, and Astro components | `fallow dupes` |
  70. | Does the UI follow the design system? | [Styling drift](https://fallow.tools/docs/analysis/css-analysis/) in CSS and CSS-in-JS | `fallow health --css` |
  71. | What does nothing use? | [Unused files, exports, types, class and enum members, and dependencies](https://fallow.tools/docs/analysis/dead-code/), with an [auto-fix](https://fallow.tools/docs/analysis/auto-fix/) and a dry-run preview | `fallow dead-code`, `fallow fix` |
  72. | Do the tests detect a code change? | [Mutation testing](docs/mutation-testing.md): small changes in the source that no test detects (opt-in, runs the project tests) | `fallow mutation` |
  73. | Which code paths are risky? | Security candidates, ranked by reachability from entry points (opt-in) | `fallow security` |
  74. | Which functions do the same job? | Functions with the same intent and different syntax (opt-in, uses a local model that you download once) | `fallow similar-code` |
  75. | Where are the feature flags? | Feature-flag patterns across the codebase | `fallow flags` |
  76. `npx fallow viz` opens an interactive HTML map of the project with lenses for health, duplication, architecture, and unused code.
  77. Add `--type-aware` for exact TypeScript symbol identity across aliases, re-exports, and packages. This optional pass removes false positives from interfaces and base classes ([how type-aware analysis works](docs/type-aware-analysis.md)). [Runtime coverage](https://fallow.tools/docs/analysis/runtime-coverage/) from production is an optional add-on that fallow merges into health and audit reports.
  78. The [CLI reference](https://fallow.tools/docs/cli/global-flags/) lists every command. `fallow schema` prints all commands, flags, output formats, and exit codes as JSON.
  79. ## Why teams can depend on fallow
  80. fallow keeps these properties from release to release:
  81. - The same input gives the same output, with a stable fingerprint for each finding. There is no AI inside the analyzer. Only the opt-in `similar-code` command uses a pinned local model.
  82. - `fallow audit` fails only on findings that a change introduces. Existing findings do not fail the check.
  83. - It is fast on large codebases. fallow finds the unused code in the next.js monorepo (20,558 files) in 2.95s. Measured on fallow 2.100.0. [BENCHMARKS.md](BENCHMARKS.md) has the method and all results, and [CodSpeed](https://app.codspeed.io/fallow-rs/fallow) tracks performance on each change.
  84. - fallow reads npm, yarn, and pnpm workspaces, and `--workspace <name>` scopes a run to one package.
  85. - Over 100 built-in [framework plugins](https://fallow.tools/docs/frameworks/built-in/) find entry points and framework conventions, so the first run needs no config.
  86. - Each command has a typed JSON output, documented exit codes, and a published [output schema](docs/output-schema.json).
  87. - Analysis runs on your machine or CI runner. Telemetry is opt-in ([what fallow collects](docs/telemetry.md)).
  88. - The project has a public issue tracker, a public [roadmap](ROADMAP.md), and a [security policy](SECURITY.md).
  89. The analyzer is written in Rust and uses [Oxc](https://oxc.rs) for syntactic analysis. Static analysis needs no TypeScript compiler and no Node.js runtime.
  90. ## In your terminal
  91. ```bash
  92. npx fallow # health, duplication, and unused code in one run
  93. npx fallow audit # only the findings that your change introduces
  94. npx fallow fix --dry-run # preview the auto-fixes, then run `npx fallow fix`
  95. npx fallow health --score # health score with the largest deductions
  96. npx fallow dead-code --trace src/api.ts:client # prove an export is unused before you delete it
  97. ```
  98. To keep fallow in the project, install it as a dev dependency:
  99. ```bash
  100. npm install --save-dev fallow
  101. ```
  102. The npm package includes the `fallow`, `fallow-lsp`, and `fallow-mcp` launchers. For pnpm, yarn, `cargo install fallow-cli`, and Docker, see the [installation guide](https://fallow.tools/docs/installation/).
  103. To check each commit before it leaves your machine, install the managed pre-commit hook:
  104. ```bash
  105. npx fallow hooks install --target git
  106. ```
  107. ## Adopt fallow on an existing codebase
  108. You do not have to fix every finding before you add fallow to CI.
  109. 1. Run `npx fallow recommend`. It detects the stack and proposes a config. It changes no files.
  110. 2. Use `fallow audit` in pull requests. It compares each pull request with its base branch and blocks only the findings that the pull request adds. It needs no baseline file.
  111. 3. For full runs of `fallow`, `dead-code`, `dupes`, or `health`, save a baseline once with `npx fallow --save-baseline fallow-baseline.json`. Pass `--baseline fallow-baseline.json` on each later run, so that only new findings fail.
  112. 4. Reduce the backlog when your team has time. `fallow fix --dry-run` shows the fixes and changes no files. `fallow fix` applies them.
  113. If findings are caused by missing entry points or generated files, add the missing entry points and exclude the generated files in the config:
  114. ```json
  115. {
  116. "$schema": "./node_modules/fallow/schema.json",
  117. "entry": ["src/cli.ts"],
  118. "ignorePatterns": ["**/*.generated.ts"]
  119. }
  120. ```
  121. To keep an intentional export, add a suppression comment:
  122. ```ts
  123. // fallow-ignore-next-line unused-export -- kept for plugin consumers
  124. export const keepThis = 1;
  125. ```
  126. `// fallow-ignore-file <issue-type>` suppresses a whole file. JSDoc tags (`@public`, `@internal`) keep intentional library API quiet. `npx fallow suppressions` lists every suppression in the project.
  127. The [adoption guide](https://fallow.tools/docs/adoption/) shows the staged path. [Configuration](https://fallow.tools/docs/configuration/overview/) has the full reference.
  128. ## In pull requests
  129. GitHub Actions:
  130. ```yaml
  131. - uses: actions/checkout@v4
  132. with:
  133. fetch-depth: 0
  134. - uses: fallow-rs/fallow@v3
  135. with:
  136. command: audit
  137. ```
  138. GitLab CI:
  139. ```yaml
  140. include:
  141. - remote: 'https://raw.githubusercontent.com/fallow-rs/fallow/v3.43.0/ci/gitlab-ci.yml'
  142. fallow:
  143. extends: .fallow
  144. ```
  145. `fetch-depth: 0` is the recommended setup. A default shallow checkout also works for `command: audit`: the Action fetches the commits that it needs to find the merge base.
  146. To start in report-only mode, add `fail-on-issues: false`. Remove it when the team is ready for a gate. With `command: audit`, a pull request fails only on findings that it introduces. Without `command: audit`, the Action runs the full pipeline, and any finding fails the job (`fail-on-issues` defaults to true). In a pull request, the Action scopes the analysis to the changed files, so its output can differ from a full local run.
  147. The Action installs the fallow version that the project's `package.json` names. Pin an exact version there to use the same version in CI and on your machine. It can post a PR comment and inline review comments, and it can upload SARIF to GitHub Code Scanning. Other output formats are CodeClimate, GitHub annotations, and Markdown. The GitLab template URL names a release tag, because GitLab includes a file from a fixed ref. The [CI guide](https://fallow.tools/docs/integrations/ci/) covers inputs, permissions, and a staged rollout.
  148. For a PR comment or review comments, give the job these permissions. `id-token: write` is optional: it lets the Action post as the fallow bot. Without it, the comments come from `github-actions[bot]`.
  149. ```yaml
  150. permissions:
  151. contents: read
  152. id-token: write
  153. pull-requests: write
  154. checks: write
  155. ```
  156. Exit code 0 means no error-severity findings, or an audit result of pass or warn. Exit code 1 means error-severity findings, or an audit result of fail. In CI, exit code 1 fails the job, and that is the gate. The rule severity in the config (`error`, `warn`, `off`) sets which findings count. Exit code 2 means invalid input or an execution error. A script that reads the JSON output can treat 0 and 1 as a completed run, but must not hide exit code 2 with `|| true`.
  157. <details>
  158. <summary>All exit codes and the JSON error format</summary>
  159. | Exit code | Meaning |
  160. |---|---|
  161. | 0 | Clean, or audit result pass or warn |
  162. | 1 | Findings, or audit result fail (a normal outcome) |
  163. | 2 | Validation or runtime error (JSON error on stdout with `--format json`) |
  164. | 3 | A requested resource is unavailable, for example when `config --path` finds no config |
  165. | 8 | Security gate hit (`fallow security --gate`) |
  166. | 4 to 7, 10 to 13 | Runtime coverage, license, network, and upload errors |
  167. With `--format json`, an error arrives on stdout as `{"error": true, "message": "...", "exit_code": 2}`, not as a stack trace.
  168. </details>
  169. ## Editors and integrations
  170. - The [VS Code extension](https://fallow.tools/docs/integrations/vscode/) shows findings in the editor.
  171. - `fallow-lsp` gives diagnostics, hover, code actions, and code lenses in any LSP editor. [`editors/`](editors/) has setups for Zed and [Neovim](https://fallow.tools/docs/integrations/neovim/).
  172. - The Node API [`@fallow-cli/fallow-node`](https://fallow.tools/docs/integrations/node-bindings/) exports `detectDeadCode`, `detectCircularDependencies`, `detectBoundaryViolations`, `detectArchitecture`, `detectDuplication`, `detectSimilarCode`, `detectFeatureFlags`, `computeComplexity`, and `computeHealth`. The [package API reference](crates/napi/README.md) has the options and return types.
  173. - `fallow health --format badge > badge.svg` writes a [health badge](https://fallow.tools/docs/integrations/badges/) for your README.
  174. ## With coding agents
  175. ```bash
  176. npx fallow agent install --dry-run # show the plan
  177. npx fallow agent install # apply it
  178. ```
  179. `fallow agent install` sets up the agents that it detects (Claude Code, Codex, and Cursor) in one pass. It writes an `AGENTS.md` task map, installs the `fallow` and `fallow-setup` skills, registers the MCP server, and adds a gate on `git commit` and `git push`. Run `npx fallow agent status` to see these changes. Run `npx fallow agent uninstall` to remove them.
  180. To register only the [MCP server](https://fallow.tools/docs/integrations/mcp/):
  181. ```json
  182. { "mcpServers": { "fallow": { "command": "npx", "args": ["--yes", "--package", "fallow", "fallow-mcp"] } } }
  183. ```
  184. `--package fallow` selects the npm package that provides the `fallow-mcp` launcher.
  185. Scripts and agents that call the CLI directly add `--format json --quiet`. Each command then writes one typed JSON document to stdout:
  186. - A root `kind` field names the analysis that made the document.
  187. - Each finding has an `actions[]` array and an `auto_fixable` flag, so a script knows what `fallow fix` can do.
  188. - Root `next_steps[]` suggestions are commands that run as written.
  189. - The types ship as `fallow/types`, and [docs/output-schema.json](docs/output-schema.json) is the full schema.
  190. Do not run `fallow watch` in an agent loop, because it does not exit.
  191. Exit codes and the JSON error format are in [In pull requests](#in-pull-requests). The [agent skills guide](https://fallow.tools/docs/integrations/agent-skills/) has the details.
  192. ## Migrate existing config
  193. `npx fallow migrate` converts knip, jscpd, and stylelint config into fallow config. The migration guides for [knip](https://fallow.tools/docs/migration/from-knip/) and [jscpd](https://fallow.tools/docs/migration/from-jscpd/) show each step.
  194. ## Contributing
  195. To report a missing framework plugin or a false positive, [open an issue](https://github.com/fallow-rs/fallow/issues). [CONTRIBUTING.md](CONTRIBUTING.md) covers the development setup. [docs/README.md](docs/README.md) is the entry point for maintainer documentation.
  196. Thank you to everyone who contributes code, bug reports and ideas.
  197. <a href="https://github.com/fallow-rs/fallow/blob/badges/CONTRIBUTORS.md">
  198. <img src="https://raw.githubusercontent.com/fallow-rs/fallow/badges/contributors.png" alt="Contributors, including people who open issues. Follow the link for their names.">
  199. </a>
  200. ## License
  201. MIT. See [LICENSE](LICENSE).
  202. If fallow helps you or your team, you can support its development through [GitHub Sponsors](https://github.com/sponsors/fallow-rs).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.