pi-lens
pi-lens gives AI coding agents fast, language-aware feedback while they write/edit.
Working in this project as an AI agent? Read the agent guide
for how pi-lens surfaces diagnostics (honesty labels, blockers, read-before-edit)
and how to respond.
What It Does
- LSP diagnostics and navigation across supported languages
- Impact cascade diagnostics that show which related files were affected and run LSP diagnostics on them
- Language-specific linters, type-checkers, and scanners on every write/edit
- Safe formatting/autofix where tools are configured or confidently detected
- ast-grep and tree-sitter structural rules for correctness/security smells
- Agent-facing tools for LSP navigation/diagnostics, AST search/replace,
- Review-graph intelligence for supported languages via bundled tree-sitter WASMs
- Ranked identifier search (
symbol_search) over an always-warm word index,
- Diagnostic triage (
lens_diagnostic_mark): findings can be marked
/lens-map— interactive HTML dependency map of the project- Read-guard and edit-autopatch support to reduce bad edits
- Background security/dependency scans for opted-in projects
- Runtime health telemetry (
/lens-health) including a bounded degradation
- MCP server (experimental) so Claude Code or any MCP client can drive the
Architecture
Most lifecycle events enter through one wrapper, which drops and counts events
that arrive on a replaced session. tool_call registers raw: it delegates
straight to a handler that owns its own total guard. Events fan out into the
edit-time lane and the LSP lane. Both lanes write into the findings stores.
Nothing reaches the agent from those stores until a freshness gate or an
explicit age label clears it.
flowchart TD
subgraph host["pi host"]
HOST["Host events<br/>tool_call, tool_result, turn_start/end,<br/>session_start/shutdown, agent_end, context"]
WRAP["Stale-ctx wrapper<br/>skips and counts events on a replaced session<br/>tool_result, turn_start, turn_end, agent_end,<br/>agent_settled, session_start, context"]
end
subgraph guards["Guards"]
RG["Read-guard<br/>blocks edits that lack prior reading"]
GG["Git-guard<br/>holds commit/push while findings stay unresolved"]
end
subgraph edit["Edit-time lane"]
PIPE["Post-write pipeline<br/>secrets, format, autofix, sync, lint, tests"]
PLAN["Dispatch plan<br/>per file kind, per capability group"]
RUN["Runners<br/>format, lint, types, security, smells, docs"]
STRUCT["Structural rules<br/>tree-sitter queries and ast-grep"]
BUS["files-touched bus<br/>tells extensions which paths moved"]
end
subgraph lsp["LSP lane"]
POOL["Client pool<br/>warm reuse, idle eviction"]
DIAGS["File and workspace diagnostics"]
CASC["Impact cascade<br/>tiered wait policy"]
end
STORES["Findings stores<br/>widget state, warning caches, project snapshot"]
subgraph gate["Freshness gating"]
FRESH["Path freshness<br/>mtime vs scan time, past-EOF, dependency drift"]
DISPO["Dispositions<br/>false-positive, suppress, defer, flagged"]
LABEL["Explicit age label<br/>for findings no path gate can check"]
end
subgraph deliver["Delivery surfaces"]
TURN["Turn-end findings injection"]
WIDGET["Widget and footer tally"]
TOOLS["lens_diagnostics tool"]
NUDGE["Agent nudges"]
end
SESSION["Session lifecycle<br/>primary, sequential replacement, concurrent secondary"]
SINKS["Observability sinks<br/>latency.log, degradation ledger, bounded telemetry,<br/>cache observability, cascade and tree-sitter logs"]
CONFIG["Config-core<br/>resolve, merge, deny"]
REVIEWGRAPH["Review-graph intelligence<br/>call graph, reverse deps, import resolution"]
HOST --> WRAP
HOST -->|tool_call, raw| RG
HOST -->|tool_call, raw| GG
WRAP -->|session_start| SESSION
WRAP -->|tool_result| PIPE
WRAP -->|tool_result, records reads and writes| RG
SESSION --> POOL
SESSION --> STORES
PIPE --> PLAN
PLAN --> RUN
PLAN --> STRUCT
PIPE --> POOL
PIPE --> BUS
CONFIG --> PIPE
CONFIG --> PLAN
STRUCT --> REVIEWGRAPH
REVIEWGRAPH --> CASC
POOL --> DIAGS
DIAGS --> CASC
RUN --> STORES
STRUCT --> STORES
DIAGS --> STORES
CASC --> STORES
BUS --> NUDGE
RG -->|read and edit history filter| NUDGE
STORES --> FRESH
STORES --> LABEL
FRESH --> DISPO
DISPO --> TURN
DISPO --> WIDGET
DISPO --> TOOLS
LABEL --> TURN
TURN --> GG
WRAP --> SINKS
PIPE --> SINKS
RUN --> SINKS
STRUCT --> SINKS
POOL --> SINKS
CASC --> SINKS
RG --> SINKS
GG --> SINKS
FRESH --> SINKS
Architecture-level view, updated when a lane changes. Per-tool inventories live in features and language coverage. Today the edit-time lane carries 45+ runner modules over 35+ file kinds, and the LSP lane speaks to 50 language server definitions.
The gating box is an abstraction, not a call order. Freshness covers several
independent mechanisms: path freshness against scan time, past-EOF line checks,
and forward-import dependency drift. Dispositions are one more filter alongside
them, not a second stage every finding walks through. Read the box as "a finding
passes the gates that apply to it", and see clients/finding-delivery-gate.ts
for the per-surface contract.
Install
pi install npm:pi-lensOr from git:
pi install git:github.com/apmantza/pi-lenspi-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/, or -skills/). Loading the extension
file directly (pi --extension ./index.js) does not read that manifest and
loads no pi-lens skills.
Requires Node.js >=22.19.0 (matches the pi host's own floor — see engines
in package.json), and a pi host of 0.86.1 or newer. pi 0.80–0.85 keep the
prompt outside the request the extension can write to, so pi-lens delivers no
findings there; docs/release-qa-baseline.md lists the certified hosts.
Letting a coding agent do it: paste this into its prompt.
Install pi-lens (npm:pi-lens) into pi, then read AGENTS.md in
https://github.com/apmantza/pi-lens for how the extension works and how it
expects to be operated.npm v12 users: dependency lifecycle scripts (e.g. @ast-grep/cli's
postinstall) now require explicit approval — ifnpm installwarns about
unreviewed install scripts, review and allow them with
npm approve-scripts, or trust theallowScriptsentries already declared
in this package's package.json (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/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:
pkg install rust clang
cargo install ast-grep --locked
ast-grep --version
npm_config_ignore_scripts=true pi install npm:pi-lensnpm_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.
Documentation
- Agent guide — how an AI agent should consume and respond to pi-lens
- Agent tools — pi tool names, scopes, and arguments
- Usage guide — lifecycle, tool behavior, MCP notes, and
- Features — detailed feature reference
- Word index — identifier search (
symbol_search) and
- Tools and commands — runtime flags and slash commands
- Diagnostic dispositions — triage: false-positive,
- Settings — the configuration hub: defaults, env vars, CLI
- Configuration — global and project config files
- Environment variables — common env vars and
- Language coverage — supported languages, runners,
- Dependencies — auto-install policy and external tools
- Custom rules — project ast-grep and tree-sitter rules
- MCP server — experimental MCP server for Claude Code and
- Architecture decision records — settled design
Contributing
See CONTRIBUTING.md for the development workflow, runner,
LSP, formatter, and rule checklists, and issue/PR conventions.
Security issues should be reported privately; see SECURITY.md.
pi-lens is released under the MIT License.
Contributors
Thanks goes to these wonderful people:
