fallow: codebase intelligence for TypeScript and JavaScript

Fallow reads a small set of environment variables to override default behavior. These are useful for CI pipelines, editor integrations, and the MCP server.

Variable	Description	Values
`FALLOW_FORMAT`	Default output format	`human`, `json`, `sarif`, `compact`, `markdown`, `codeclimate`, `gitlab-codequality`, `pr-comment-github`, `pr-comment-gitlab`, `review-github`, `review-gitlab`, `badge`
`FALLOW_QUIET`	Suppress progress output	`1` or `true`
`FALLOW_BIN`	Path to the fallow binary	Any valid path
`FALLOW_EXTENDS_TIMEOUT_SECS`	Timeout for fetching URL extends	Seconds (default: `5`)
`FALLOW_PRODUCTION`	Global production-mode override for every analysis	`true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`
`FALLOW_PRODUCTION_DEAD_CODE`	Per-analysis production override for dead-code (combined runs and `fallow audit`)	Same values as `FALLOW_PRODUCTION`
`FALLOW_PRODUCTION_HEALTH`	Per-analysis production override for health	Same values as `FALLOW_PRODUCTION`
`FALLOW_PRODUCTION_DUPES`	Per-analysis production override for duplication	Same values as `FALLOW_PRODUCTION`
`FALLOW_REVIEW_GUIDANCE`	Add collapsed “What to do” blocks to `review-github` / `review-gitlab` inline comments	`1`, `true`, `yes`, `on`
`FALLOW_SUMMARY_SCOPE`	Sticky PR/MR summary scope for `pr-comment-github` / `pr-comment-gitlab`. `all` keeps project-level dependency/catalog/override findings outside the diff; `diff` applies the diff filter to those findings too. Inline review comments are unaffected	`all` (default), `diff`
`FALLOW_PR_COMMENT_LAYOUT`	Sticky PR/MR summary layout for `pr-comment-github` / `pr-comment-gitlab`. Use `gate-only` when a native Check Run or Code Quality widget is the primary surface	`default`, `compact`, `gate-only`, `details`
`FALLOW_CACHE_DIR`	Override the extraction cache directory	Any valid path
`FALLOW_AUDIT_BASE`	Pin the `fallow audit` comparison base when `--base` / `--changed-since` is unset (escape hatch for the agent gate and forks)	Any git ref (e.g. `origin/main`, `upstream/main`)
`FALLOW_AUDIT_CACHE_MAX_AGE_DAYS`	Max age of persistent reusable `fallow audit` base-snapshot worktree caches	Whole days (default `30`; `0` disables)
`FALLOW_IMPACT_STORE_MAX_AGE_DAYS`	Reclaim per-project `fallow impact` stores older than this; a recorded run sweeps stale stores (e.g. from deleted repos)	Whole days (unset / `0` keeps every store forever)
`FALLOW_MAX_FILE_SIZE`	Skip source files larger than this many megabytes at discovery and skip large one-line minified JS assets while the guard is enabled (mirrors `--max-file-size`; `.d.ts` always analyzed)	Whole megabytes (default `5`; `0` disables)
`FALLOW_UPDATE_CHECK`	Disable the local human-TTY upgrade nudge and background latest-version check	`off`, `0`, `false`, `disabled`, `no`
`FALLOW_SUGGESTIONS`	Suppress the `next_steps[]` array of read-only follow-up commands in JSON output and the human `Next:` line	`off`, `0`, `false`, `no`, `disabled` (default on)
`FALLOW_TELEMETRY`	Opt-in telemetry mode, off by default (see what it collects)	`off`/`on`/`inspect` (plus `0`/`1`/`true`/`false`/`disabled`/`enabled`/`debug`/`log`)
`FALLOW_TELEMETRY_DISABLED`	Admin/fleet telemetry kill switch (top precedence)	`1`, `true`, `yes`, `on`
`FALLOW_TELEMETRY_DEBUG`	Forces inspect mode (outranks `FALLOW_TELEMETRY`)	`1`, `true`, `yes`, `on`
`DO_NOT_TRACK`	Honored as a top-precedence telemetry kill switch	`1`, `true`, `yes`, `on`
`FALLOW_AGENT_SOURCE`	Declare the calling agent for telemetry classification (never enables telemetry)	`codex`, `claude_code`, `cursor`, `copilot`, `opencode`, `aider`, `roo`, `windsurf`, `gemini` (aliases `gemini_cli`/`antigravity`), `cline`, `continue`, `zed`, `goose`, `other_known`, `unknown`, `none`
`FALLOW_INTEGRATION_SURFACE`	Declare the telemetry integration surface (set by the MCP server on the CLI it invokes; never enables telemetry)	`mcp`, `lsp`, `vscode`, `napi`, `programmatic`
`FALLOW_MCP_TOOL`	Declare the MCP tool name for the telemetry `mcp_tool` dimension (set by the MCP server; validated against a fixed allowlist, otherwise dropped; never enables telemetry)	An allowlisted MCP tool name (for example `find_dupes`, `audit`)

FALLOW_FORMAT

Set the default output format so you don’t need to pass --format every time.

export FALLOW_FORMAT=json
fallow dead-code   # Outputs JSON without --format flag

The --format CLI flag takes precedence over FALLOW_FORMAT when both are set.

FALLOW_QUIET

Suppress progress bars and status messages. Useful in CI environments or when piping output.

export FALLOW_QUIET=1
fallow dead-code   # No progress output, only results

Equivalent to passing --quiet on every command.

FALLOW_BIN

Path to the fallow binary. Used by the MCP server (fallow-mcp) to locate the fallow CLI.

export FALLOW_BIN=/usr/local/bin/fallow
fallow-mcp   # MCP server uses the specified binary

Defaults to fallow on PATH when not set.

FALLOW_EXTENDS_TIMEOUT_SECS

Timeout in seconds for fetching remote configs via https:// URLs in the extends field.

export FALLOW_EXTENDS_TIMEOUT_SECS=10
fallow dead-code   # URL extends have 10s to respond

Defaults to 5 seconds when not set.

FALLOW_CACHE_DIR

Directory for the persistent extraction cache. Wins over the cache.dir config field when both are set.

export FALLOW_CACHE_DIR=/tmp/fallow-cache
fallow dead-code   # cache files are stored under /tmp/fallow-cache

By default, fallow stores the cache in .fallow/cache.bin under the project root. Use this env var when the project checkout is read-only, when CI has a dedicated cache volume, or when multiple workspace copies should share a stable cache location. --no-cache disables the cache entirely; this env var is then irrelevant.

FALLOW_CACHE_MAX_SIZE

Maximum on-disk extraction cache (.fallow/cache.bin) size in megabytes. Wins over the cache.maxSizeMb config field when both are set.

export FALLOW_CACHE_MAX_SIZE=64
fallow dead-code   # cache capped at 64 MB

Defaults to 256 (MB) when not set. The cache triggers LRU eviction when its serialized size crosses 80% of the cap and evicts down to 60%. Intended for CI runners with disk quotas; local dev machines on full-size disks rarely need to touch this knob. --no-cache disables the cache entirely; this env var is then irrelevant.

FALLOW_AUDIT_BASE

Pins the fallow audit comparison base. It takes effect only when neither --base nor --changed-since is passed, so the precedence is --base flag, then FALLOW_AUDIT_BASE, then auto-detection.

export FALLOW_AUDIT_BASE=upstream/main
fallow audit   # compares against upstream/main instead of the auto-detected base

When unset, fallow audit auto-detects the base as the git merge-base (fork point) against the branch’s upstream or the remote default (origin/HEAD, then origin/main, then origin/master). That is the right answer for most repositories, but two cases want an explicit pin:

Forks. On a fork, origin is your fork (which can lag the real upstream), so set FALLOW_AUDIT_BASE=upstream/main to compare against the true upstream.
The agent gate. fallow hooks install --target agent generates a hook that runs bare fallow audit. If your team works entirely in git worktrees and never updates the local default branch, the env var lets you pin the base without editing the generated script (which is regenerated on reinstall).

A malformed value (a ref with disallowed characters) fails the audit with exit code 2 rather than being silently ignored, so a typo surfaces immediately.

FALLOW_AUDIT_CACHE_MAX_AGE_DAYS

Maximum age (in whole days, since last reuse or fresh create) of a persistent reusable fallow audit base-snapshot worktree cache. Older entries are removed at the top of the next fallow audit invocation. Wins over the audit.cacheMaxAgeDays config field when both are set.

export FALLOW_AUDIT_CACHE_MAX_AGE_DAYS=7
fallow audit --base origin/main   # caches older than 7 days are reclaimed

Defaults to 30 days when not set. Setting the value to 0 disables the GC entirely (escape hatch for CI runners that prune /tmp out-of-band). Invalid values (non-integer, negative) silently fall back to the config field / default; a typo in a runner env var does not fail audits. The sweep runs once per fallow audit invocation, walks git-registered worktrees only (not raw /tmp content), and never removes a cache entry that another in-flight fallow audit is using (per-entry kernel flock(2) guard). On reclaim, fallow writes a single fallow: reclaimed N stale base-snapshot caches line to stderr (unless --quiet is set) so the disk-space recovery is observable.

FALLOW_IMPACT_STORE_MAX_AGE_DAYS

Reclaim per-project fallow impact stores that have not been touched in this many whole days. Impact keeps one small history file per project in your user config directory; over time, projects you delete from disk leave their stores behind. Set this so a recorded run prunes them.

export FALLOW_IMPACT_STORE_MAX_AGE_DAYS=90
fallow audit --base origin/main   # impact stores untouched for 90+ days are reclaimed

Unset (the default) keeps every store forever; 0 and invalid values are treated the same way (no sweep), so a typo never deletes history. Age is the store file’s modification time, and any recorded run rewrites the file, so an actively-tracked project never ages out. The sweep never touches the project you just recorded, never deletes the advisory .lock sidecars, and never the global impact.json opt-in toggle. Because impact only records on developer machines (never in CI), this is purely local housekeeping.

FALLOW_UPDATE_CHECK

Local human runs can show a one-line upgrade hint when a cached latest-version check says the installed fallow is stale. The hint is suppressed for machine formats, CI, quiet runs, and non-TTY agent paths. Set FALLOW_UPDATE_CHECK=off to disable both the hint and the background latest-version check on that machine. DO_NOT_TRACK and FALLOW_TELEMETRY_DISABLED also suppress it.

FALLOW_SUGGESTIONS

dead-code, health, dupes, bare fallow, and audit add a top-level next_steps[] array of read-only follow-up commands to their --format json output (and a one-line Next: hint to bare fallow’s human output on a TTY), computed from the run’s findings. Set FALLOW_SUGGESTIONS=off (or 0/false/no/disabled) to suppress it; this is the escape hatch for CI consumers that snapshot-diff raw JSON output. The variable is inherited by the MCP-spawned CLI, so it also disables next_steps on MCP responses.

FALLOW_PRODUCTION and per-analysis overrides

FALLOW_PRODUCTION mirrors the --production CLI flag and turns production mode on for every analysis. The per-analysis vars (FALLOW_PRODUCTION_DEAD_CODE, FALLOW_PRODUCTION_HEALTH, FALLOW_PRODUCTION_DUPES) target a single analysis when running bare combined mode (fallow with no subcommand) or fallow audit.

# Run combined mode with production-only health, full-tree dead-code and dupes
export FALLOW_PRODUCTION_HEALTH=true
fallow --format json --quiet

Precedence (highest to lowest):

CLI flags (--production, --production-{dead-code,health,dupes})
Per-analysis env var (FALLOW_PRODUCTION_HEALTH, etc.)
Global env var (FALLOW_PRODUCTION)
Config (production: true legacy form, or production: { health: true, ... } per-analysis form)

Per-analysis env beats global env, so FALLOW_PRODUCTION=false FALLOW_PRODUCTION_HEALTH=true runs health in production mode and the other analyses in non-production mode. Single-subcommand runs (e.g. fallow health) still respect FALLOW_PRODUCTION_HEALTH even though the per-analysis CLI flag is rejected with a subcommand: pass --production or set the per-analysis env var.

Set FALLOW_FORMAT=json and FALLOW_QUIET=1 in CI pipelines for clean machine-readable output.

FALLOW_COVERAGE

Path to Istanbul coverage data (coverage-final.json) used for accurate per-function CRAP scores in fallow health, fallow audit, and bare fallow. The --coverage CLI flag wins when both are set. Standalone health and bare fallow fall back to health.coverage when both CLI and env inputs are omitted.

export FALLOW_COVERAGE=./coverage/coverage-final.json
fallow health

FALLOW_COVERAGE_ROOT

Absolute prefix to strip from Istanbul coverage paths before matching files. Use it when coverage was generated in a different checkout root, such as CI or Docker. The --coverage-root CLI flag wins when both are set. Standalone health and bare fallow fall back to health.coverageRoot when both CLI and env inputs are omitted.

FALLOW_MAX_FILE_SIZE

Per-file size ceiling in megabytes for source discovery (default 5; 0 = no limit). Source files strictly larger are skipped before parsing, guarding against out-of-memory blowups from a single multi-megabyte generated or bundled file. The --max-file-size CLI flag wins when both are set. Declaration files (.d.ts) are always analyzed.

Review and PR-comment formats

These variables tune the review-github / review-gitlab / pr-comment-github / pr-comment-gitlab output formats. The bundled GitHub Action and GitLab CI template set them for you; set them yourself only when rendering these formats outside the bundled integrations.

Variable	Effect
`FALLOW_ROOT`	Project root the review renderers read source from for suggestion blocks. Set alongside `--root`.
`FALLOW_REVIEW_GUIDANCE`	Set to `true` to append collapsed per-finding guidance blocks to review inline comment bodies.
`FALLOW_SUMMARY_SCOPE`	`all` (default) keeps project-level dependency/catalog/override findings outside the diff filter in PR-comment summaries; `diff` applies the diff filter to them too.
`FALLOW_PR_COMMENT_LAYOUT`	Sticky PR/MR summary layout for `pr-comment-github` / `pr-comment-gitlab`. Values: `default`, `compact`, `gate-only`, or `details`. Use `gate-only` when a native Check Run or Code Quality widget is the primary surface.
`FALLOW_DIFF_CONTEXT`	Line radius around changed diff lines when scoping findings to a diff (default `3`).
`FALLOW_BOT_LOGIN`	Bot or token username treated as fallow’s own when reconciling existing PR/MR comments. Required when posting with a personal access token.
`FALLOW_API_RETRIES`	Maximum HTTP attempts for review-comment reconciliation API calls (default `3`).
`FALLOW_API_RETRY_DELAY`	Floor delay in seconds between HTTP retries (default `2`); a server-supplied `Retry-After` overrides it on 429 responses.

License and cloud

These variables configure the paid runtime intelligence layer and fallow cloud connectivity. See fallow license and fallow coverage.

Variable	Effect
`FALLOW_LICENSE`	License JWT (full string); intended for shared CI runners.
`FALLOW_LICENSE_PATH`	File path containing the license JWT.
`FALLOW_LICENSE_SKEW_TOLERANCE_SECONDS`	Clock-skew tolerance applied to the license JWT’s `iat` claim (default `86400`).
`FALLOW_COV_BIN`	Explicit path override for the `fallow-cov` runtime-coverage sidecar binary.
`FALLOW_COV_BINARY_PATH`	Secondary sidecar path override, checked after `FALLOW_COV_BIN` (air-gapped installs, distro-packaged sidecars).
`FALLOW_RUNTIME_COVERAGE_SOURCE`	Set to `cloud` to select cloud runtime coverage in `fallow coverage analyze` without passing `--cloud`.
`FALLOW_REPO`	`owner/repo` fallback for `fallow coverage analyze --cloud` when `--repo` is not passed.
`FALLOW_API_URL`	Base URL override for fallow cloud API calls (staging / local-dev).
`FALLOW_API_KEY`	fallow cloud bearer token for coverage upload commands.
`FALLOW_CA_BUNDLE`	Path to a PEM certificate bundle for fallow cloud and provider HTTP calls (replaces the default WebPKI roots; include public roots plus any private CA).

Telemetry

Telemetry is opt-in and off by default. Full reference: fallow telemetry.

Variable	Effect
`FALLOW_TELEMETRY`	`off`, `on`, or `inspect` (print the payload to stderr without sending).
`FALLOW_TELEMETRY_DISABLED`	Admin/fleet kill switch: truthy values hard-disable telemetry.
`FALLOW_TELEMETRY_DEBUG`	Truthy values alias `FALLOW_TELEMETRY=inspect`.
`FALLOW_AGENT_SOURCE`	Normalized agent vendor for telemetry classification (e.g. `claude_code`, `codex`, `cursor`).
`DO_NOT_TRACK`	Honored as a top-precedence telemetry kill switch.

MCP server

Set these in the MCP server’s env block; the spawned CLI inherits them. Full reference: MCP integration.

Variable	Effect
`FALLOW_TIMEOUT_SECS`	Per-tool-call CLI subprocess timeout in seconds (default `120`).
`FALLOW_DIFF_FILE`	Path to a unified diff that scopes all findings by changed line.
`FALLOW_CHANGED_SINCE`	Git ref that scopes file discovery for analysis tools.
`FALLOW_INTEGRATION_SURFACE`	Telemetry surface override for non-CLI surfaces; set by the MCP server on the CLI it spawns.
`FALLOW_MCP_TOOL`	Telemetry per-tool dimension; set by the MCP server alongside `FALLOW_INTEGRATION_SURFACE=mcp`.

The complete machine-readable list ships in the environment_variables block of fallow schema.

MCP server

AI agent integration using the Model Context Protocol.

fallow dead-code

Full CLI reference including all output format options.

Getting Started

Analysis

Configuration

Integrations

Explanations

Frameworks

Migration

Environment variables

FALLOW_FORMAT

FALLOW_QUIET

FALLOW_BIN

FALLOW_EXTENDS_TIMEOUT_SECS

FALLOW_CACHE_DIR

FALLOW_CACHE_MAX_SIZE

FALLOW_AUDIT_BASE

FALLOW_AUDIT_CACHE_MAX_AGE_DAYS

FALLOW_IMPACT_STORE_MAX_AGE_DAYS

FALLOW_UPDATE_CHECK

FALLOW_SUGGESTIONS

FALLOW_PRODUCTION and per-analysis overrides

FALLOW_COVERAGE

FALLOW_COVERAGE_ROOT

FALLOW_MAX_FILE_SIZE

Review and PR-comment formats

License and cloud

Telemetry

MCP server

See also

MCP server

fallow dead-code

​FALLOW_FORMAT

​FALLOW_QUIET

​FALLOW_BIN

​FALLOW_EXTENDS_TIMEOUT_SECS

​FALLOW_CACHE_DIR

​FALLOW_CACHE_MAX_SIZE

​FALLOW_AUDIT_BASE

​FALLOW_AUDIT_CACHE_MAX_AGE_DAYS

​FALLOW_IMPACT_STORE_MAX_AGE_DAYS

​FALLOW_UPDATE_CHECK

​FALLOW_SUGGESTIONS

​FALLOW_PRODUCTION and per-analysis overrides

​FALLOW_COVERAGE

​FALLOW_COVERAGE_ROOT

​FALLOW_MAX_FILE_SIZE

​Review and PR-comment formats

​License and cloud

​Telemetry

​MCP server

​See also

MCP server

fallow dead-code

FALLOW_FORMAT

FALLOW_QUIET

FALLOW_BIN

FALLOW_EXTENDS_TIMEOUT_SECS

FALLOW_CACHE_DIR

FALLOW_CACHE_MAX_SIZE

FALLOW_AUDIT_BASE

FALLOW_AUDIT_CACHE_MAX_AGE_DAYS

FALLOW_IMPACT_STORE_MAX_AGE_DAYS

FALLOW_UPDATE_CHECK

FALLOW_SUGGESTIONS

FALLOW_PRODUCTION and per-analysis overrides

FALLOW_COVERAGE

FALLOW_COVERAGE_ROOT

FALLOW_MAX_FILE_SIZE

Review and PR-comment formats

License and cloud

Telemetry

MCP server

See also