pi-lens
Real-time code feedback for pi — LSP, linters, formatters, type-checking, structural analysis & booboo
Package details
Install pi-lens from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:pi-lens- Package
pi-lens- Version
4.5.1- Published
- Nov 16, 2026
- Downloads
- 115K/mo · 27.5K/wk
- Author
- apmantza
- License
- MIT
- Types
- extension, skill
- Size
- 26.3 MB
- Dependencies
- 6 dependencies · 3 peers
Pi manifest JSON
{
"skills": [
"./skills"
],
"extensions": [
"./dist/index.js"
],
"changelogPath": "CHANGELOG-USER.md"
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-lens
pi-lens gives AI coding agents fast, language-aware feedback while they write and edit code. It is an extension for the pi coding agent, with an experimental MCP server for other hosts.
An AI agent working with pi-lens? Read the agent guide. It explains the findings you will see and how to respond.
An AI agent changing pi-lens itself? Read
AGENTS.mdandCONTRIBUTING.md. A one-line-per-doc index for agents is inllms.txt.
Quick start
pi install npm:pi-lens
Or from git: pi install git:github.com/apmantza/pi-lens.
Requirements: Node.js >=22.19.0 and a pi host of 0.86.1 or newer. On pi 0.80–0.85, pi-lens gives no findings, because those hosts keep the prompt where the extension cannot write to it. Release QA baseline lists the certified hosts. See Troubleshooting for npm v12, Android, and skills-manifest notes.
Install it and start a session. The language servers and many linters start with no setup. Some tools need your project's config, and a few are opt-in. See What runs by default and Settings.
To let a coding agent install it, paste this into its prompt:
Install pi-lens (npm:pi-lens) into pi, then read docs/agent-guide.md in
https://github.com/apmantza/pi-lens for how to read and respond to its findings.
What the agent sees
After an edit, the tool result carries any blocking findings, with the offending line. At the end of the turn, pi-lens injects the findings that remain. The text below follows the real renderers: the STOP block from clients/pipeline.ts, and the turn-end framing, Advisory label, and warnings summary from clients/runtime-context.ts and clients/runtime-turn.ts.
🔴 STOP — 1 issue(s) must be fixed:
L4: 'randomInt' is declared but its value is never read.
→ const randomInt = Math.floor(result);
[pi-lens automated check — not a user request] Address 🔴 blockers before continuing; ℹ️ advisories are informational only.
ℹ️ Advisory — no action required this turn:
🟡 Fixable warnings introduced this turn: 1.
Use lens_diagnostics with mode=delta to inspect these warnings.
Files:
src/app.ts: 1
The agent must clear a 🔴 blocker before it reports the task as done. A result marked partial, stale, or unconfirmed is never reported as clean.
What you get
- Real diagnostics on every edit. Language servers, linters, type-checkers, and scanners check each written file, and an impact cascade checks the files that depend on it. See language coverage.
- Safe formatting and autofix. pi-lens formats and fixes files with the tools you configure or it confidently detects.
- Structural rules. ast-grep and tree-sitter rules flag correctness and security smells, and you can add custom rules.
- Code navigation for the agent. Tools cover LSP navigation, ranked identifier search, module reports, and symbol reads, so the agent reads less code. See agent tools.
- Guards and triage. Read-before-edit blocks blind edits, an optional git guard holds
git commitwhile blockers stand, and on pi you can mark a finding false-positive, suppressed, or deferred. The marking tool has no MCP endpoint, and under pi's lazy tool loading the agent activates it first. See dispositions and agent tools. - Health and scans.
/lens-healthreports runtime health, and opted-in projects get background security and dependency scans.
The feature reference covers everything.
What runs by default
pi-lens runs tools in three tiers. The per-tool table lists every gate and where it lives in the code.
- No project config. Language servers start by default, and
--no-lspturns them off. Many linters and formatters also run when the tool is available. Examples: ruff, shellcheck, hadolint, and ktlint for linting; oxlint or Biome for JS and TS when the project has no ESLint config; Biome and shfmt for formatting. - Your project's config. ESLint, golangci-lint, mypy, phpstan, and vale skip a project that lacks their config. detekt needs a detekt config file, credo needs
mix.exs, and the taplo and clang-format formatters wait for config. - Opt-in. trivy (
trivy.enabled), SpotBugs (--lens-spotbugs), Helm render validation (helm.renderValidation.enabled), and the commit guard (--lens-guard) stay off until you enable them.
Project-local binaries, such as node_modules/.bin/eslint or .venv/bin/ruff, run only when pi trusts the project.
Commands you'll use
| Command | What it does |
|---|---|
/lens-health |
Show runtime health, latency, and degradation counts |
/lens-widget-toggle |
Show or hide the diagnostics widget below the editor |
/lens-toggle |
Turn pi-lens on or off for the session |
/lens-map |
Build an interactive HTML dependency map of the project |
/lens-allow-edit <path> |
Override the read-before-edit guard for one edit |
/lens-tools |
Show which tools are installed, auto-installed, or fall back to npx |
The full list of commands and runtime flags is in Tools and commands.
Documentation
Use
- Agent guide: how an agent reads and responds to pi-lens
- Agent tools: tool names, scopes, and arguments
- Usage guide: lifecycle, tool behavior, MCP notes, and troubleshooting
- Features: the detailed feature reference
- Diagnostic dispositions: triage with false-positive, suppress, defer, and flagged-to-fix
- Word index: identifier search and the discovery funnel
Configure
- Settings: defaults, environment variables, flags, and global versus project config
- Configuration: global and project config files
- Environment variables: the full reference
- Language coverage: supported languages, runners, and formatters
- Dependencies: auto-install policy and external tools
Extend
- Custom rules: project ast-grep and tree-sitter rules
- MCP server: the experimental server for Claude Code and other MCP clients
- Architecture: how events reach the findings the agent sees
- Architecture decision records: settled design decisions
Troubleshooting
The install notes in the usage guide cover three cases:
- npm v12 asks you to approve dependency install scripts such as the
@ast-grep/clipostinstall. - Android and Termux can fail to find the
@ast-grep/clinative binary. The notes give a verified fallback. - Skills arrive through the package manifest. Loading the extension file directly (
pi --extension ./index.js) loads no pi-lens skills.
For runtime problems, run /lens-health and read the usage guide troubleshooting section.
Contributing
See CONTRIBUTING.md for the development workflow, runner, LSP, formatter, and rule checklists, and for issue and PR conventions.
Report security issues privately; see SECURITY.md.
pi-lens is released under the MIT License.
Contributors
Thanks goes to these wonderful people: