Pi Coding Agent: What It Is and How to Set It Up

Pi keeps showing up in “which harness do you use” threads on X next to Claude Code, Codex, and OpenCode. Pi 1.0 shipped on October 1, 2026, and version 1.3.0 followed on October 15. If you’ve only used Claude Code, Pi is worth understanding because it takes the opposite approach: it ships small, and you build the rest.

This guide covers what Pi is, how to install it, how to connect a model, how to customize it, and where it differs from Claude Code. Everything here comes from the Pi repository, the Pi docs, and the Pi changelog.

What Pi is

The README describes Pi as “a minimal, extensible agent harness that you can make your own.” In practice it is a terminal coding agent. You run pi in a folder, give it a task, and it reads files, runs shell commands, and edits code there.

A few facts to anchor it:

• Open source, MIT license. The code started as Mario Zechner’s pi-mono repository. The old badlogic/pi-mono address now redirects to earendil-works/pi.
• A monorepo of libraries. The CLI (@earendil-works/pi-coding-agent) sits on top of a unified multi-provider LLM API (pi-ai), an agent runtime (pi-agent-core), and a terminal UI library (pi-tui). You can use those pieces to build your own agent.
• Four ways to run it. Interactive terminal UI, print or JSON mode for scripts, RPC over stdin and stdout, and a TypeScript SDK.
• Small by design. Pi “ships with powerful defaults but skips features like sub-agents and plan mode.” The idea is that you ask Pi to build what you want, or install a package that does it your way.

That last point is the whole pitch. Claude Code gives you one opinionated workflow. Pi gives you a small core and a plugin system.

How to install Pi

On macOS or Linux, the official installer pins all dependencies and lets you update later with pi update:

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

On Windows, in PowerShell:

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

If you prefer npm, Pi needs Node.js 22.19 or newer:

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

The docs point out that the npm route doesn’t pin transitive dependencies, which is why they recommend the installer. Nix users can run nix profile add github:earendil-works/pi/stable. Check the install with:

pi --version

Connect a model

Pi doesn’t come with a model. You bring one, in one of three ways:

• A subscription or account. Run /login inside Pi and pick a provider. Pi walks you through the OAuth or API key flow and saves the credential in ~/.pi/agent/auth.json.
• An API key in the environment. Set the provider’s variable before starting Pi, for example ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, or OPENROUTER_API_KEY. The providers page lists the rest.
• A local model. Pi integrates with the llama.cpp router, managed with the /llama command.

Then pick a model with /model (or Ctrl+L) and a reasoning level with /thinking (or Shift+Tab). Ctrl+P cycles through your available models. Pi’s model catalog lists providers, context limits, and pricing.

Keep auth.json private. It can hold API keys and OAuth tokens.

Your first session

Start Pi in the folder you want it to work in:

cd /path/to/project
pi

Type a task and press Enter. A few things work differently from what you might expect:

Sessions save automatically as JSONL files. They form a tree, so you can go back to an earlier message and branch from it with /tree, /fork, or /clone without losing the original path. /compact shrinks the history sent to the model, and /export saves a session as HTML or JSONL.

Give Pi instructions with AGENTS.md

Pi loads context files from its agent directory (~/.pi/agent/), from your working folder, and from the folders above it. It reads AGENTS.md, and also CLAUDE.md, so a project already set up for Claude Code gives Pi the same instructions without changes. An AGENTS.override.md replaces the AGENTS.md in the same folder.

If you’ve written a CLAUDE.md before, the advice from our slash commands and memory guide carries over: short, specific rules beat long essays.

Customize Pi

This is where Pi earns the “make it yours” line. The quickstart suggests starting with the least powerful option that does the job:

Prompt templates are Markdown files. Save this as ~/.pi/agent/prompts/review.md and you get a /review command:

---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.

Skills follow the Agent Skills specification, the same SKILL.md format covered in our skills and subagents guide. Pi lists each skill’s name and description in the system prompt and loads the full instructions only when a task needs them. Put skills in ~/.pi/agent/skills/, .pi/skills/, or the shared ~/.agents/skills/ and .agents/skills/ folders. Force one with /skill:name.

Extensions are TypeScript modules that run inside the Pi process. This one, from the docs, adds a /hello command:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Show a greeting",
    handler: async (name, ctx) => {
      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
    },
  });
}

Save it in ~/.pi/agent/extensions/ or try it once with pi --extension ./hello.ts. Extensions can register tools, commands, shortcuts, providers, and terminal UI, so subagents, plan mode, or a permission gate can all be built this way.

Pi packages bundle extensions, skills, templates, and themes for sharing through npm or git:

pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1

Browse what others have published on pi.dev/packages. An extension or package runs with your user’s permissions and can read your files and credentials, so review the source before you install one.

Add MCP servers

Pi used to leave MCP out of the core. Current versions connect to MCP servers over stdio or streamable HTTP:

pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list

Servers you add go to ~/.pi/agent/mcp.json by default. Add --local to write .pi/mcp.json in the project instead, which Pi reads only after you trust the project. Inside a session, /mcp shows connections and handles sign-in. The config format matches other MCP clients, so a server you set up for Claude Code (see our MCP guide) moves over with little change.

Run Pi safely

This is the part to read twice. Pi’s security page is direct: Pi “does not ask for approval before every tool call,” and it has no built-in permission system for files, processes, network, or credentials. It runs with the permissions of the account that started it.

Project trust is the one guard at startup. When you open a folder, Pi can ask whether you trust it before loading that project’s settings, extensions, and packages. That stops a cloned repo from silently running its own extension code. It does not limit what tool calls can do once you start working.

For anything unattended or untrusted, the docs describe three ways to isolate Pi:

• Gondolin extension: Pi and your provider login stay on the host, while built-in tools and ! commands run in a local Linux micro-VM.
• Plain Docker: the whole pi process runs in a container.
• OpenShell: the whole process runs in a policy-controlled sandbox.

If you work on a repo where main deploys straight to production, the same advice from our auto mode guide applies with more force here. Pi won’t stop to ask before git push, so use a sandbox, branch protection, or an extension that asks first.

Pi vs Claude Code

Both are terminal agents that edit code in your repo. The differences are in what ships by default:

Pick Claude Code if you mainly use Claude models and want guardrails and features like subagents and hooks working on day one.

Pick Pi if you want to switch between providers or run local models, you want to read and change how your agent works, or you prefer a small core you grow yourself.

You don’t have to pick one. Pi reads your existing CLAUDE.md and skills, so trying it on a side project costs little. If you want to run Pi and Claude Code side by side on the same task, Orca can launch each one in its own git worktree.

If you want more in the box: Oh My Pi

Not everyone wants to build their own subagents. Oh My Pi (omp) is a fork of Pi that takes the opposite bet and ships subagents, LSP, a debugger, browser control, and much more by default. Same roots, very different philosophy. Our Oh My Pi guide covers what it adds.

Sources

• earendil-works/pi on GitHub (README, docs, and changelog)
• pi.dev, the official site and docs
• @earendil-works/pi-coding-agent on npm