pi

1. Project Overview

Pi is a self-extensible, terminal-based coding agent framework built on top of the Claude Agent SDK, giving developers an interactive CLI that can plan, edit code, run tools, and support multiple LLM providers in a single unified runtime.

2. Background & Positioning

Pi was created to give developers a coding agent they can fully own and extend, rather than a closed, single-vendor assistant baked into one IDE or platform. Its core mission is to provide a lightweight, composable "agent harness": a runtime that manages tool calls and state, a terminal UI, and a model abstraction layer, all exposed as separate packages so teams can build their own agents on top of the same primitives Pi itself uses.

Compared with similar coding-agent projects, Pi differentiates itself in three ways:

• Provider-agnostic by design — instead of hard-coding a single AI vendor, Pi ships a unified LLM API (pi-ai) that speaks to OpenAI, Anthropic, Google, and other providers through one interface.
• Composable architecture — the CLI, the agent runtime, the model layer, the terminal UI, and telemetry are separate packages, so developers can reuse individual pieces instead of the whole application.
• Supply-chain conscious — the project pins dependencies and ships shrinkwrap files, reflecting a deliberate focus on reproducible, auditable builds for a tool that runs with host-level permissions.

3. Feature Categories

🧠 Agent Runtime
Core package handling tool-calling loops and conversation/application state.

• Tool invocation and result handling
• State persistence across a session
• Extensible tool registration
• Purpose: gives any CLI or app the "brain" needed to run an autonomous coding agent.

🌐 Multi-Provider LLM Layer
A unified abstraction over multiple large language model APIs.

• OpenAI support
• Anthropic (Claude) support
• Google support
• Provider-agnostic request/response typing
• Purpose: lets developers swap or mix model providers without rewriting application logic.

💻 Interactive CLI
The flagship pi-coding-agent terminal application.

• Interactive coding sessions in the terminal
• File editing and command execution via tools
• Session-based workflows
• Purpose: the day-to-day entry point developers use to work with Pi on real codebases.

🎛️ Terminal UI Library
A dedicated package (pi-tui) for building rich terminal interfaces.

• Differential rendering for smooth updates
• Reusable UI primitives for agent output
• Purpose: powers Pi's own CLI experience and can be reused to build other terminal-based agent tools.

📊 Telemetry Framework
Vendor-neutral telemetry contracts and typed schemas (pi-telemetry).

• Structured, typed event schemas
• Vendor-neutral design (not tied to a single analytics backend)
• Purpose: lets teams observe and improve agent behavior without lock-in to one telemetry provider.

4. Key Highlights

• Self-extensible harness — Pi is built so that developers can extend and reshape the agent itself, rather than being limited to a fixed feature set.
• Multi-provider flexibility — switch between OpenAI, Anthropic, Google, and other LLM providers through one consistent API surface.
• Modular package design — five focused packages (CLI, agent core, AI layer, telemetry, TUI) can be adopted independently or together.
• Terminal-first UX — a differential-rendering terminal UI keeps interactive sessions fast and responsive without leaving the command line.
• Transparency on security — the project explicitly documents that it has no built-in permission system for filesystem, process, network, or credential access, and instead publishes containerization patterns (Gondolin, plain Docker, OpenShell) for teams that need isolation.
• Reproducible builds — pinned dependencies and shrinkwrap files support supply-chain integrity for a tool that runs with full host permissions by default.

5. Use Cases by Role

• General developers: Use the pi-coding-agent CLI as a day-to-day pair-programming assistant for writing, editing, and debugging code directly in the terminal.
• Platform/tooling engineers: Build custom coding agents or internal developer tools on top of pi-agent-core, pi-ai, and pi-tui instead of starting from scratch.
• Security-conscious teams: Run Pi inside one of the documented containerization patterns (Gondolin, Docker, OpenShell) to constrain filesystem, network, and credential access before granting it host-level tasks.
• DevOps/SRE: Integrate the vendor-neutral pi-telemetry schemas into existing observability pipelines to monitor agent usage and reliability.

6. Getting Started

Find what you need — start with the official documentation site:

https://pi.dev/docs/latest

Install and run:

npm install --ignore-scripts
npm run build

For a fully offline rebuild using cached model data:

npm run build:offline

Run the CLI from source for local testing:

./pi-test.sh

Contribute:

npm run check   # lint, format, and type validation
./test.sh        # run the test suite

See CONTRIBUTING.md and AGENTS.md in the repository for contribution guidelines.

7. Project Structure

pi/
├── packages/
│   ├── pi-coding-agent/   # Interactive CLI (main entry point)
│   ├── pi-agent-core/     # Agent runtime: tool calling & state management
│   ├── pi-ai/             # Unified multi-provider LLM API
│   ├── pi-telemetry/      # Vendor-neutral telemetry contracts/schemas
│   └── pi-tui/            # Terminal UI library (differential rendering)
├── CONTRIBUTING.md        # Contribution guidelines
├── AGENTS.md              # Agent-related development notes
├── test.sh                # Full test suite runner
└── pi-test.sh              # Run the CLI directly from source

The package split mirrors Pi's design philosophy: the CLI is just one consumer of the underlying agent runtime, model layer, and UI toolkit, all of which are independently reusable.

8. Related Ecosystem

• Claude Agent SDK — the underlying SDK that Pi's agent harness is built on.
• LLM providers — OpenAI, Anthropic, and Google APIs, accessed through the pi-ai abstraction layer.
• Containerization tooling — Gondolin, Docker, and OpenShell are documented as complementary isolation layers for running Pi safely.
• npm registry — Pi is distributed as @earendil-works/pi-coding-agent and related scoped packages.

9. License

Pi is released under the MIT License.

• ✅ Free to use, copy, modify, and distribute, including for commercial purposes
• ✅ Free to build derivative tools on top of pi-agent-core, pi-ai, and pi-tui
• ❌ Comes with no warranty; the authors are not liable for damages arising from use
• ℹ️ The original copyright and license notice must be retained in copies or substantial portions of the software
• ℹ️ Pi runs with host process permissions by default and has no built-in access control — review the containerization guidance before granting it access to sensitive environments

10. FAQ

Q: What LLM providers does Pi support?
A: Through its pi-ai package, Pi supports OpenAI, Anthropic, Google, and other providers behind a single unified API.

Q: Is it safe to let Pi run commands on my machine?
A: Pi has no built-in permission system restricting filesystem, process, network, or credential access — it runs with host process permissions by default. For isolation, use one of the documented containerization patterns (Gondolin, Docker, or OpenShell).

Q: How do I install and build Pi from source?
A: Run npm install --ignore-scripts followed by npm run build (or npm run build:offline for an offline rebuild), then use ./pi-test.sh to run it from source.

Q: Can I use only part of Pi, like the terminal UI or the agent runtime?
A: Yes. Pi is split into independent packages (pi-coding-agent, pi-agent-core, pi-ai, pi-telemetry, pi-tui), so you can adopt individual components without the full CLI.

Q: How can I contribute?
A: Run npm run check and ./test.sh before submitting changes, and follow the guidelines in CONTRIBUTING.md and AGENTS.md in the repository.

11. Quick Links

• Repository: https://github.com/earendil-works/pi
• Official documentation: https://pi.dev/docs/latest
• Homepage: https://pi.dev
• Contributing guide: CONTRIBUTING.md (in the repository)
• Community: Discord server linked from the project homepage

12. Summary

Pi offers developers a provider-agnostic, self-extensible coding agent that can be used as a ready-made terminal CLI or as a set of composable building blocks (agent runtime, model layer, terminal UI, telemetry) for building custom agents. It's best suited for developers and platform teams who want control over their AI coding tools rather than a closed, single-vendor assistant — with the explicit understanding that access control and isolation are the operator's responsibility, not a built-in feature.