Pi Agent: The Minimal Coding Agent vs Claude Code
Pi agent explained: the open-source minimal coding agent, how to install it, models and logins, extensions and skills, and how it compares with Claude Code.
Josh Pocock7 min read
AI Coding
Pi coding agent
Stride AI Academy
Pi is an open-source, minimal coding agent you run in the terminal. It ships with a small core, works with many model providers, and leaves out features like subagents and plan mode on purpose, so you add what you need with extensions, skills and packages. It's MIT licensed, and you install it with one command or from npm as @earendil-works/pi-coding-agent.
This guide covers what the Pi agent is, how to install and start it, which models it supports, how you extend it, and how it compares with Claude Code. Everything here was checked against the Pi repo on GitHub, the coding agent package, pi.dev and the Pi docs on providers, configuration and how Pi works on November 22, 2026. If you searched "pi agent" for Raspberry Pi or a chatbot, this isn't that Pi.
What the Pi agent is
The Pi repo calls itself a toolkit for AI agents: a unified LLM API, an agent loop, a terminal UI and a coding agent CLI. It's a monorepo with several packages, including:
| Package | What it is |
|---|---|
@earendil-works/pi-coding-agent |
The pi coding agent CLI |
@earendil-works/pi-ai |
The unified LLM API |
@earendil-works/pi-agent-core |
The agent loop |
@earendil-works/pi-tui |
The terminal UI |
The coding agent's README calls Pi a minimal, extensible agent harness you can make your own. It says Pi ships with strong defaults but skips features like subagents and plan mode, and suggests you either ask Pi to build what you want or install a package that does it.
How to install Pi
On macOS or Linux:
curl -fsSL https://pi.dev/install.sh | shOn Windows:
powershell -c "irm https://pi.dev/install.ps1 | iex"With npm:
npm install -g --ignore-scripts @earendil-works/pi-coding-agentThe README notes that the npm route doesn't pin transitive dependencies, unlike the installer, and that Pi needs Node.js 22.19 or newer. If you used the installer, update with:
pi updateStarting Pi and signing in
Open your project folder and run pi:
cd /path/to/project
piTo connect a model, run /login inside Pi. The README says this connects a subscription or an API key for a built-in provider. The providers docs say most hosted providers support browser or device-flow OAuth, an API key, or both, and that /login [provider] shows what a given provider supports. You can also set keys as environment variables, such as ANTHROPIC_API_KEY or OPENAI_API_KEY.
/login saves credentials in auth.json in the agent folder. The docs warn that this file can hold API keys and OAuth tokens, so keep it private and never commit it.
Which models Pi supports
Per pi.dev, Pi works with Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding, MiniMax, NVIDIA, OpenRouter, Ollama and more. You can add custom providers and models through models.json or an extension.
You can switch models mid-session with /model or Ctrl+L, and cycle through favourites with Ctrl+P.
If you want to use Claude models through a Claude plan rather than an API key, read Anthropic's Claude Code legal and compliance page first. It says plan sign-in is intended for Claude Code and Anthropic's own apps, and that developers building products should use API keys. Pi's docs don't name which subscriptions /login supports, so check /login yourself and the provider's terms.
Pi's minimal design
Pi keeps the core small and moves everything else into add-ons. A few choices stand out:
- No subagents or plan mode built in. The README says Pi skips them. You add them with an extension or package if you want them.
- No permission popups. pi.dev says Pi doesn't ask before each action. Instead, you run it in a container or build your own confirmation flow with an extension. The how-it-works docs say enabled tools run with the operating-system permissions of the Pi process.
- MCP support. pi.dev says MCP is built in, with a Codemode feature that lets agents compose tool calls in a JavaScript sandbox, and MCP extensions are also supported.
- Sessions as trees. Sessions are stored as trees in one file.
/treejumps back to an earlier point and branches from it,/exportwrites HTML and/shareuploads to a GitHub gist. - Automatic compaction. Older messages are summarised as you near the context limit.
That design suits people who want to know exactly what their agent does and shape it themselves. It means more setup than an agent that ships with everything on.
Extending Pi: extensions, skills, prompts and packages
Pi has four kinds of customisation, plus packages to share them.
Extensions are TypeScript modules loaded into the Pi process. Per the how-it-works docs, they can register tools, commands, shortcuts, providers, event handlers, renderers and terminal UI, and can add instructions or transform context. Because they run inside Pi, only install ones you trust.
Skills give on-demand instructions and supporting files, loaded when needed.
Prompt templates expand when you type /name.
Themes change how the terminal UI looks.
Pi packages bundle any of these and install from npm or git:
pi install npm:@foo/pi-toolsWhere Pi keeps its files
From the configuration docs:
| What | User level | Project level |
|---|---|---|
| Config folder | ~/.pi/agent |
.pi |
| Skills | ~/.pi/agent/skills/ |
.pi/skills/ |
| Extensions | ~/.pi/agent/extensions/ |
.pi/extensions/ |
| Prompt templates | ~/.pi/agent/prompts/ |
.pi/prompts/ |
| Themes | ~/.pi/agent/themes/ |
.pi/themes/ |
You can move the user folder with the PI_CODING_AGENT_DIR environment variable. Project config in .pi loads only after you trust the project.
For instructions, Pi looks for AGENTS.override.md, AGENTS.md or CLAUDE.md in the agent folder, and also loads context files from your working folder and its parents. pi.dev adds that a SYSTEM.md can replace or append to the system prompt per project. The configuration docs don't say whether Pi reads .claude/skills, so if you're bringing Claude Code skills over, copy them into .pi/skills/.
Ways to run Pi
Pi isn't only an interactive terminal app. Per pi.dev:
| Mode | How |
|---|---|
| Interactive | pi |
pi -p |
|
| JSON | --mode json |
| RPC | JSON over stdin and stdout |
| SDK | The Pi TypeScript SDK, to run Pi inside your own app |
While Pi works, Enter sends a steering message after the current tool, and Alt+Enter queues a follow-up for when it finishes.
Pi vs Claude Code
| Pi | Claude Code | |
|---|---|---|
| Source | Open source, MIT | Anthropic's product |
| Models | Many providers | Claude models |
| How you pay | Your provider's rates | Claude Pro and up, or API key |
| Subagents | Not built in, add with extensions | Built in |
| Plan mode | Not built in | Built in |
| Permissions | No popups; use a container or extension | Permission prompts and modes |
| Extending | TypeScript extensions, skills, prompts, packages | Skills, hooks, plugins, MCP |
| Instructions | AGENTS.md, CLAUDE.md, SYSTEM.md |
CLAUDE.md |
The Claude Code column is from Anthropic's permission modes docs, which list modes from default to plan and bypassPermissions and cover subagents. Our guide to Claude Code plan mode goes deeper. Claude Code comes with Claude Pro at $20 a month or higher plans, per Claude's pricing page. See how much Claude Code costs for every plan.
Choose Pi if you want a small agent you control, use several model providers, or want to build your own workflow on its SDK or RPC mode.
Choose Claude Code if you want subagents, plan mode and permission controls ready on day one, and want your Claude plan to cover the usage.
Comparing more tools? See the best AI coding agents, Claude Code vs Codex and Claude Code vs OpenCode.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
What is the Pi agent?
Pi is an open-source coding agent CLI from the earendil-works/pi repo on GitHub. It's a minimal, extensible agent harness that works with many model providers. It's MIT licensed.
How do I install the Pi coding agent?
Run curl -fsSL https://pi.dev/install.sh | sh on macOS or Linux, or the PowerShell installer on Windows. You can also run npm install -g --ignore-scripts @earendil-works/pi-coding-agent. Pi needs Node.js 22.19 or newer.
Is Pi free?
The Pi agent is free and open source under the MIT license. You pay whichever model provider you connect, at that provider's rates.
Does Pi support MCP?
pi.dev says MCP is built in, and that MCP extensions are also supported. It also has a Codemode feature that lets the agent compose tool calls in a JavaScript sandbox.
Is Pi better than Claude Code?
It depends on what you want. Pi gives you a small, open agent and many providers, but you add features like subagents yourself. Claude Code ships those features and works with your Claude plan.