Pi Betterleaks Scanner (pi-betterleaks-scanner) is a Pi extension that runs the Betterleaks secret scanner against live session text. It checks your input before the agent processes it, audits what the agent and its tools produce after every turn, and holds each potential secret for an explicit decision — it never acknowledges a finding on your behalf.

• Scans input first — interactive and RPC user input is scanned before the agent processes it.
• Audits output after each turn — finalized assistant text and tool results are batch-scanned once the turn completes.
• Requires explicit review — findings surface in a compact TUI review panel, with an RPC select fallback, and wait for your decision.
• Persists fingerprints, not secrets — only HMAC fingerprints and safe acknowledgement metadata are written to the active session branch.
• Keeps scanning local — session text is never written to temporary scan files, and Betterleaks live validation is never enabled, so candidate secrets are never tested against real services.

Post-turn review is an audit boundary, not a gate: by the time assistant text or tool results are scanned, they may already have been sent to your model provider or persisted in the session. The extension tells you when a secret got out; it cannot un-send it.

1. Install

Install the npm release with Pi:

pi install npm:@moyai/pi-betterleaks-scanner

Restart Pi after installation, or run /reload in your current Pi session to activate the scanner immediately.

Pi extensions run with your system permissions. Review third-party extension source before installing it.

1.1 First run

The extension needs a compatible Betterleaks executable. If it cannot find one when Pi first starts interactively, it offers to install one — and asks twice before touching the network:

1. Choose a destination: this project only, or globally for all Pi projects.
2. Confirm the details: the pinned version (v1.7.3), the official GitHub release URL, the chosen destination, and the package-owned SHA-256 checksum.

After you approve, the extension downloads the v1.7.3 archive, verifies it against the pinned checksum, extracts only the expected executable, smoke-tests it, and activates it atomically with owner-only permissions. No Pi restart is needed.

If you decline, that choice is remembered for v1.7.3 and nothing is downloaded. Reopen the installer whenever you are ready:

/betterleaks setup

1.2 Use an existing Betterleaks

Existing installations are fully supported. The extension picks an executable in this order:

1. The executablePath value from ~/.pi/agent/betterleaks-scanner/config.json, or the BETTERLEAKS_BIN environment variable
2. The verified project-managed executable under <project>/.pi/betterleaks-scanner
3. The verified global managed executable under the Pi agent directory
4. A betterleaks executable on PATH

2. Using the scanner

Most of the time, Pi's footer status is all you need. The extension renders these compact TUI elements:

| Footer element | Meaning | | --- | --- | | ◌ leaks: clean | The last scan found no potential secrets | | ⠋ leaks: scanning | A scan is in progress; the Braille glyph animates while Betterleaks runs | | +N leaks: N pending | Findings are waiting for your review; the +N prefix is highlighted | | ! leaks: unavailable | No compatible Betterleaks executable was found; the ! is shown as a warning | | ○ leaks: off | Scanning is disabled |

When a finding needs attention, Pi opens a compact review panel with a masked preview and explicit actions. It never displays the full detected secret or silently acknowledges the finding.

Two commands are available:

/betterleaks status
/betterleaks setup

/betterleaks status reports the scanner's current state. /betterleaks setup opens the Betterleaks installer.

3. Configuration

Configuration is optional. Global settings live in ~/.pi/agent/betterleaks-scanner/config.json:

{
  "enabled": true,
  "executablePath": "/absolute/path/to/betterleaks",
  "maximumInputBytes": 262144,
  "maximumOutputBytes": 1048576,
  "maximumFindings": 100,
  "timeoutMs": 5000
}

What the settings control:

| Setting | Description | | --- | --- | | enabled | Turns scanning on or off | | executablePath | Absolute path to a Betterleaks executable; overrides managed installations | | maximumInputBytes | Upper bound on scanned input, in bytes | | maximumOutputBytes | Upper bound on scanned output, in bytes | | maximumFindings | Upper bound on reported findings | | timeoutMs | Time limit for a Betterleaks run, in milliseconds |

Project-level .betterleaks.toml files and project rules are never loaded implicitly, so a repository you clone cannot silently change how it is scanned.

4. Supply-chain safeguards

A secret scanner has to be trustworthy before it is useful, so the download path is deliberately strict:

• Pinned, verified digests — the pinned SHA-256 digests come from the official Betterleaks v1.7.3 checksums.txt. On August 6, 2026, we verified them against the release's Sigstore bundle and the expected Betterleaks GitHub Actions release-workflow identity.
• No postinstall download — Pi can install packages non-interactively, so the extension never downloads anything during pi install. Consent is always requested through Pi's UI at first interactive startup.
• Nothing sneaks into your repo — a project-managed installation writes a nested .gitignore, so the downloaded executable cannot be committed by accident.

5. Contributing

Pi Betterleaks Scanner is open source under the MIT license. Bug reports, feature ideas, and pull requests are all welcome.

To work on the extension locally:

npm install
npm run check

npm run check runs formatting checks, linting, the TypeScript compiler, Vitest with coverage, Fallow's type-aware analysis, and the architecture boundary checks.

This extension is powered by Betterleaks. If you want to improve secret detection rules, scanner behavior, performance, or platform support, please consider contributing those improvements directly to the Betterleaks project as well.