# 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"] CONFIG["Config-core
resolve, merge, deny"] REVIEWGRAPH["Review-graph intelligence
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](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 47 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 ```bash pi install npm:pi-lens ``` Or from git: ```bash pi install git:github.com/apmantza/pi-lens ``` 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//SKILL.md`, or `-skills//SKILL.md`). 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`). Letting a coding agent do it: paste this into its prompt. ```text 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 — 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` (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. ## 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 - [Architecture decision records](docs/adr/README.md) — settled design decisions, linked from the engineering-defect catalog ## 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 💻	Thomas F Steeples 💻 🐛
Ama Senevirathne 💻	AcademyKUB8 💻 🐛	soulocker 🐛	Johanderson Mogollon 🤔 🐛	kurihada 🐛	Giraffe224 🐛	Robert Navarro 🐛 💻
Marc 🐛	Heyner Javier Marmol Verbel 🐛	Stijnus 🐛	macroxing 🐛	John Tracy 💻	woyxiang 🤔	Juncanthia 🐛
Kevin S Kirkup 🐛	George Harker 💻 🐛 🤔	Duy /zuey/ 🤔 💻	luw2007 🐛	WrongWorry 🐛	nanaxx131-gif 🐛	MateusCx 🐛
Hugh Zadora 🐛	撑伞的鱼 🐛	Lv 🐛	apmcodes 🐛	Jonathan Dong 🐛	Caprika 🐛 💻	dmontague-crwv 🐛
Yihang "Corvo" Liu 🐛	Luca Barrella 💻 🤔	xuankun zheng 💻 🐛 🤔 📖 ⚠️	Younes Beriane 💻	Jakob Sjælland 🐛	Brian B 💻	dearbld 💻
Fredrik Ekman 💻	plutoYang 💻	Flash-Z 🐛	Kristjan 🐛	raulriqueleme79-wq 🐛	liujam 🐛	Go.YAMADA 🐛
Benedikt Rötsch 🤔	Stark-X 🐛	Yahav Bahat 🐛	Edwin A. Saavedra Navarro 🐛	Laurent 🐛	vincent 🐛 🤔	Linx 🐛
Audi Young 🐛	Adam Spiers 🐛	Claudio Cocciarelli 🤔	205 Dev 🐛	Ea Chan 🐛	XiaoMing 🐛	John Reeder 🐛 🤔
Yejia Mo 🤔	bricabrol 🐛	0xkite 🐛	Steve Lovelace 🐛	ravshansbox 🐛	misc4747 🐛	Jérémy Audiger 🤔
Sebastian Rogers 🐛	Pierre 🤔	douglasf 🐛	Bolshakov Danila 🤔	theverymrp 🐛	Kaushal Prajapati 🐛	Shyamalan Kannan 🤔
Neil Chambers 🐛	Denis Da Silva Rocha 🤔	David Brenton Allen 🐛	Anders E. Andersen 🐛	Vedmaka 🐛	sith007 🐛	Punk Dev Robot 🐛
StativBus 🤔	Max Swain 🤔	DrunkenDonkey80 🐛	marioHealthSoft 🤔	Orestes Kassian 🤔	vanyastaff 🐛	周凯 💻
pikachu01 🤔	Igor G. Gor 🐛	dampent 🐛	arbelafor 🐛	yangfan qi 🤔	IGabrielRC 🐛	Taras Zubrei 🤔
pandas9 🐛	Renzo Oliveira 🤔