Pi Fallow

Pi Fallow connects Fallow to the Pi coding agent. It adds:

• 🧰 fallow_run — a compact tool for agent workflows
• ⌨️ /fallow — a slash command for interactive analysis
• 🧭 a TUI navigator for reviewing, filtering, tracing, and selecting findings

Use it to verify changes, review a PR, find dead code or duplication, inspect maintainability, surface security candidates, and trace whether code is safe to remove.

📦 Install

pi install npm:pi-fallow

Other supported sources:

pi install git:github.com/revazi/pi-fallow
pi install .       # local checkout
pi install -l .    # project-local checkout
pi -e .            # try without installing

🚀 Quick start

Run the issue-focused default:

/fallow

This combines dead-code, duplication, health, and security analysis into one actionable report. Informational file scores, hotspots, and advisory refactoring targets remain available through explicit health commands but do not inflate the default issue count.

| Command | What it does | |---|---| | /fallow | Issue-focused default report | | /fallow issues | Same aggregate, explicit | | /fallow pr | Audit against the detected base, new-only gate | | /fallow health --file-scores --targets --score | Maintainability context | | /fallow dead-code --changed-since main | Unused code on a branch | | /fallow dupes --changed-since main | Duplication on a branch | | /fallow security --changed-since main --gate new | Security candidates on a branch | | /fallow audit --base origin/main --gate new-only | Full change audit | | /fallow inspect --file extensions/fallow/cli.ts | Inspect one file | | /fallow trace extensions/fallow/cli.ts:fallowCli | Trace a symbol | | /fallow architecture extensions/fallow/cli.ts extensions/fallow/registry.ts | Architecture lookup | | /fallow decision-surface --changed-since main | Structural decisions in a change | | /fallow history | Reopen or compare session reports | | /fallow compatibility | Compare installed Fallow with the certified surface | | /fallow config-assist | Read-only config inspection | | /fallow similar-code status | Local similar-code readiness |

/fallow pr is shorthand for an audit against the detected base with a new-only gate. /fallow rerun repeats the last analysis. /fallow architecture <file>... maps to Fallow's read-only guard command.

Set a shell-free custom default with PI_FALLOW_DEFAULT_COMMAND:

export PI_FALLOW_DEFAULT_COMMAND='health --complexity --targets --score'

Explicit subcommands are never replaced. Recursive and extension-only commands cannot be configured as the default.

🤖 Agent tool

fallow_run accepts a command, separate CLI-token arguments, an optional root and timeout, and an output detail level:

{
  "command": "audit",
  "args": ["--base", "main", "--gate", "new-only"],
  "detail": "findings"
}

| Detail | What the model sees | |---|---| | summary | Status and counts | | findings | Bounded normalized findings with locations and actions (default) | | raw | Bounded raw Fallow output for diagnostics |

Bounded responses link to a complete report whenever data is omitted. Before deletion, inspect or trace the target; treat incomplete type-aware evidence as advisory; and preview fixes before applying them.

🧭 Interactive navigator

The TUI keeps every actionable finding navigable while defaulting to a compact model prompt.

| Key | Action | |---|---| | ↑/↓, j/k | Move | | Enter/Space | Expand finding | | / | Search | | f / v | Cycle section/severity filters | | s / A | Select one/all visible findings | | p | Open read-only action palette | | t | Run the first valid trace action | | e or a | Load selected findings into the editor | | y | Copy selected findings | | d | Toggle full raw detail | | i | Toggle informational health context | | q / Esc | Close or dismiss the current control |

The action palette supports safe inspection, explanation, tracing, symbol impact, and architecture lookup. Fixes are limited to explicit project-wide dry-run previews; the navigator never applies them.

🧩 Similar Code

Similar Code is explicit, local-model, and advisory. It never runs as part of the default report, audits, security analysis, or automatic fixes.

Open the persistent overlay with 2 or o. From its Similar Code view:

• r refreshes readiness
• s, t, and l edit scope, threshold, and result limit
• c opts into reuse of project-local embeddings (off by default)
• v validates without running
• Enter validates and requests a run when not editing
• uppercase S opens the setup preview, and only y confirms installation

Setup and analysis stay in the overlay, support cancellation, retain their latest result, and never run automatically. Cold inference may require the download size reported by similar-code status and can take minutes. Complete reports remain separate files for reproducible inspect/review steps.

Open Runtime Coverage with 3. Its only runnable mode is one explicit local coverage analyze --runtime-coverage <path> request against the local V8/Istanbul file or directory you select and preview. Run remains disabled until readiness is verified and that explicit artifact preview is valid; execution then freshly rechecks the mode, project, artifact identity/metadata, arguments, and signed sidecar binding. Directory contents are not crawled to guess capture cardinality.

Continuous monitoring, cloud analysis/upload, and multi-capture analysis are shown as distinct licensed workflows that are unavailable in this overlay. They have no selectable request variant, flags, upload path, or capture initiation. The available local run disables analysis caching, removes cloud credential/source variables from the child, and does not claim production coverage. Setup and analysis remain explicit TUI-only actions; RPC, print, JSON, and fallow_run cannot install the sidecar or initiate capture.

🕘 History

Pi Fallow keeps up to 20 completed slash-command reports in branch-aware, project-isolated session metadata:

/fallow history
/fallow history open r1
/fallow history compare r1 r2
/fallow history clear

Reports must still exist and match their recorded digest. Comparisons require compatible, complete scopes and never guess when identity evidence is missing. History is session-local and Pi Fallow never deletes saved reports automatically.

⚙️ Configuration and compatibility

/fallow config-assist performs a bounded read-only inspection of the discovered Fallow configuration. It can preview one schema-recognized rule severity without exposing resolved values or secrets.

Applying a preview is TUI-only. Apply requires a direct confirmation; repeated discovery, schema, and content checks ensure concurrent drift or cancellation refuses the write. Existing files receive byte-exact backups and atomic replacements; inherited or external configuration remains read-only.

/fallow compatibility compares the installed Fallow capability schema with the certified surface. It reports additive and incompatible capabilities, never installs software or runs during startup, and never gates ordinary execution.

🛡️ Run modes and safety

• TUI mode uses loaders and the interactive navigator.
• RPC, print, and JSON modes execute directly and retain complete transcript output without terminal UI.
• Arguments are passed as arrays without a shell.
• Cancellation terminates process trees and escalates when necessary.
• Large model-facing results are bounded and preserve complete-output references.
• Pi host packages remain external and are never bundled.
• Optional model setup requires an explicit TUI preview and confirmation.

✅ Tested compatibility

| Pi coding agent | Matching Pi AI/TUI packages | TypeBox | Node.js | Fallow | |---|---|---|---|---| | 1.4.0 | 1.4.0 | 1.4.3 | 22.19 and 24 | 3.36.0 |

Certification means this exact matrix passed frozen and live repository checks. Compatibility means the installed Fallow still advertises the capabilities Pi Fallow models. Installation constraints are only the requirements below. This is tested compatibility; it is not an installation constraint, and other versions may work.

Pi libraries and TypeBox are host-provided wildcard peer dependencies, following Pi package guidance; the tested matrix does not narrow those peer ranges.

📋 Requirements

• Node.js 22.19+
• Pi coding agent
• Fallow available through FALLOW_BIN, PATH, a package-local installation, or the npx -y fallow fallback

Fallow 3.36.0 is the current certification target. Runner discovery is cached per project/session and refreshed when relevant environment values change.

📊 Benchmarks

Pi Fallow is measured in three places: model-visible tokens, interactive latency, and /fallow issues on pinned popular JS/TS packages. These are host-specific snapshots, not provider billing or a quality ranking of the analyzed projects.

🧠 Model-visible tokens

Bounded fallow_run output keeps complete findings on disk and sends the model a compact, actionable slice.

| Surface (o200k_base) | Before output-detail | Current | |---|---:|---:| | Active fallow_run contract | 2,237 | 421 | | All tool results | 45,104 | 7,590 (83.17% smaller) |

Slash-command transcripts are unchanged by detail. Omitted inline findings are counted, and bounded results keep a complete-output reference. These are deterministic corpus measurements; see benchmarks/README.md.

⚡ Interactive analysis

/fallow issues runs combined code-quality and security analyses concurrently, capped at two child processes.

| Generated project | Sequential | Concurrent | Faster | Peak descendant RSS | |---|---:|---:|---:|---:| | 10 files | 287.65 ms | 183.94 ms | 36.05% | 115.78 → 215.47 MB | | 500 files | 333.84 ms | 238.24 ms | 28.64% | 123.55 → 212.97 MB |

Navigator preparation stays below 0.2 ms. Direct Fallow invocation is much cheaper than npx fallback on the same machine. Methodology and the Apple M1 Pro baseline live in benchmarks/PERFORMANCE.md.

📦 Popular packages

The table below is /fallow issues on shallow clones of widely used JS/TS projects, using default Fallow discovery and Pi Fallow's production aggregator.

Health is Fallow's overall project score (0–100 and letter grade). MI is average maintainability. Default discovery includes tests, examples, docs, and generated fixtures, so unused-file and duplication penalties can pull the composite score down even when maintainability stays high. This is a snapshot, not a ranking of these projects.

Measured on Apple M1 Pro, Node.js 24.12.0, Fallow 3.24.1:

HTTP frameworks

| Package | Pin | Files | Health | MI | Time | Findings | |---|---|---:|---:|---:|---:|---:| | express | v5.2.1 | 154 | B 72.9 | 90.2 | 0.35s | 358 | | fastify | v5.9.0 | 296 | F 16.6 | 74.7 | 0.36s | 514 | | koa | v3.2.1 | 82 | C 65.7 | 74.8 | 0.26s | 112 | | hono | v4.13.8 | 391 | C 68.1 | 90.6 | 0.53s | 218 |

UI frameworks

| Package | Pin | Files | Health | MI | Time | Findings | |---|---|---:|---:|---:|---:|---:| | preact | 10.29.8 | 255 | D 51.3 | 89.9 | 0.47s | 126 | | vue | v3.5.43 | 565 | D 48.4 | 89.8 | 0.62s | 569 | | svelte | [email protected] | 8,493 | C 65.6 | 86.8 | 1.66s | 5,961 |

Svelte is measured as the published monorepo tag, not a single package path.

Libraries

| Package | Pin | Files | Health | MI | Time | Findings | |---|---|---:|---:|---:|---:|---:| | axios | v1.20.0 | 252 | B 72 | 89.6 | 0.41s | 176 | | zod | v4.6.5 | 549 | D 45.2 | 86.9 | 0.63s | 863 | | commander | v15.0.0 | 171 | B 71.8 | 74.4 | 0.31s | 208 | | zustand | v5.0.15 | 56 | C 59.8 | 92.0 | 0.57s | 21 | | redux | v5.0.1 | 225 | D 52.6 | 90.7 | 0.45s | 118 | | date-fns | v4.4.0 | 1,632 | B 70.3 | 91.9 | 1.38s | 909 | | debug | 4.4.3 | 7 | C 65 | 94.1 | 0.25s | 14 | | chalk | v6.0.0 | 20 | C 64 | 88.9 | 0.70s | 9 | | lodash | 4.18.1 | 59 | D 51 | 83.1 | 0.51s | 767 |

Reproduce or refresh the snapshot:

npm run bench:packages -- \
  --label candidate \
  --output /tmp/pi-fallow-popular-packages.json

Pinned refs live in benchmarks/popular-packages.json. The checked-in result is benchmarks/baselines/popular-packages-v0.6.2.json. Wall times are one-shot and machine-sensitive; file counts and finding totals are from the pinned checkouts.

🧩 More Pi packages by Revaz

| Package | Purpose | | --- | --- | | pi-jscpd | Quiet, read-only duplication guardrail for Pi | | pi-reads | Source capture, cited reading, Obsidian, EPUB, PDF, and Kindle workflows | | pi-career | Deterministic resume and career workflows | | pi-tmux-orchestrator | Multi-agent coordination in tmux | | @tasklight/pi-tasklight | Tasklight notifications for Pi |

🛠️ Development

npm test
npm run coverage
npm run check:bundle
npm run health
npm run dupes
npm run dead-code
npm run audit:all
npm run package:smoke
npm run bench:tokens -- --label candidate --output /tmp/pi-fallow-tokens.json
npm run bench:performance -- --label candidate --output /tmp/pi-fallow-performance.json
npm run bench:issues -- --label candidate --output /tmp/pi-fallow-project-issues.json
npm run bench:packages -- --label candidate --output /tmp/pi-fallow-popular-packages.json

See CONTRIBUTING.md, ROADMAP.md, benchmark documentation, and performance methodology.

The package manifest exposes ./extensions/index.ts. Pi libraries and TypeBox are external wildcard peers, not bundled dependencies.

📄 License

MIT © Revaz Zakalashvili