Status

Pi Agent IDE is experimental and under active development. It is used in real work, but bugs and rough edges are still being found and fixed. Interfaces and behavior may change.

The current focus is measurement. The project is being compared with vanilla Pi on evals and editing gyms to understand where its tools improve results or reduce tool use and token use. Some workflows already benefit from the tools; others become harder. Until the data is stronger, treat performance claims as unproven and use the package at your own risk.

What it does

Pi Agent IDE provides a small set of tools with more specialized behavior behind them:

• read handles files, web pages, images, PDFs, code views, and diagnostics;
• search routes text, structural, semantic, and web searches;
• write, replace, insert, delete, copy, and move cover common text mutations; range-based edits can target snapshot and semantic anchors instead of reproducing the oldText block required by Pi's built-in edit tool;
• optional plugins add AST, LSP, formatting, linting, and Git-aware behavior;
• /pi-agent-ide-doctor detects project languages and lets each loaded plugin check or configure its own scope.

The public interface is intentionally small. Resources, resolvers, anchors, renderers, and toolchain integrations are connected through versioned plugin protocols. The npm package loads as one Pi extension, while its built-ins remain separate modules that can be replaced or extended.

Installation

Install Pi first, then install Pi Agent IDE:

pi install npm:pi-agent-ide

Pi packages run with your full system permissions. Review the package before installing it.

Check project setup

Start Pi in your project directory, then run:

/pi-agent-ide-doctor

Doctor detects the project languages and asks each loaded plugin to check its own tools and configuration. It reports missing executables, formatter and linter mappings, language servers, AST support, search setup, and Git support.

Doctor shows its report before changing anything. If you approve the suggested setup, it writes project-local mappings under .pi/pi-agent-ide/ without replacing native files such as eslint.config.js, .clang-format, or pyproject.toml. When setup still needs work, you can ask the agent to finish it; doctor runs the checks again afterward.

Run doctor again after installing or changing project tools. For non-interactive use and command flags, see Configuration.

Documentation

| Document | Contents | | ------------------------------------------ | -------------------------------------------------------------------- | | Tools and workflow | Read, search, editing, anchors, and feedback | | Architecture | Module boundaries, protocols, and the umbrella extension | | Configuration | Run doctor, configure project tools and search, or disable built-ins | | Writing extensions | Add resolvers, anchors, search backends, and IDE plugins | | Development | Work from a checkout, test, and run modular mode | | Evaluation | Compare Pi Agent IDE with vanilla Pi on repeatable tasks |

Repository

Executable behavior is defined by the source and tests. The documents above explain the intended boundaries, extension contracts, and development workflows.

License

MIT