analyze | Full dead code analysis (fallow dead-code --format json). Detects unused files, exports, types, dependencies, enum/class members, unresolved imports, unlisted dependencies, duplicate exports, circular dependencies, re-export cycles (barrel files that form a structural loop, silently breaking re-exports), boundary violations, framework component findings (unused props, emits, inputs, outputs, Svelte events, unrendered components, and unprovided injects), rule-pack policy violations (banned calls and banned imports declared via the rulePacks config key), stale suppressions, unused pnpm catalog entries, empty pnpm catalog groups, and unresolved pnpm catalog references (consumer package.json references a catalog that does not declare the package; pnpm install would fail). Private type leaks are opt-in via issue_types: ["private-type-leaks"]. |
check_changed | Incremental analysis of changed files (fallow dead-code --changed-since) |
security_candidates | Unverified local security candidates, not confirmed vulnerabilities (fallow security --format json). Read security_findings[] for category, CWE, severity, evidence, trace, optional reachability, blind-spot counters, and optional unresolved_callee_diagnostics samples for dynamic callee follow-up. severity is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable candidate (source_kind/sink/boundary), where URL-category sinks may include url_shape (fixed-origin-dynamic-path or dynamic-origin), an optional taint_flow source-to-sink triple, and a stable finding_id (equal to the SARIF fingerprint) for cross-run correlation; there is no impact field (deciding exploitability is the agent’s job). Set surface: true to include top-level attack_surface[] entries with defensive-boundary prompts for a verifier. Set gate to new for changed-line candidates or newly-reachable for candidates that became reachable from entry points; newly-reachable requires changed_since. reachability.untrusted_source_trace is module-level import context only and does not prove value flow; reachability.taint_confidence tiers each reachable candidate as arg-level (sink argument traces to a same-module source read, strong) or module-level (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports root, config, workspace, paths, changed_since, changed_workspaces, surface, gate, no_cache, and threads; paths forwards repeated fallow security --file filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See Security agent verification for the verifier packet and verdict recipe. Inherits FALLOW_DIFF_FILE from the server environment for line-level diff scoping; raise FALLOW_TIMEOUT_SECS for large repos. |
inspect_target | Compose one evidence bundle for a file or exported symbol. File targets use target: { type: "file", file }; symbol targets use target: { type: "symbol", file, export_name }. Returns kind: "inspect_target", normalized target identity, trace_file, optional trace_export, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Evidence sections carry status and scope; symbol targets warn when supporting evidence is file-scoped. Set the opt-in symbol_chain: true option to also attach the best-effort symbol-level call chain (the same data as fallow trace) as a symbol_chain evidence section; only meaningful for a symbol target, default off (best-effort, syntactic, off the ranked path). Supports root, config, production, workspace, no_cache, and threads; production applies to trace, dead-code, and health evidence only. Raise FALLOW_TIMEOUT_SECS for large repos. |
code_execute | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives { fallow, root }, returns JSON-serializable data, and can call read-only helpers such as fallow.projectInfo, fallow.audit, fallow.checkHealth, and fallow.run(tool, params) for the same allowlist. Mutating fix tools are not exposed. The sandbox has no filesystem, network, imports, eval, Function, process, require, Deno, Bun, or shell access. Params: code, optional root, timeout_ms (capped at 30000), and max_output_bytes (capped at 4000000). |
find_dupes | Code duplication detection (fallow dupes --format json). Each clone_groups[] entry (plus nested clone_families[].groups[] and the per-bucket --group-by output) carries a stable fingerprint, usually dup:<8hex> and widened only on rare report collisions; pass it to trace_clone to deep-dive that group. Import declarations are excluded from clone detection by default; pass ignore_imports: false to count them again. |
fix_preview | Dry-run auto-fix preview (fallow fix --dry-run --format json) |
fix_apply | Apply auto-fixes (fallow fix --yes --format json) |
check_health | Complexity metrics, file health scores, hotspots, and refactoring targets (fallow health --format json). Set file_scores: true for maintainability index, hotspots: true for churn analysis, targets: true for ranked recommendations sorted by efficiency, trend: true for per-metric deltas against the most recent snapshot. Set complexity_breakdown: true to add a per-decision-point contributions[] array to each complexity finding (each else-if, nested if, boolean operator, loop, case, etc. with its source line and cyclomatic/cognitive weight) so you can explain WHY a function scored high and pinpoint which lines to refactor. Set css: true to add a css_analytics section: structural CSS slop that per-rule linters do not aggregate (specificity hotspots, !important density, deep nesting, design-token sprawl) plus cleanup candidates (unreferenced custom properties / @keyframes, dead Vue <style scoped> classes, unused @property / @layer, Tailwind arbitrary-value bypasses, Tailwind v4 @theme unused_theme_tokens, duplicate declaration blocks) and undefined-reference candidates, each with a read-only verification step in its actions[]. It also adds token_consumers, a reverse index of where each design token is consumed (per token a consumer_count plus a located consumers[] sample) so an agent can read a token’s blast radius before changing it; it covers Tailwind v4 @theme tokens (kind theme-var / css-var / utility / apply) and CSS-in-JS token definitions: StyleX defineVars, vanilla-extract createTheme-family definitions, and PandaCSS defineTokens (token is binding-qualified; kind is js-member for member access and js-call for Panda token(...) calls). consumer_count is a static lower bound (a computed class name like bg-${c}, dynamic import strings, unresolved aliases, generated package state, or computed token access can still be invisible) and the field is descriptive context, not a finding (no actions[]). Opt-in because it reads project stylesheets and cross-checks source files. Standard CSS and Vue/Svelte/Astro standard <style> blocks are parsed structurally; Sass/Less sources are scanned only where fallow can stay conservative without expanding preprocessor semantics. Set churn_file to a fallow-churn/v1 JSON path to drive hotspots/ownership/targets from imported VCS history instead of git, for projects with no git repository (Yandex Arc, Mercurial, Perforce); the file is authoritative for the window, so since then only labels output. Set runtime_coverage to merge a V8 or Istanbul coverage dump; tune it with min_invocations_hot (default 100), min_observation_volume (default 5000), and low_traffic_threshold (default 0.001). Set group_by to owner, directory, package, or section to partition results: each group gets its own vital_signs, health_score, and optional coverage_source_consistency recomputed from the group’s files (top-level metrics stay project-wide), SARIF results gain properties.group, CodeClimate issues gain a top-level group field. Findings include a bucketed coverage_tier (none/partial/high) and coverage_source for CRAP-triggered entries; summary.coverage_source_consistency reports whether those sources are uniform or mixed. Actions pick add-tests / increase-coverage when coverage can still clear CRAP, or refactor-function when cyclomatic >= maxCrap, see “Structured actions” below. |
check_runtime_coverage | Merge runtime-coverage data into the health report. Required coverage param accepts a V8 coverage directory, a single V8 coverage JSON, or an Istanbul coverage-final.json. A single local capture is free and runs without a license; continuous or multi-capture runtime monitoring (a V8 directory containing multiple JSON files) requires an active license JWT. Tunable via min_invocations_hot (default 100), min_observation_volume (default 5000), low_traffic_threshold (default 0.001), max_crap (default 30.0), top, and group_by. Protocol-0.3+ sidecars emit a summary.capture_quality block flagging short-window captures. Cloud runtime rows can expose resolutionStatus / mappingQuality on function-list JSON and resolution_status / mapping_quality in runtime-context JSON. Use the confidence table below before acting on file-level runtime signals. Can exceed the default 120s timeout on large dumps; raise FALLOW_TIMEOUT_SECS accordingly. Pick this over check_health when you have a coverage dump. |
get_hot_paths | Runtime-context slice over the same local runtime coverage pipeline. Same input schema and free-vs-paid contract as check_runtime_coverage; read runtime_coverage.hot_paths for production hot paths sorted by percentile and invocation count. |
get_blast_radius | Runtime-context slice for blast-radius review. Same input schema and free-vs-paid contract as check_runtime_coverage; read runtime_coverage.blast_radius for stable fallow:blast:<hash> IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands. |
get_importance | Runtime-context slice for production-importance review. Same input schema and free-vs-paid contract as check_runtime_coverage; read runtime_coverage.importance for stable fallow:importance:<hash> IDs, invocations, cyclomatic complexity, owner count, 0-100 score, and templated reason. |
get_cleanup_candidates | Runtime-context slice for cleanup review. Same input schema and free-vs-paid contract as check_runtime_coverage; read runtime_coverage.findings for safe_to_delete, review_required, low_traffic, and coverage_unavailable verdicts. |
get_token_blast_radius | Design-token blast radius from static analysis (free, no runtime dump). Runs fallow health --css --format json; read css_analytics.token_consumers for, per token, its defining site plus a consumer_count and a capped located consumers[] sample of {path,line,kind}. Covers Tailwind v4 @theme tokens (token is the ---prefixed custom property; kind theme-var / css-var / utility / apply) plus CSS-in-JS token definitions: StyleX defineVars, vanilla-extract createTheme / createThemeContract / createGlobalTheme, and PandaCSS defineTokens. StyleX and vanilla-extract consumers use binding-qualified dotted paths like vars.color.primary with kind js-member; PandaCSS consumers use token paths like tokens.colors.brand with kind js-call. A focused entry point so you do not need css=true on check_health. consumer_count is a static lower bound (a computed class name like bg-${c}, dynamic import strings, unresolved aliases, generated package state, or computed token access can still be invisible), so use it to size the impact of editing or renaming a token, not to decide deletion; the Tailwind dead-token verdict stays on unused_theme_tokens, and CSS-in-JS tokens have no dead-token finding (so a CSS-in-JS consumer_count of 0 is weaker). |
audit | Audit changed files for dead code, complexity, duplication, and styling (fallow audit --format json). Returns a verdict (pass/warn/fail). Set base to specify the comparison ref, gate to new-only or all, and include_entry_exports=true to also catch typos in entry-file exports (meatdata vs metadata). Set coverage to an Istanbul coverage-final.json path (and absolute coverage_root when paths need rebasing for CI / Docker checkouts) for accurate per-function CRAP scoring in the health sub-analysis. Styling analytics are included by default in audit, including styling_findings and css_analytics when the project has CSS or CSS-in-JS evidence. Set css_deep=false to skip project-wide styling reachability, or css_deep=true to force it back on when config disables it. Set runtime_coverage (V8 dir / V8 JSON / Istanbul JSON) to fold runtime-coverage findings into the same audit invocation; tune with min_invocations_hot (default 100). When FALLOW_DIFF_FILE or FALLOW_CHANGED_SINCE is set in the agent’s env, runtime_coverage.verdict promotes hot-path-touched over cold-code-detected for PR-review contexts. |
decision_surface | Surface the few consequential structural decisions a change embeds (coupling, public API, dependency), each as a judgment question with the routed expert; ranked, capped, and signal_id-anchored. Reads the same graph-derived review brief as fallow review (the brief path of fallow audit). Returns the decision surface with exactly three shippable categories: coupling-boundary (a new cross-zone dependency edge), public-api-contract (a new exported public-API surface, or a changed contract consumed by modules outside this diff), and dependency (a new third-party dependency). Each decision is anchored to a signal_id fallow deterministically derived from the graph, ranked by consequence (blast radius x reversibility), paired with the routed expert (who to ask), and may carry previous_signal_id (the id the anchor had before a git mv, so a review surface can re-attach a prior comment across a rename). Each decision also carries a tradeoff clause (the named structural sacrifice stated as a fact, e.g. “Couples app to infra; N in-repo modules already depend on this anchor”) and internal_consumer_count (the honest per-anchor count of in-repo modules outside the diff that already depend on it, the display number you read reversibility from, distinct from the ranking-only blast). Set base to specify the comparison ref and max_decisions to cap the surfaced decisions (default 4, clamped to a 3 to 5 band). The brief always exits 0; the verdict is carried informationally and never gates. |
fallow_explain | Explain one issue type without running analysis (fallow explain <issue-type> --format json). Returns rationale, example, fix guidance, and docs URL. |
project_info | Project metadata, including plugins, files, and entry points (fallow list --format json). Set entry_points, files, plugins, or boundaries to true to request specific sections. |
recommend | Recommend a project-tailored fallow config for cold-start onboarding (fallow recommend --format json). Read-only: from framework / workspace / tooling detection it returns a loader-validated proposed_config you can write as-is, plus a decisions[] list that classifies each setting as auto (decided from detection, applied silently), default (a disclosed, overridable default with a rationale), or taste (a genuinely subjective choice surfaced as an AskUserQuestion-shaped prompt with no baked-in answer). Detected TypeScript projects receive an informational typeAware.enabled decision with the opt-in command, cost boundary, and guide link; it is never written into proposed_config. root-only; writing no config at all is a valid outcome. |
feature_flags | Detect feature flag patterns in the codebase (fallow flags --format json). Identifies environment variable flags, SDK calls from common providers, and config object patterns. Set top to limit results. |
list_suppressions | List active fallow-ignore suppression markers grouped per file with line, kind, level, reason, and a stale cross-reference (fallow suppressions --format json). A read-only governance inventory for seeing what a clean verdict is hiding, not a gate: always exits 0 even when suppressions exist. Scope with workspace, changed_since (the natural pull-request review scope), or repeated file entries. Runs a full analysis, so raise FALLOW_TIMEOUT_SECS on large repos. |
list_boundaries | Architecture boundary zones and access rules (fallow list --boundaries --format json). Returns zone definitions, access rules, per-zone file counts, and logical_groups[] (pre-expansion autoDiscover parents with verbatim paths, discovered children, a status enum (ok / empty / invalid_path), summed file_count, optional authored_rule, optional fallback_zone cross-reference for the Bulletproof case, optional merged_from for duplicate parent declarations, optional original_zone_root echo for monorepo subtree scopes, and optional child_source_indices attribution for multi-path autoDiscover). Returns {"configured": false} if no boundaries are configured. |
trace_export | Trace why an export is used or unused (fallow dead-code --trace FILE:EXPORT_NAME --format json). Required file and export_name params. Returns file reachability, entry-point status, direct references, re-export chains, and a reason string. If export_name is a class / enum / store MEMBER rather than a top-level export, returns a member trace instead (member_name, member_kind, owner_export, owner_is_used) reporting the owning declaration’s reachability and usage plus a pointer to the matching --unused-<kind>-members command; branch on field presence (export_name vs member_name). Use before deleting a supposedly-unused export or debugging an unused-class-member finding. |
symbol_trace | Trace exact TypeScript symbol references, namespaces, aliases, and re-export hops (fallow dead-code --type-aware --trace FILE:EXPORT --format json --quiet). Required file and export_name; optional type_aware_projects and type_aware_require (best-effort or complete). This adds semantic proof to Fallow’s project-wide usage evidence without returning TypeScript compiler diagnostics or lint findings. |
symbol_impact | Return exact-symbol consumers, transitive affected files, and targeted tests for a TypeScript export (fallow dead-code --type-aware --symbol-impact FILE:EXPORT --format json --quiet). Required file and export_name; optional type_aware_projects and type_aware_require (best-effort or complete). Use it to plan a rename, deletion, or API change. It is advisory change-impact evidence, not a substitute for tsc or Oxlint. |
trace_file | Trace all graph edges for a file (fallow dead-code --trace-file PATH --format json). Required file param. Returns reachability, entry-point status, 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 param. Returns importing files, type-only importers, total import count, used_in_scripts (true when invoked from package.json scripts or CI configs like .github/workflows/*.yml / .gitlab-ci.yml), and is_used (combined import + script signal, mirrors the unused-deps detector so build tools like microbundle or vitest invoked only via scripts are correctly classified as used). Use before removing a dependency or moving it between dependencies and devDependencies. |
trace_clone | Deep-dive a duplicate-code clone group (fallow dupes --trace <spec> --format json). Address it by exactly one of: file + line (a source location), or fingerprint (a dup:<id> from a prior find_dupes clone_groups[].fingerprint, usually dup:<8hex> and widened only on rare report collisions). Returns the matched clone instance plus every clone group containing it; each traced group carries its fingerprint, a group-level extract-function suggestion with estimated savings, and a best-effort suggested_name (omitted when no confident name; advisory). Supports mode, min_tokens, min_lines, threshold, skip_local, cross_language, and ignore_imports (module wiring is excluded by default; pass ignore_imports: false to count it). Use to consolidate duplication when you need exact sibling locations and a refactor target; the fingerprint form lets an agent deep-dive a find_dupes result directly. |
impact | Read the local, opt-in Fallow Impact value report (fallow impact --format json). Runs no analysis: reports current surfacing counts, the trend since the last recorded run, pre-commit gate containment, and (on impact v1.5+) resolved/suppressed attribution. History is read from a per-project file in the user’s private config dir (never inside the repo). Read-only and root-only (no config / no_cache / threads); the mutating enable / disable / default lifecycle is not exposed. The report carries enabled_source (project / user / default); on a project where tracking was never enabled it returns a populated {"enabled": false, ...} report (never {}), so an agent branches on enabled and enabled_source then record_count, recommending fallow impact enable only when explicit_decision is false (never asked), and staying silent when true (deliberately disabled here). Local-developer signal: fallow never records in CI, so there it returns an empty report and is not a CI metric. |
impact_closure | Trace the impact closure for one file (fallow dead-code --impact-closure <path> --format json). Returns the transitive affected-but-not-in-diff set plus coordination gaps for consumers of the file contract. Supports path, root, config, production, workspace, no_cache, and threads; use it as review-planning evidence, not proof that affected files are wrong. |
impact_all | Roll every tracked project on this machine into one cross-repo value report (fallow impact --all --format json). Runs no analysis: reads the per-project histories in the user config dir and returns kind: "impact-cross-repo" with project_count, tracked_count, unreadable_count, a totals roll-up summed over all tracked projects (including repos since deleted from disk), and a projects[] array. Each row carries a hashed project_key (never a filesystem path; always present), an optional human label (the repo’s folder basename; omitted on rows from older stores, so fall back to project_key), last_recorded, and the same per-project report shape as impact. Use this for a portfolio view; use impact (with root) for one project. sort orders rows (recent default / resolved / contained / name); limit caps rows while totals still cover every project. Projects enabled but with no recorded history are counted but not listed. Read-only; the mutating enable / disable / default / reset lifecycle is not exposed. Local-developer signal: empty in CI, not a CI metric. |
