Who Pi is for#
Solo developers extending their own coding agent
Pi gives you a coding agent you can shape in TypeScript without maintaining a fork. Write an extension once, put it in ~/.pi/agent/extensions/, and it loads every session. Prompt templates expand in the editor, skills load on demand via /skill:name, and sessions branch so you can explore alternate approaches without losing history.
Skip if:
Skip Pi if you want a coding agent that works out of the box with MCP integrations, plan mode, and permission prompts already configured. Claude Code ships those defaults without any extension setup required.
Teams sandboxing agent access on untrusted codebases
For teams reviewing or working on codebases they do not fully trust, Pi's Docker patterns let you run the whole agent in a container with only the target directory mounted. The Docker Sandboxes integration (via sbx) keeps provider credentials entirely outside the container while routing inference via a proxy.
Skip if:
Skip this pattern if you need sandboxed agent access without container management overhead. Managed commercial coding agents may be simpler for teams without DevOps capacity.
Developers embedding a coding agent in their own tooling
Pi's SDK mode (createAgentSession) and RPC mode (--mode rpc) let you integrate the agent loop into Node.js apps or non-Node.js tools respectively. SessionManager.inMemory() creates ephemeral sessions; the full session API handles persistent, named, and forked sessions. The JSON event stream exposes every turn, tool call, and result for logging or orchestration.
Skip if:
Skip Pi's SDK if you need multi-agent orchestration with shared context or a managed agent runtime. Pi's SDK is a single-session API; coordination between instances requires custom wiring.
Developers switching between LLM providers
Pi supports 30+ providers including subscriptions (Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro, GitHub Copilot) and API keys (Google Gemini, DeepSeek, Azure OpenAI, xAI, Mistral, Groq, and more). Switch models mid-session with Ctrl+L or cycle a scoped set with Ctrl+P. Custom providers that speak the OpenAI, Anthropic, or Google API can be added via models.json.
Skip if:
Skip Pi if you are locked into a single provider with no need to switch. Claude Code's Anthropic integration may be simpler if you only use Claude models.
The problem it solves#
Most commercial coding agents ship as closed systems with a fixed set of tools, a built-in workflow, and limited options for customization. Plan mode, permission popups, and MCP come bundled whether you need them or not. Adapting the agent to your actual workflow means working around its assumptions rather than building on them.
The extension story for these tools is usually either 'fork the project' or 'wait for a plugin API that may never ship.' Teams with existing context files, tool conventions, or specialized workflows end up maintaining patches or stitching together multiple tools to fill gaps a composable agent core could handle.
How it solves it#
Four built-in tools with a TypeScript extension API
Pi gives the model read, write, edit, and bash by default. TypeScript extensions can register new tools, replace built-in ones, add custom commands and UI components, listen to events, or build permission gates. Extensions ship as pi packages installable from npm or git, so the community can share capabilities without requiring a fork.
30+ LLM providers via API key or subscription
Authenticate with Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro, or GitHub Copilot by subscription, or bring an API key for providers including Google Gemini, DeepSeek, Azure OpenAI, Mistral, Groq, Amazon Bedrock, xAI, OpenRouter, Hugging Face, and more. Switch models mid-session with Ctrl+L or cycle a scoped set with Ctrl+P.
Persistent sessions with in-place branching
Sessions save to JSONL files with a tree structure, so every message has an id and parentId rather than creating new files on each branch. The /tree command navigates the session tree in-place: select any previous point, continue from there, and switch between branches without losing history. Fork or clone sessions directly from the CLI.
Interactive, print, JSON, RPC, and SDK modes
Run pi interactively for terminal work, use -p for one-shot non-interactive prompts, --mode json for JSONL event streams, or --mode rpc for process integration over stdin/stdout. The SDK (createAgentSession) embeds Pi in Node.js applications with full programmatic control over sessions and model runtimes.
Shareable pi packages via npm and git
Bundle extensions, skills, prompt templates, and themes as pi packages and share them via npm (pi install npm:@foo/pi-tools) or git (pi install git:github.com/user/repo). Pi auto-discovers resources from conventional directories without a manifest. Community packages are findable on npmjs.com with the pi-package keyword.
Strengths and trade-offs#
Strengths
- MIT license with a fully auditable TypeScript coreThe entire agent core is MIT licensed, meaning you can modify, fork, and deploy it commercially without restriction. Unlike proprietary coding agents where the extension API is a closed plugin surface, Pi's TypeScript extension API runs in the same process, and the full source is on GitHub under earendil-works/pi.
- Add or replace any capability without forkingTypeScript extensions register new tools, replace built-in ones (including all four defaults), add commands, keyboard shortcuts, custom UI components, event handlers, and sub-agent patterns. Third-party pi packages install via npm or git. The design goal is that you never need to fork Pi to shape it to your workflow.
- Supply-chain-hardened npm releasesPi pins direct dependencies to exact versions and ships npm-shrinkwrap.json with the published CLI to lock transitive deps for end users. A scheduled GitHub workflow runs npm audit plus npm audit signatures. The pre-commit hook blocks accidental lockfile changes, and release smoke tests run isolated installs before tagging. Dependency changes are treated as reviewed code changes.
- 104k GitHub stars and active communityThe earendil-works/pi repo has 104,849 stars and 13,158 forks since its August 2025 creation, with the count spanning repo renames from badlogic/pi-mono. The Discord community is active. The downstream oh-my-pi fork, which adds 60+ providers and 31 built-in tools, demonstrates the extension model working at scale.
Trade-offs
- -No built-in permission boundary by defaultPi runs with the full permissions of the launching user and process. There is no built-in system to restrict filesystem, network, credential, or process access. Unlike Claude Code, which ships permission prompts by default, Pi delegates isolation to the environment. For untrusted codebases or CI pipelines, you need to set up plain Docker, the Gondolin micro-VM extension, or OpenShell before running. This is a deliberate design choice but a real setup step for security-sensitive workflows.
- -MCP, sub-agents, and plan mode are not in the corePi deliberately omits MCP integration, sub-agent patterns, plan mode, built-in to-dos, and background bash. These are design decisions, not missing features; each can be added via TypeScript extensions or pi packages. For users who want these capabilities working out of the box without writing TypeScript, oh-my-pi (the batteries-included fork with 31 built-in tools and subagents) may be the better starting point.
- -Third-party pi packages run with full system accessPi packages (extensions, skills, prompts, and themes installable via npm or git) execute with full system access. Extensions run arbitrary TypeScript, and skills can instruct the model to perform any action including running executables. The README advises reviewing source code before installing third-party packages. Teams with strict security requirements should establish an approved package list before wide adoption.
Pi vs alternatives#
Pi vs Claude Code
Pi and Claude Code are both terminal coding agents that drive an LLM through a file-editing agent loop. The decision between them turns on how much control you want over the agent's behavior and extension points.
| Feature | Pi | Claude Code |
|---|---|---|
| License | MIT | Proprietary |
| Self-hosting | Yes (npm install) | No |
| Default tools | read, write, edit, bash | Proprietary set |
| Extension model | TypeScript extensions + pi packages | MCP servers |
| Permission prompts | None by default | Built-in |
| Plan mode | Extension / not built-in | Built-in |
| MCP support | Extension / not built-in | Built-in |
| Sub-agents | Extension / not built-in | Built-in |
| LLM providers | 30+ (any provider) | Anthropic-first |
| In-place session branching | Built-in (/tree) | Not built-in |
Pi is the stronger choice when you want to control and extend the agent loop itself. Its TypeScript extension API lets you add tools, replace built-in ones, build permission gates, wire in sub-agent patterns, and ship custom UI, all without forking the project. The MIT license and npm distribution mean you can audit, fork, and deploy it commercially without restriction.
Claude Code is the better choice when you want MCP integrations, plan mode, and permission prompts working out of the box without writing TypeScript. Claude Code also integrates tightly with Anthropic's tooling and subscription tiers, which matters for teams on Claude Pro or Max plans who want the lowest-friction setup.
The clearest difference is the security model. Claude Code ships permission prompts that ask before executing filesystem and shell operations. Pi runs with the full permissions of the launching user and has no built-in restriction layer. For most single-developer workflows on trusted code this is not a problem, but for teams running agents against unfamiliar codebases, Claude Code's default-cautious approach may be the safer starting point. Pi's containerization patterns (Docker, Gondolin, OpenShell) fill the same role but require explicit setup.
Quick start#
Install Pi from npm or via the curl setup script, then authenticate with an API key or provider login.
```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
curl -fsSL https://pi.dev/install.sh | sh
```What it's built on#
- Languages
- JavaScriptTypeScript
- Infrastructure
- AWS
- Tooling
- esbuild
FAQ#
Can Pi replace Claude Code as a coding agent?
Yes. Pi is a standalone coding agent with its own agent loop, four built-in tools (read, write, edit, bash), a TUI, and support for the Anthropic API, making it a genuine substitute for Claude Code. The honest tradeoffs: Pi ships without permission prompts, plan mode, MCP, or sub-agents by design. Claude Code provides those defaults out of the box; Pi expects you to add them via TypeScript extensions or pi packages if you need them. For developers who want to control and extend their agent loop, Pi is a direct alternative.
How does Pi differ from oh-my-pi?
Pi is the upstream minimal core: four default tools, no MCP or sub-agents in the core, extended via TypeScript extensions and pi packages. oh-my-pi (can1357/oh-my-pi) is a downstream fork that describes itself as 'everything you're missing' on top of Pi, adding 60+ providers, 31 built-in tools, LSP and DAP operations, sub-agents, and a Rust core. Pick Pi if you want a small, auditable base you extend yourself. Pick oh-my-pi if you want those features wired in without writing extensions.
Does Pi support local or offline LLM models?
Yes. Pi supports the llama.cpp router server natively: configure it with /login llama.cpp, manage downloaded models with /llama, and select loaded models with /model. For fully offline operation, set PI_OFFLINE=1 or pass --offline to disable update checks, package update checks, and install telemetry at startup.
Does Pi require an LLM API key, or can I use a subscription?
Both work. Pi supports Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro (Codex), and GitHub Copilot via subscription, authenticated with /login. Alternatively, bring an API key from any of 30+ supported providers including Anthropic, Google Gemini, DeepSeek, Azure OpenAI, xAI, OpenRouter, Mistral, Groq, and others.
Can Pi run in a container or sandbox for isolation?
Yes. Pi documents four containerization patterns: plain Docker (run the whole pi process in a container with your project mounted as a volume), the Gondolin extension (keep pi on the host and route built-in tool calls into a Linux micro-VM via QEMU, requires Node.js >= 23.6), OpenShell (policy-controlled sandbox with filesystem and network controls), and Docker Sandboxes via sbx (keeps provider credentials off the container via a proxy). Plain Docker and OpenShell are the broadest options; Gondolin and Docker Sandboxes offer more granular credential separation.
Similar open-source tools#
OpenCode
OpenCode is an open-source AI coding agent that assists developers in
Jean
A dev environment for running AI agents in isolated git worktrees
Omnara
Remote monitoring and control for Claude Code and Codex sessions.
fx
Native Zig CLI coding agent, 7.8 MiB, any AI model.
codex
OpenAI's terminal coding agent, Apache-2.0 licensed
kilocode
Open source AI coding agent. 500+ models at zero markup.