# pi-lens Usage Guide

This page holds the detailed usage/reference material that does not need to live
in the repository front page.

## Lifecycle overview

pi-lens hooks into the pi agent lifecycle:

- **`session_start`** resets runtime state, hydrates project caches, preinstalls
  likely tools, warms LSPs, and starts background project scans.
- **`tool_call`** records read coverage and prepares read-guard/autopatch state
  before a write/edit lands.
- **`tool_result`** records file mutations, runs format/autofix/LSP/runners, and
  stores diagnostics on the runtime coordinator.
- **`turn_end`** merges blockers/advisories, refreshes project-diagnostic caches,
  runs selected project-level checks, and injects findings for the next turn.

## On-write pipeline

For each write/edit, pi-lens runs a language-aware pipeline. Format and safe
autofix (steps 1–2) run on different schedules depending on the tool:

- **`write`** (new file, full overwrite, bash-authored write): autofix runs
  immediately, in the same tool result, carrying the fixed file's full content
  back to the agent when it fits under the per-file cap.
- **`edit`**: autofix defers to `agent_end`, joining the same per-file queue as
  deferred formatting; autofix drains before format so the final state is
  formatter-stable. A `write` followed by an `edit` on the same file in the
  same turn demotes the write's autofix to deferred too.

1. Format queue / immediate formatting when configured (deferred to
   `agent_end` for an `edit` even under `--immediate-format`, so it lands
   after autofix reformats the file).
2. Safe autofix from tools with deterministic fix support — immediate for
   `write`, deferred to `agent_end` for `edit` (see above).
3. LSP file sync and diagnostic wait.
4. Parallel dispatch runners: LSP, ast-grep, tree-sitter, fact rules, and
   language-specific linters/security scanners. For a deferred `edit`, these
   run against the not-yet-autofixed disk state, so a lint finding autofix
   would have cleared may appear here and resolve itself at `agent_end`.
5. Cascade diagnostics for likely affected neighbors.
6. Deduplication and routing to blockers, actionable warnings, or code-quality
   history.

See [`docs/agent-guide.md`](agent-guide.md#6-auto-format--auto-fix-timing--dont-be-surprised)
for the consumer-facing version of this routing.

## Agent tools

pi-lens exposes these high-value tools to agents:

- `lens_diagnostics` — `source=session` (default) reports cached findings; an
  empty cache is not proof of a clean file. If changed files have no cached
  diagnostics or stale findings, use `source=lsp scope=paths` for targeted
  active verification (or `scope=workspace` to sweep a whole directory/project).
- `lsp_navigation` — IDE-style code navigation (definition/references/etc.).
- `ast_grep_search` / `ast_grep_replace` — AST-aware structural search/replace.
- `module_report` / `read_symbol` — navigable outline and targeted symbol-body
  reads; prefer these before broad full-file reads.

## Project config

Project-level `.pi-lens.json` can configure mutation policy, ignore patterns,
and selected rule thresholds. Global config lives under
`~/.pi-lens/config.json`.

Typical project config:

```jsonc
{
  "format": { "enabled": false },
  "autofix": { "enabled": false },
  "actionableWarnings": {
    "autoFix": { "enabled": false }
  },
  "ignore": ["generated/**", "fixtures/**"],
  "rules": {
    "high-complexity": { "threshold": 20 },
    "high-fan-out": { "threshold": 25 }
  },
  "trivy": {
    "enabled": true,
    "minSeverity": "HIGH"
  }
}
```

The three mutation controls disable auto-formatting, deterministic pipeline
autofix, and actionable-warning quickfixes respectively. Diagnostics continue
to run. See [Global and Project Config](globalconfig.md#project-config) for
precedence and the complete project schema.

## Runtime flags

```bash
# Standard mode (LSP enabled by default)
pi

# Optional switches
pi --no-lens             # Start pi-lens disabled for this session; /lens-toggle can re-enable
pi --no-lens-context     # Disable automatic context injection only (tools/LSP/read-guard/format stay on); /lens-context-toggle
pi --no-lsp              # Disable unified LSP diagnostics
pi --no-autoformat       # Skip auto-formatting entirely
pi --immediate-format    # Format immediately after each edit instead of deferring to agent_end
pi --no-autofix          # Skip auto-fix (Biome, Ruff, ESLint, stylelint, sqlfluff, RuboCop)
pi --no-tests            # Skip test runner
pi --no-delta            # Disable delta mode (show all diagnostics, not just new ones)
pi --lens-guard          # Block git commit/push when unresolved blockers exist (experimental)
pi --lens-checkout-guard # Decline git commands that rewrite the working tree while another live pi-lens session shares this dirty checkout (experimental)
pi --no-opengrep         # Disable the Opengrep security scanner (default-on auxiliary LSP)
pi --no-ast-grep         # Disable the ast-grep auxiliary LSP server (default-on)
pi --no-zizmor           # Disable the zizmor auxiliary LSP server (default-on)
pi --no-typos            # Disable the typos auxiliary LSP server (default-on)
pi --lens-spotbugs       # Run SpotBugs on Java and Kotlin files (opt-in; needs a Java build descriptor and compiled classes)
pi --no-read-guard       # Disable the read-before-edit behavior monitor
pi --no-read-expansion   # Keep exact read ranges without disabling the read guard
pi --lens-retain-injections # Re-send injected findings unchanged in later requests, for exact-prefix (local) prompt caches
pi --lens-turn-summary   # Persist a per-turn summary of diagnostics, autofixes, and autoformats
pi --lens-compact-tool-line   # Render tool results as one compact, theme-aware line (closes #1327)
pi --lens-compact-lsp-status  # Collapse the footer LSP status to one state glyph instead of the server names (refs #3099)
pi --lens-hide-lsp-status     # Publish no pi-lens-lsp footer status at all, so a status-rendering host stops showing the key (closes #3099)
pi --lens-compact-widget      # Render the widget as one summary line (languages + totals, LSP↑ chip while servers spawn) with no file rows or blocker details (refs #3959)
pi --lens-issues-status       # Publish a compact pi-lens-issues footer status from the widget summary (●<N>E, !<N>W, ⚠ <N> unchecked, ✓ clean)
pi --no-lazy-tools       # Keep every pi-lens tool active instead of activating the situational ones on demand
pi --lens-turn-end-madge # Run the madge circular-dependency check at every turn end, not just at session start
pi --lens-fallow         # Run fallow-lsp beside the TypeScript server on JS/TS files (advisory unused-code, duplication and cycle findings; opt-in)
pi --no-knip             # Disable the knip session-start analyzer
pi --no-jscpd            # Disable the jscpd session-start analyzer
pi --no-madge            # Disable the madge session-start analyzer
pi --no-gitleaks         # Disable the gitleaks session-start analyzer
pi --no-govulncheck      # Disable the govulncheck session-start analyzer
pi --no-dead-code        # Disable the dead-code session-start analyzer
pi --no-complexity       # Disable the complexity analyzer and the per-edit complexity line

# Actionable warnings (all default off)
pi --lens-actionable-warnings          # Report fixable warnings at turn end
pi --lens-actionable-warning-actions   # Enrich the report with LSP code-action titles
pi --lens-actionable-warning-autofix   # Apply conservative LSP quickfixes at agent_end
pi --lens-actionable-warning-all       # Report every warning, not just this turn's
```

Every one of these has a `~/.pi-lens/config.json` equivalent, so you can set it
once instead of per session. See
[Global and Project Config](globalconfig.md#every-toggle-both-ways) for the
flag-to-key table and the precedence order.

## Rules

### Tree-sitter rules

Tree-sitter rules live under `rules/tree-sitter-queries/<language>/` and are
query-based. Use them when you need precise tree relationships or post-filters.
See [`docs/custom-rules.md`](../docs/custom-rules.md) and the
`pi-lens-write-tree-sitter-rule` skill.

### ast-grep rules

ast-grep rules live under `rules/ast-grep-rules/rules/`. Every shipped rule must
have a fixture in `rules/ast-grep-rules/rule-tests/`. Use the
`pi-lens-write-ast-grep-rule` skill for schema and runner gotchas.

The shipped baseline combines native pi-lens rules with vendored CodeRabbit
security rules under `rules/ast-grep-rules/coderabbit/rules/`.

## Security and dependency scans

Session-level scanners run in the background and surface at turn end:

- `gitleaks` — committed secrets.
- `govulncheck` — reachable Go vulnerabilities.
- `trivy` — dependency CVEs, hardcoded secrets, license risk, and IaC config
  scans when explicitly enabled.

Per-edit IaC config scanning currently covers Dockerfiles and Kubernetes-style
YAML when `trivy.enabled` is true.

## MCP mirror

pi-lens also ships an MCP server for Claude Code or other MCP clients. It is a
second host adapter that calls the same `clients/lens-engine.ts` seam as the pi
extension. Use `npm run build:dist` after MCP/engine changes so the user-scoped
server loads fresh compiled code.

Two Claude Code hooks give the MCP mirror the same automatic cadence the pi
extension has. PostToolUse runs the per-edit pass, `Stop` runs the per-turn one:

```json
{ "hooks": {
  "PostToolUse": [
    { "matcher": "Edit|Write",
      "hooks": [ { "type": "command", "command": "pi-lens-analyze --hook" } ] } ],
  "Stop": [
    { "hooks": [ { "type": "command", "command": "pi-lens-analyze --turn-end", "timeout": 60 } ] } ]
} }
```

The `Stop` hook only works against a running MCP server because only that
process owns the session state and pending turn work. With no warm server the
turn-end is skipped, not faked: one line on stderr and nothing on stdout.

## Troubleshooting

- Run `npm run build` before tests after editing TypeScript; tests import
  generated `.js` artifacts.
- Use `lens_diagnostics mode=all` to surface stale blockers from the current
  session.
- Check `~/.pi-lens/sessionstart.log`, `~/.pi-lens/latency.log`, and
  `~/.pi-lens/cascade.log` for lifecycle/performance/debug traces.
- For live tool validation, use `node scripts/smoke-tools.mjs` with the relevant
  `--lsp`, `--format`, or `--autofix` layer. `--resolution` checks, without
  installing or spawning anything, that the resolvers find project-local tools in
  `.venv/bin`, `vendor/bin` and `node_modules/.bin` (it runs nightly in
  tool-smoke).

### Install notes

pi-lens delivers its four skills through the `pi.skills` package manifest, so
install it as a package (`npm:`, `git:`, or a local path); a package install
honours the host's `packages[].skills` filters (for example `[]`,
`!skills/<name>/SKILL.md`, or `-skills/<name>/SKILL.md`). Loading the extension
file directly (`pi --extension ./index.js`) does not read that manifest and
loads no pi-lens skills. To install from git, run
`pi install git:github.com/apmantza/pi-lens`.

> **npm v12 users:** dependency lifecycle scripts (e.g. `@ast-grep/cli`'s
> `postinstall`) now require explicit approval — if `npm install` warns about
> unreviewed install scripts, review and allow them with
> `npm approve-scripts` in pi's install root. The `allowScripts` entries in
> pi-lens's own `package.json` do not apply when pi-lens is installed as a
> dependency: copy them into the install root's `package.json` instead
> (maintainers: see CONTRIBUTING.md "Lifecycle-script approvals"). Installing from a git source (`pi install
> git:...` / `pi update --extension git:...`) may similarly prompt for
> git-dependency approval; accept it to let the `prepare` build step run.

#### Android and Termux fallback

Try the normal install first. If it fails in `@ast-grep/cli`'s
`postinstall.js` with `Failed to locate @ast-grep/cli native binary`, the
fallback below has worked in one Termux environment:

```bash
pkg install rust clang
cargo install ast-grep --locked
ast-grep --version
npm_config_ignore_scripts=true pi install npm:pi-lens
```

`npm_config_ignore_scripts=true` skips every dependency lifecycle script for
that `pi install` command, not only the failing `@ast-grep/cli` script. Use it
only for this fallback after installing and checking the Rust-built `ast-grep`
binary separately. `pi update` runs the same postinstall, so set the variable
for it too. `ast-grep --version` must succeed from a new shell, which means
`~/.cargo/bin` is on your `PATH`.

In the verified environment, `/lens-health` reported zero pipeline crashes and
listed the `ast-grep` and `bash` LSP servers as available. This confirms startup
and server discovery only; `ast_grep_search` was not tested end to end.

pi-lens only looks for an `ast-grep` on `PATH` (such as Cargo's
`~/.cargo/bin/ast-grep`) when pi trusts the project, so in an untrusted
project this fallback leaves `ast_grep_search` unavailable. The in-process
ast-grep rules (`@ast-grep/napi`) and Biome have no Android build, so they stay
unavailable either way.
