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, 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

Install

pi install npm:pi-lens

Or from git:

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 — 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 troubleshooting
• Features — detailed feature reference
• Word index — identifier search (symbol_search) and the discovery funnel
• Tools and commands — runtime flags and slash commands
• Diagnostic dispositions — triage: false-positive, suppress, defer, flagged-to-fix
• Settings — the configuration hub: defaults, env vars, CLI flags, and global vs project config at a glance
• Configuration — global and project config files
• Environment variables — common env vars and full reference
• Language coverage — supported languages, runners, and formatters
• 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 other MCP clients

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:

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.