How to use Fallow

Use the repository's pinned Fallow CLI to inspect code health, review changed code, and preview safe fixes. Run each command from the repository root.

Fallow reads the root .fallowrc.json file and the pinned 3.21.0 dependency. The configuration sets the analysis rules and production mode for this repository.

Prepare the local tool

Install the repository tools before you run a Fallow command:

mise install

The local pnpm script resolves the repository dependency. Do not install a second Fallow version for this repository.

Run a full analysis

Run Fallow without a subcommand to analyze unused code, duplication, and code health across the repository:

pnpm fallow --format json --quiet

The full analysis returns Fallow's command-specific JSON output. Read the check, health, dupes, and next_steps fields when they are present. Do not wrap this output in a new schema.

The root policy enables production mode. Pass --production when a command must state that mode explicitly:

pnpm fallow --production --format json --quiet

Scope an analysis to a workspace

Pass a workspace name or pattern to limit the report:

pnpm fallow --workspace "<workspace-name>" --format json --quiet

Fallow accepts an exact workspace name, a glob pattern, or a negated pattern. Use the workspace package name from the repository configuration.

Audit changed code

Use the audit command before you commit code or open a pull request:

pnpm fallow audit --base main --format json --quiet

Replace main with the correct comparison ref when the branch uses another base. The --base option is an alias for --changed-since.

The audit uses a new-only gate by default. It reports a verdict of pass, warn, or fail. A failed verdict blocks the audit command.

Use these fields to process the audit result:

• verdict gives the quality gate result.
• summary gives category counts and severity information.
• dead_code, complexity, and duplication give finding details when Fallow reports findings.
• attribution separates introduced findings from inherited findings.
• base_ref, head_sha, and changed_files_count identify the audit scope.

Use --pretty when a person must read the JSON in a terminal:

pnpm fallow audit --base main --format json --pretty

Keep the JSON output unchanged when an agent or script consumes it. Use the documented Fallow fields instead of a repository-specific output format.

Investigate findings before deletion

Treat an unused symbol or file as a lead for investigation. Check entry points, dynamic imports, package exports, and runtime configuration before deletion.

Inspect the file or trace the symbol with Fallow:

pnpm fallow inspect --file <path>
pnpm fallow dead-code --trace <path>:<symbol>

Use type-aware symbol impact when a TypeScript symbol needs stronger evidence:

pnpm fallow dead-code --type-aware --symbol-impact <path>:<symbol>

Do not delete an item only because Fallow labels it as unused.

Preview automatic fixes

Fallow can propose changes to source files and dependencies. Preview every change before you apply it:

pnpm fallow fix --dry-run --no-create-config --format json --quiet

Review the proposed file and configuration changes. Apply a fix only after explicit approval:

pnpm fallow fix --yes --no-create-config --format json --quiet

Agents must keep the default workflow read-only. Agents must not apply a fix without explicit user approval.

Configure VS Code diagnostics

The Fallow VS Code extension is optional. Install it with:

code --install-extension fallow-rs.fallow-vscode

Open the repository root as the VS Code workspace. The extension checks fallow.lspPath, the local node_modules binary, and the system PATH in that order. The local binary uses the repository dependency and .fallowrc.json.

If the extension does not find the local binary, set the path in workspace settings:

{
  "fallow.lspPath": "${workspaceFolder}/node_modules/.bin/fallow"
}

Do not add an MCP server or a Fallow Cloud integration for this local workflow.

Keep policy changes explicit

Keep Fallow analysis read-only by default. Change .fallowrc.json only with an explicit reason in the pull request.

This rule applies to:

• new ignore patterns or ignored dependencies;
• rule suppressions or lower rule severity;
• wider duplication or complexity thresholds;
• changes to production mode.

Some dependencies are required by a framework or bundler but have no direct source import. Add these packages to ignoreDependencies only when the runtime or build requires them. Explain the reason in the change. For example, the Mermaid integration requires cytoscape during the documentation build.

Describe the affected code, the reason for the policy change, and the plan to remove the exception when you add a suppression or widen a threshold.