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

Pi coding agent cover

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:

Terminal
curl -fsSL https://pi.dev/install.sh | sh

On Windows:

PowerShell
powershell -c "irm https://pi.dev/install.ps1 | iex"

With npm:

Terminal
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

The 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:

Terminal
pi update

Starting Pi and signing in

Open your project folder and run pi:

Terminal
cd /path/to/project
pi

To 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. /tree jumps back to an earlier point and branches from it, /export writes HTML and /share uploads 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:

Terminal
pi install npm:@foo/pi-tools

Where 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
Print 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.

Build it with us in Stride AI Academy

Four courses, weekly live calls and a community of people building and selling AI. Or start with 320+ free guides.

Keep reading

Free AI Coding guides