Pi: The Open-Source AI Coding Agent You Probably Haven't Tried Yet

The open-source AI coding agent pi, from the earendil-works project on GitHub, has surpassed 46,000 stars and offers a terminal-based assistant that reads files, writes code, runs shell commands, and iterates on tasks within a user's project directory. Built entirely in TypeScript and distributed as npm packages, the tool can be installed in under five minutes with a single command and supports authentication via subscription login or API keys for providers including Anthropic, OpenAI, Google, and GitHub Copilot. Pi automatically loads project-specific instructions from `AGENTS.md` or `CLAUDE.md` files, saves session history for resuming or forking conversations, and can operate in non-interactive mode for scripting and automation.

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 https://github.com/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 interfaces Prerequisites: 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 or yarn global add @earendil-works/pi-coding-agent or 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: Project Instructions - 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: js 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 |