3 Pi Overview
3.1 What Is Pi?
Pi is a minimal terminal coding harness developed by Earendil Inc. It is designed to stay small at the core while being extended through TypeScript extensions, skills, prompt templates, themes, and pi packages. Unlike monolithic AI coding assistants, Pi deliberately keeps its kernel compact and pushes workflow-specific behavior into composable, user-controlled extensions.
Pi runs in your terminal, operates on your local source trees, and integrates with your existing development environment. It invokes project toolchains, modifies files, and executes shell commands—all with the permissions of the user account that starts it.
3.2 Design Philosophy
3.2.1 Minimal Kernel, Maximum Extensibility
Pi is built on a simple but powerful idea: the core should stay small, and workflow-specific features should be pushed into extensions, skills, prompt templates, and packages. This design decision manifests in several ways:
- No built-in MCP server — use extensions or packages if you need it
- No sub-agents — build or install them as extensions
- No permission popups — handled through project trust and extensions
- No plan mode or to-dos — implement via extensions
- No background bash — use external tools like containers and tmux
This philosophy means Pi avoids feature creep. Every capability beyond the core four tools is opt-in, installed only when you need it.
3.2.2 Local-First
Pi is designed to operate on local source trees. It does not include a built-in sandbox because real isolation must come from the operating system or a virtualization/container boundary. This is intentional—a partial in-process sandbox would be easy to misunderstand as a security boundary while still depending on the host shell, filesystem, and credentials.
3.3 Core Features
3.3.1 Four Built-in Tools
Pi provides four essential tools by default:
| Tool | Description |
|---|---|
read |
Read file contents from the local filesystem |
write |
Create or overwrite files |
edit |
Apply precise patches to existing files |
bash |
Run shell commands with the user’s permissions |
Additional built-in read-only tools (grep, find, ls) are available through tool options. This minimal toolkit gives the model everything it needs to understand, navigate, and modify a codebase.
3.3.2 Extension System
Extensions are TypeScript modules that can:
- Register custom tools callable by the LLM
- Subscribe to lifecycle events and intercept tool calls
- Add custom slash commands
- Render custom TUI components
- Implement custom providers and OAuth flows
3.3.3 Skill System
Skills are self-contained capability packages that the agent loads on-demand. They provide specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks. Pi implements the Agent Skills standard for cross-harness compatibility.
3.3.4 Session Management
Pi saves conversations as tree-structured JSONL session files. You can resume previous work, branch from earlier turns, and revisit abandoned paths—all without creating new files.
3.4 Comparison with Other Tools
| Feature | Pi | Claude Code | Cursor |
|---|---|---|---|
| Interface | Terminal (TUI) | Terminal (TUI) | IDE |
| Core tools | 4 (read/write/edit/bash) | Similar | Built-in |
| Extension language | TypeScript | Limited | Plugin system |
| Built-in sandbox | No (by design) | No | No |
| Session format | JSONL tree | Linear | IDE state |
| MCP built-in | No (extension) | Yes | No |
| Sub-agents | No (extension) | Yes | No |
| Model support | Multi-provider | Anthropic | Multi-provider |
| Custom providers | Full API | Limited | No |
| Themes | JSON-based | Limited | IDE |
| Open source | Yes (MIT) | No | No |
Pi’s key differentiator is its commitment to extensibility over built-in features. Where other tools bake features into the core, Pi provides the infrastructure and lets you choose what to add.
3.5 Installation
3.5.1 Prerequisites
Pi requires Node.js to be installed on your system.
3.5.2 npm Installation
npm install -g --ignore-scripts @earendil-works/pi-coding-agentThe --ignore-scripts flag disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
3.5.3 curl Installation (Linux/macOS)
curl -fsSL https://pi.dev/install.sh | shThe curl installer uses npm globally under the hood, so both installation methods are equivalent.
3.5.4 Verification
After installation, verify Pi is available:
pi --version3.5.5 Uninstallation
Use the package manager that installed Pi:
# curl installer or npm install -g
npm uninstall -g @earendil-works/pi-coding-agent
# pnpm
pnpm remove -g @earendil-works/pi-coding-agent
# Yarn
yarn global remove @earendil-works/pi-coding-agent
# Bun
bun uninstall -g @earendil-works/pi-coding-agentUninstalling Pi leaves settings, credentials, sessions, and installed pi packages in ~/.pi/agent/.
Pi is open source under the MIT License. The source code is available at GitHub.
3.6 Quick Start
# Install
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# Navigate to your project
cd /path/to/project
# Start Pi
pi
# Authenticate (subscription) or set an API key
# Inside Pi: /login
# Or before starting: export ANTHROPIC_API_KEY=sk-ant-...For the full first-run experience including authentication options, context files, and common operations, see the Quickstart chapter.