# 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](docs/agent-guide.md) > 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, diagnostics state, and project intelligence - Review-graph intelligence for supported languages via bundled tree-sitter WASMs - Ranked identifier search (`symbol_search`) over an always-warm word index, feeding the discovery funnel (symbol_search → module_report → read_symbol) - Diagnostic triage (`lens_diagnostic_mark`): findings can be marked false-positive, suppressed in source, deferred, or flagged-to-fix — honored across all surfaces - `/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 ledger for silently-degraded behavior (LSP breakers, formatter skips/failures, idle evictions, timeouts) - MCP server (experimental) so Claude Code or any MCP client can drive the same diagnostics/read-substitute tools pi-lens exposes to pi ## 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. ```mermaid flowchart TD subgraph host["pi host"] HOST["Host events
tool_call, tool_result, turn_start/end,
session_start/shutdown, agent_end, context"] WRAP["Stale-ctx wrapper
skips and counts events on a replaced session
tool_result, turn_start, turn_end, agent_end,
agent_settled, session_start, context"] end subgraph guards["Guards"] RG["Read-guard
blocks edits that lack prior reading"] GG["Git-guard
holds commit/push while findings stay unresolved"] end subgraph edit["Edit-time lane"] PIPE["Post-write pipeline
secrets, format, autofix, sync, lint, tests"] PLAN["Dispatch plan
per file kind, per capability group"] RUN["Runners
format, lint, types, security, smells, docs"] STRUCT["Structural rules
tree-sitter queries and ast-grep"] BUS["files-touched bus
tells extensions which paths moved"] end subgraph lsp["LSP lane"] POOL["Client pool
warm reuse, idle eviction"] DIAGS["File and workspace diagnostics"] CASC["Impact cascade
tiered wait policy"] end STORES["Findings stores
widget state, warning caches, project snapshot"] subgraph gate["Freshness gating"] FRESH["Path freshness
mtime vs scan time, past-EOF, dependency drift"] DISPO["Dispositions
false-positive, suppress, defer, flagged"] LABEL["Explicit age label
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
primary, sequential replacement, concurrent secondary"] SINKS["Observability sinks
latency.log, degradation ledger, bounded telemetry,
cache observability, cascade and tree-sitter logs"] 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 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](docs/features.md) and [language coverage](docs/language-coverage.md). Today the edit-time lane carries 45+ runner modules over 35+ file kinds, and the LSP lane speaks to a dozen-plus language servers. 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 ```bash pi install npm:pi-lens ``` Or from git: ```bash 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`, or trust the `allowScripts` entries already declared > in this package's `package.json`. 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. ## Documentation - [Agent guide](docs/agent-guide.md) — how an AI agent should consume and respond to pi-lens - [Agent tools](docs/agent-tools.md) — pi tool names, scopes, and arguments - [Usage guide](docs/usage.md) — lifecycle, tool behavior, MCP notes, and troubleshooting - [Features](docs/features.md) — detailed feature reference - [Word index](docs/word-index.md) — identifier search (`symbol_search`) and the discovery funnel - [Tools and commands](docs/tools.md) — runtime flags and slash commands - [Diagnostic dispositions](docs/dispositions.md) — triage: false-positive, suppress, defer, flagged-to-fix - [Settings](docs/settings.md) — the configuration hub: defaults, env vars, CLI flags, and global vs project config at a glance - [Configuration](docs/globalconfig.md) — global and project config files - [Environment variables](docs/environment-variables.md) — common env vars and full reference - [Language coverage](docs/language-coverage.md) — supported languages, runners, and formatters - [Dependencies](docs/dependencies.md) — auto-install policy and external tools - [Custom rules](docs/custom-rules.md) — project ast-grep and tree-sitter rules - [MCP server](docs/mcp.md) — experimental MCP server for Claude Code and other MCP clients ## Contributing See [`CONTRIBUTING.md`](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`](SECURITY.md). pi-lens is released under the [MIT License](LICENSE). ## Contributors Thanks goes to these wonderful people:

Apostolos Mantzaris 💻 📖 🤔 🚧 👀	Kenneth McCormick 🐛 💻	Anh Chu 💻	minicx 💻	silvanshade 💻	Tifan Dwi Avianto 💻	Amit 💻 🐛
Fractiunate // David Rahäuser 💻	Vitali Karasenko 💻	V 💻	Fabio Dee 💻	moj02090 💻	Micah Halter 💻	Julien Ellie 💻
Ruben Paz 💻 🐛	C.Junxiang 💻 🐛	Trevon 💻	Aaron Bell 💻 🐛	Will Mitchell 💻	spyrosbazios 💻	Roman Galeev 💻
jerryfan 💻	Max L. 💻	David Ryan 💻	JayceFreeman 💻	Heitor Ramon Ribeiro 💻	Chris Patti 💻 🐛	Chenxin Yan 💻 📖 🐛
flowing-abyss 💻	shaochong-theoai 💻	Xu Yili 🐛 💻	Ricardo Raposo 💻	Justin Smestad 💻	anasalsbey-glitch 💻 🐛	정제훈 💻
Myke Stubbs 💻 🐛	JSap0914 💻	Kent Hou Man 💻 🐛	Jakub Neumann 💻	CyYu 💻	Carolina 🐛	LeakedBy 🐛
Matthew Booth 🐛	Wiedzmin89 🤔	Virgile 🐛	Finn 🤔	Wayne E 🐛	RimuruW 🤔	Bjynt 🐛 🤔
Tri Van Pham 🐛	BingWuJ 🐛	tackleberrybey 🐛	Mariann Abshire 🐛	ProbabilityEngineer 🤔	Leonardo Rick 🐛 🤔	Ken Banks 🐛
Rico Sta. Cruz 🤔	Nikita Bilous 🐛	Andrea Arturo Venti Fuentes 🐛	dacec354 🐛	Brandon Martin 🐛	Alper Tarhan 🐛	Andrius Solopovas 🐛
Graham Jenkins 🐛	Wings Butterfly 🐛	Johannes Klauss 🤔	Tan Yong Sheng 🤔	Frédéric 🐛	Salvador Fuentes Jr 🐛	Viktor 🐛
Gregory Orton 🐛	Jim Allen 🐛	quantfiction 🐛	Art 🐛	Colin Swenson-Healey 🐛	Laurent Wiesel 🐛	Rei Starks 🐛
Roberto Freitas 🐛	tmttodd 🐛	smaharnav 🐛	Mza.Guille 🐛	Jason Rimmer 🐛	Arthur Heymans 🤔	Blue-B 🐛
Biser Perchinkov 🐛	Peter Nagy 🐛	Orest Tokovenko 🐛	Federico Pasqua 🐛	Ronald 🐛	Aaron Ky-Riesenbach 🐛	可爱的龙 🐛
pppobear 🐛	Bertrand Cachet 💻	earthchen 💻	Don Yin 💻	ELA718 📖	Sujeito Operator 💻	Dan Blah 🐛
Nathan Cooke 💻	Eli Stark 💻	Marvin Aziz 💻	Mark 💻	aeturnal 💻	floatGray 💻

The following commit identities also appear in `git shortlog -sne HEAD` but are not represented in the generated table above: Anas Alsbei, Claude, Christopher Patti, dependabot[bot], Fabio-D, github-actions[bot], JSup, Kenny McCormick, Max Lupus, Moritz Hofmann, ricardo, and root. If you land a pull request or report an issue that gets fixed, we'll add you here.