Pi is the open-source AI agent toolkit from the earendil-works team, a TypeScript monorepo under MIT. As of late July 2026 it sits at 79,473 stars, 9,769 forks, ranking #9 on GitHub's weekly trending list. The repo was created on August 9, 2025-less than a year to reach this size-and the latest release is v0.82.1, still pre-1.0 and moving fast. What it does in one sentence: hand you a complete toolchain from a unified LLM API, an agent runtime, a terminal UI, to an interactive coding agent-and it's "self extensible," meaning the agent can expand its own capability boundary. The core is four npm packages: @earendil-works/pi-ai (unified multi-provider LLM API), @earendil-works/pi-agent-core (agent runtime with tool calling and state management), @earendil-works/pi-tui (terminal UI library with differential rendering), and @earendil-works/pi-coding-agent (the interactive coding agent CLI, the flagship).
What Pain It Solves
Anyone trying to ship an AI agent has hit these: supporting multiple LLM providers means wrapping each SDK separately-OpenAI here, Anthropic there, Google over there, with different signatures, so swapping models means rewriting the call layer; an agent isn't a single LLM call, it has to call tools, hold state, and push a task across many turns, and building that loop from scratch usually ends with you discovering state management is a black hole; giving the agent a decent terminal UI means wrestling with terminal rendering, input handling, and refresh logic yourself; and finally, landing a real coding agent means dealing with permissions, containerization, and extensibility-all pits. Pi splits these into four independently usable packages: pi-ai for the model layer, pi-agent-core for the runtime, pi-tui for the interface, and pi-coding-agent that composes the first three into a usable coding agent. The positioning is "building blocks for your own agent, plus an out-of-the-box flagship"-not "yet another black-box CLI."
Unified LLM API: One Interface Across OpenAI/Anthropic/Google
The base layer is @earendil-works/pi-ai. It's a unified multi-provider LLM API that puts OpenAI, Anthropic, Google, and others behind one interface. Direct consequence: your agent code isn't locked to one vendor-run Claude today, swap to GPT tomorrow, switch to Gemini the day after, without touching the call layer. For agent developers the value is that benchmarking, fallback, and cost control no longer need three parallel provider adapters. The package ships on npm as @earendil-works/pi-ai. Note the README describes it as "Unified multi-provider LLM API" without publishing exact method signatures or the full provider list (the "etc." implies more than three); to confirm coverage you check the provider model data inside the package, which npm run build refreshes.
Agent Runtime: Tool Calling + State Management
One layer up is @earendil-works/pi-agent-core, the agent runtime. README positions it as "Agent runtime with tool calling and state management"-two things: tool calling, so the LLM can invoke external tools (read files, run commands, hit APIs) rather than just emit text; and state management, so across multi-turn conversations and tool calls the state holds, letting the agent break a long task into steps instead of amnesia every turn. This is the line that separates an "LLM wrapper" from an "agent": the former calls the model once and returns, the latter loops, remembers, and reaches into the outside world. Pi's entire agent capability, including the coding agent below, runs on this runtime. If you want to build your own agent rather than use the ready-made coding agent, this package is the entry point.
TUI: A Terminal UI Library with Differential Rendering
The third package is @earendil-works/pi-tui, a terminal UI library whose selling point is differential rendering-redraw only the screen regions that changed, not the full frame. In a terminal app that means fast refresh, minimal flicker, and the ability to hold up under complex interfaces. It's not for end users; it's for developers who want to give their agent a proper terminal interface. Pi's own coding agent interactive surface is built on top of it. If your agent needs streaming output, tool-call progress, and scrollable history, pi-tui saves you from writing curses/Ink from scratch.
Coding Agent CLI: The Self-Extensible Command Line
The flagship is @earendil-works/pi-coding-agent, which the README stresses is a "self extensible coding agent." Meaning the agent's capability boundary isn't fixed; it can be extended. It ships on npm; install it and you get the pi command, run interactively. The README also mentions the ! command family as a built-in tool entry point, plus pi update --self for self-updates. On permissions the README is blunt: Pi has no built-in permission system and by default runs with the permissions of the user and process that launched it-anything you can touch, it can touch. For harder isolation the team offers three containerization patterns: the Gondolin extension (routes built-in tools and ! commands into a local Linux micro-VM, keeping provider auth on the host), plain Docker (the whole pi process in a container), and OpenShell (a policy-controlled sandbox). For a coding agent that reads and writes files and runs commands, you must think this permission model through before production.
Three-Minute Setup
# 1. Install (needs Node + npm)
npm install -g @earendil-works/pi-coding-agent
# 2. Configure a provider key (pick one)
export OPENAI_API_KEY=sk-... # or ANTHROPIC_API_KEY / GOOGLE_API_KEY
# 3. Minimal runnable
pi # launch the interactive coding agent, give orders in natural language
# Run from source (in the repo): ./pi-test.sh, can be run from any directoryYou can also use just one package: npm install @earendil-works/pi-ai for the unified LLM API alone, or @earendil-works/pi-agent-core for the runtime alone-the four packages are independently usable. For official demos and docs go to pi.dev, with documentation at pi.dev/docs/latest; the README also notes "you can ask the agent to explain itself."
Who It's For + Five Pitfalls
For: developers building their own AI agent who don't want to write provider adapters and agent loops from scratch; people who want an open-source, model-swappable, self-extensible coding agent instead of a closed-source one; developers who want agent interactivity in the terminal and want to skip the TUI plumbing; teams that need to drop a coding agent into a containerized pipeline and care about isolation.
Five pitfalls. One, no permission system: by default it runs as your user and can read/write anything you can; for production you must containerize-of the three official paths, Gondolin keeps auth on the host, Docker is the simplest, OpenShell suits policy-controlled scenarios. Two, pre-1.0 (v0.82.1): APIs are still moving, read the changelog before upgrading, don't blindly pi update --self. Three, issues and PRs from new contributors are auto-closed by default and reviewed daily; to contribute, read CONTRIBUTING.md first-don't open a PR cold and get bounced. Four, "self extensible" plus "no permissions" means the agent can change its own behavior and touch your files; review what a task will do before running it, don't let it run blind on untrusted input. Five, it's a TypeScript/npm ecosystem-Python/Rust teams need to install the Node toolchain first, this isn't pip install and done.
vs. the Competition
Against Claude Code: Claude Code is Anthropic's closed-source CLI, locked to Claude models, polished and ready out of the box; Pi is MIT-licensed, swaps providers via pi-ai, and is self-extensible, positioned as "building blocks plus a modifiable flagship agent." Pick Pi for control and modifiability, Claude Code for turnkey convenience. Against Codex (OpenAI) the same logic holds: closed-source, locked to OpenAI models, while Pi gives you provider freedom and source. Against Aider: Aider is an open-source git pair-programming tool, written in Python, focused on code editing inside the git workflow; Pi is a TypeScript agent harness (LLM API + runtime + TUI + coding CLI) with a broader scope than git editing, plus the self-extensible-agent angle. Pi's differentiator is that it isn't a single agent-it's a whole set of composable blocks plus a self-extensible flagship. You can take just pi-ai to swap models for your own agent, or run pi-coding-agent out of the box.
References
- Pi GitHub repo (79,473 stars, MIT, TypeScript): https://github.com/earendil-works/pi
- Official site and docs (demos + pi.dev/docs/latest): https://pi.dev
- npm package @earendil-works/pi-coding-agent: https://www.npmjs.com/package/@earendil-works/pi-coding-agent
- Containerization patterns (Gondolin / Docker / OpenShell): https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/containerization.md
- Pi RFCs (long-term plans): https://rfc.earendil.com/keyword/pi/
- Discord community: https://discord.com/invite/3cU7Bz4UPx