If you've been following the AI coding agent space, you've likely heard of Claude Code, GitHub Copilot, or Codex. But there's a fast-moving open-source alternative sitting at over 46,000 GitHub stars that deserves a serious look: pi, from earendil-works/pi.
This article walks you through what pi actually is, how to get it running in under five minutes, and whether it's worth adding to your workflow.
Pi is a monorepo of tools built for constructing and running AI agents. The centerpiece is a coding agent CLI — a terminal-based assistant that can read your files, write code, run shell commands, and iterate on tasks, all within your actual project directory.
The repo is built entirely in TypeScript and ships as a set of npm packages:
@earendil-works/pi-coding-agent
— the interactive CLI you'll use day to day@earendil-works/pi-agent-core
— the agent runtime (tool calling, state management) for building your own agents@earendil-works/pi-ai
— a unified LLM API layer that normalizes OpenAI, Anthropic, Google, and others behind one interface@earendil-works/pi-tui
— a terminal UI library with differential rendering@earendil-works/pi-web-ui
— web components for AI chat interfacesPrerequisites: Node.js installed, and an API key or existing subscription (Claude Pro, ChatGPT Plus, or GitHub Copilot).
npm install -g @earendil-works/pi-coding-agent
That's the whole install. No Docker, no Python environment, no build step.
If you prefer another package manager:
pnpm add -g @earendil-works/pi-coding-agent
yarn global add @earendil-works/pi-coding-agent
bun add -g @earendil-works/pi-coding-agent
Pi supports two authentication paths.
Option A — Subscription login (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot):
Start pi from any directory and run:
pi
/login
A prompt will appear to select your provider. This stores credentials in ~/.pi/agent/auth.json
.
Option B — API key:
export ANTHROPIC_API_KEY=sk-ant-...
pi
You can use OPENAI_API_KEY
, GOOGLE_API_KEY
, or others the same way. The /login
command can also store API keys interactively so you don't need to export them every session.
Navigate to your project and launch:
cd /path/to/your/project
pi
Pi starts in interactive mode and loads your project directory as its working context. Type a request and press Enter:
Summarize this repository and tell me how to run its checks.
Out of the box, the agent has access to four tools: read
(read files), write
(create or overwrite files), edit
(patch files), and bash
(run shell commands). Additional read-only tools like grep
, find
, and ls
are available through tool options.
Pi loads AGENTS.md
(or CLAUDE.md
) files at startup to give the model project-specific instructions. You can have a global one in ~/.pi/agent/AGENTS.md
and a per-project one in your repo root. Example:
- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.
Run /reload
inside a session to pick up changes without restarting.
Type @
in the editor to fuzzy-search and reference files, or pass them on the command line:
pi @src/app.ts @src/app.test.ts "Review these together"
You can paste images with Ctrl+V (Alt+V on Windows) or drag them into supported terminals.
Sessions are saved automatically. Resuming is straightforward:
pi -c # Continue most recent session
pi -r # Browse previous sessions
Inside a session, /fork
and /clone
let you branch the conversation tree — useful when you want to try two different approaches to a problem without losing your current state.
Pi works well in scripts and pipelines:
pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"
For automation, --mode json
gives structured event output and --mode rpc
allows stdin/stdout process integration.
Prefix a command with !
to run it and send the output to the model:
!npm run lint
Use !!command
to run it without adding the output to the model's context window.
Use /model
or Ctrl+L to change models mid-session. Shift+Tab cycles thinking levels. This is useful if you want a fast cheap model for exploration and a smarter one for final implementation.
If you're building something on top of pi rather than using it as a CLI, the SDK path is clean:
import {
AuthStorage,
createAgentSession,
ModelRegistry,
SessionManager,
} from "@earendil-works/pi-coding-agent";
const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);
const { session } = await createAgentSession({
sessionManager: SessionManager.inMemory(),
authStorage,
modelRegistry,
});
await session.prompt("What files are in the current directory?");
For non-Node.js integrations, pi supports RPC mode over stdin/stdout with JSONL framing — so you can integrate from any language.
If you want to contribute or run from source:
git clone https://github.com/earendil-works/pi.git
cd pi
npm install # Install all dependencies
npm run build # Build all packages
npm run check # Lint, format, and type check
./pi-test.sh # Run pi from sources (any directory)
Note: npm run check
requires a prior npm run build
because the web-ui package needs compiled .d.ts
files from dependencies.
Yes, with some caveats.
Pi earns attention for a few concrete reasons:
It's genuinely multi-provider. Most coding agents are tied to one model provider. Pi normalizes across OpenAI, Anthropic, Google, and others at the API layer, so you can switch without re-learning a tool. If you already pay for Claude Pro or GitHub Copilot, pi can use those subscriptions directly — no extra API costs by default.
The session model is well-designed. Branching, forking, and resuming sessions is something most similar tools handle poorly. Pi treats this as a first-class feature, which matters when you're doing long iterative work.
The extensibility story is solid. Extensions are TypeScript modules that can add tools, slash commands, event handlers, and custom UI. If the built-in tools don't cover your workflow, you can add to them.
Where it's less compelling: The terminal UI won't appeal to everyone, and if you're deeply embedded in VS Code with Copilot already working, the switching cost is real. The documentation is good but spread across many individual files in the repo — there's no single polished docs site yet.
For developers who want control over their AI tooling, prefer the terminal, or need to build agents programmatically rather than just use them interactively, pi is a serious option. It's the kind of tool that rewards spending an hour with it.
| Task | Command |
|---|---|
| Install | npm install -g @earendil-works/pi-coding-agent |
| Start in project | cd /project && pi |
| Login (subscription) | |
/login inside pi |
|
| Set API key | export ANTHROPIC_API_KEY=... |
| Continue last session | pi -c |
| Browse sessions | pi -r |
| One-shot prompt | pi -p "your prompt" |
| Switch model | |
/model or Ctrl+L |
|
| Run shell command | !your-command |
| Reload context files | /reload |
| Uninstall | npm uninstall -g @earendil-works/pi-coding-agent |