# Quick start

> Get your first list of unused code, duplication, and complexity hotspots in under a minute. Then add fallow to VS Code, CI, MCP, or Fallow Cloud.

> Page index of all docs: https://fallow.tools/llms.txt
> Docs MCP server (search and read the docs): https://fallow.tools/docs/mcp
> HTML version of this page: https://fallow.tools/docs/quickstart/

In under a minute, you get a list of unused code, duplication, and complexity hotspots in your project. Everyone starts with the same command. At the end, pick the integration that fits your work.

## 1. Run fallow

From your project root, run:

```bash
npx fallow
```

This command runs these analyses in one pass:

- **Dead code**: unused files, exports, dependencies, and more
- **Architecture**: import cycles, boundary violations, and rule-pack policy violations
- **Duplication**: repeated logic across files
- **Health**: complexity hotspots and refactor targets

> **Tip:** Built-in plugins cover Next.js, Vite, Ember, Wuchale, Jest, Tailwind, PandaCSS, Contentlayer, tap, tsd, and more. The first run needs no configuration.

## 2. Run the focused commands you'll use most

```bash
npx fallow dead-code          # Cleanup candidates
npx fallow architecture       # Import cycles, boundaries, and policy rules
npx fallow dupes              # Repeated logic
npx fallow health             # Complexity and refactor targets
npx fallow review             # Advisory review brief over changed files (always exits 0)
npx fallow fix --dry-run      # Preview automatic cleanup
```

- `dead-code` reports unused files, exports, types, and dependencies. See the [dead code guide](https://fallow.tools/docs/analysis/dead-code/).
- `architecture` reports circular dependencies, re-export cycles, package cycles, boundary violations, and rule-pack policy violations. See [`fallow architecture`](https://fallow.tools/docs/cli/architecture/).
- `dupes` finds AST-based duplicates in the default `mild` mode. To also find clones with renamed variables, add `--mode semantic`. See the [duplication guide](https://fallow.tools/docs/analysis/duplication/).
- `health` reports complexity findings, maintainability per file, hotspots, and ranked refactor targets. See the [health explanation](https://fallow.tools/docs/explanations/health/).
- `fix --dry-run` shows the automatic cleanup without changing files. To apply it, remove `--dry-run`. See the [auto-fix guide](https://fallow.tools/docs/analysis/auto-fix/).

> **Tip:** To clean up or refactor TypeScript, add `--type-aware` when aliases,
> re-exports, class contracts, packages, or exact consumers affect the
> decision. This optional semantic pass is slower. See
> [Type-aware TypeScript analysis](https://fallow.tools/docs/analysis/type-aware/).

## 3. Pick your next step

> **Info:** Does your existing repo have a backlog of findings? Follow [Adopt Fallow in an existing repo](https://fallow.tools/docs/adoption/) for a step-by-step cleanup. Then come back here to set up CI or VS Code.

- [Use it in VS Code](https://fallow.tools/docs/integrations/vscode/): Get real-time diagnostics, Code Lens above exports, and one-click fixes.
- [Use it in CI](https://fallow.tools/docs/integrations/ci/): Use fallow as a PR and merge gate, with SARIF or MR annotations.
- [Use it from agents](https://fallow.tools/docs/integrations/mcp/): Add MCP to give Claude Code, Cursor, and other agents structured tool calls.
- [Add runtime evidence](https://fallow.tools/docs/analysis/runtime-coverage/): Add production execution data to `fallow health`.

## Optional: create a config

Fallow works without a config file. To customize it, run:

```bash
fallow init
```

`fallow init` detects your project structure and writes a config for it. It also adds `.fallow/` to your `.gitignore`.

**.fallowrc.json**

```jsonc
{
  "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
  "entry": ["src/workers/*.ts", "scripts/*.ts"],
  "ignorePatterns": ["**/*.generated.ts"],
  "rules": {
    "unused-files": "error",
    "unused-exports": "warn",
    "unused-types": "off"
  }
}
```

**fallow.toml**

```toml
entry = ["src/workers/*.ts", "scripts/*.ts"]
ignorePatterns = ["**/*.generated.ts"]

[rules]
unused-files = "error"
unused-exports = "warn"
unused-types = "off"
```

> **Info:** To migrate from knip or jscpd, run `fallow migrate`, or read the [knip](https://fallow.tools/docs/migration/from-knip/) or [jscpd](https://fallow.tools/docs/migration/from-jscpd/) guide.

## Optional: Fallow Cloud

The static layer of fallow is free and open source (MIT). To learn which code actually executed in production, add Fallow Cloud, the paid product. A single local capture is free. The trial below turns on continuous and multi-capture monitoring for 30 days:

```bash
npx fallow license activate --trial --email you@company.com
npx fallow coverage setup
npx fallow health --runtime-coverage ./coverage
```

Before you start, read [Static analysis vs production data](https://fallow.tools/docs/explanations/static-vs-runtime/) to learn how the two layers differ. Then follow the [runtime coverage guide](https://fallow.tools/docs/analysis/runtime-coverage/) for the setup.

## See also {#next-steps}

- [Analysis overview](https://fallow.tools/docs/analysis/): See what fallow analyzes.
- [Configuration](https://fallow.tools/docs/configuration/overview/): Customize entry points, rules, and ignore patterns.
- [Explanations](https://fallow.tools/docs/explanations/): Learn how fallow works.
- [CLI reference](https://fallow.tools/docs/cli/dead-code/): Look up every command and flag.