Mastering Pi: The Minimal Coding Agent That Adapts to You

Pi Is Not Another Claude Code

Most coding agents want you to adapt to them — learn their plan mode, their permission pop-ups, their sub-agents. Pi does the opposite.

Pi is a minimal terminal harness. Four tools by default: read, write, edit, bash. Everything else you add via TypeScript Extensions, Skills, Prompt Templates, and Themes. You shape Pi to your workflow, not the other way around.

Quick Start

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# or
curl -fsSL https://pi.dev/install.sh | sh

export ANTHROPIC_API_KEY=sk-ant-...
pi
# or use subscription
pi
/login  # pick Anthropic, OpenAI Codex, GitHub Copilot, Gemini, etc.

Then just talk. Pi ships with 30+ providers — Claude Pro/Max, ChatGPT Plus/Pro (Codex), Gemini, DeepSeek, Groq, Kimi, OpenRouter, Bedrock, Azure, and a local llama.cpp router.

1
2
3

pi --model openai/gpt-4o "Help me refactor"
pi --model sonnet:high "Solve this complex problem"
pi --provider kimi --model kimi-k2 "Review this PR"

Interactive Mode, Supercharged

Type / for commands, @ to attach files, !cmd to run bash and feed output to the model:

Command	What it does
`/model`	Switch models (Ctrl+L)
`/login` `/logout`	Manage credentials
`/resume` `/tree` `/fork` `/clone`	Session tree navigation
`/compact`	Manual context compaction
`/share`	Export as private Gist
`/skill:name`	Run a Skill

Queue while it thinks: Enter = steering, Alt+Enter = follow-up, Esc = abort. Configure steeringMode in settings.

Sessions are trees. JSONL stored in ~/.pi/agent/sessions/. Use /tree to jump to any point and branch in-place — all history preserved. Or pi -c to continue, pi -r to browse, pi --fork <id> to fork from CLI.

Why Pi Skips What Others Bake In

From the docs — Philosophy:

No MCP. Build CLI tools with READMEs, or add MCP via an Extension.
No sub-agents. Spawn pi via tmux, or build it as an Extension.
No permission pop-ups. Run in a container, or build your own gate.
No plan mode. Write plans to files, or build it.
No background bash. Use tmux.

This keeps the core minimal. You install what you need, nothing you don’t.

Extend Everything

Skills — On-Demand Capability Packs

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use when the user asks about X.
## Steps
1. Do this
2. Then that

Invoke via /skill:name or let the model auto-load. Place in ~/.pi/agent/skills/, .pi/skills/, or a Pi Package.

Extensions — TypeScript Power

export default function(pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (e, ctx) => { ... });
}

Add custom tools, sub-agents, plan mode, permission gates, status lines, git checkpointing, even Doom while you wait. Place in ~/.pi/agent/extensions/ or share via Pi Package.

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo@v1
pi list
pi update --all
pi config # enable/disable resources

Packages bundle extensions + skills + prompts + themes via package.json pi manifest. Auto-discovered from extensions/, skills/, prompts/, themes/.

Find them on npm (keywords:pi-package) or Discord.

Prompt Templates & Themes

Templates: Markdown in ~/.pi/agent/prompts/ → /templatename with {{focus}} variables
Themes: dark/light built-in, hot-reload, in ~/.pi/agent/themes/

Programmatic Use

SDK:

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime: await ModelRuntime.create(),
});
await session.prompt("What files are in the current directory?");

RPC for non-Node integrations:

1	pi --mode rpc # LF-delimited JSONL over stdin/stdout

Print mode for one-shots:

1 2	cat README.md \| pi -p "Summarize this" pi --tools read,grep,find,ls -p "Review the code" # read-only

Pro Tips

Trust: First run in a new repo asks to trust .pi/settings.json and project extensions. Use --approve / --no-approve to override, /trust to save decision.
Context: AGENTS.md / CLAUDE.md auto-loaded from ~/.pi/agent/ → parents → cwd. Override with AGENTS.override.md. Disable with --no-context-files.
System prompt: Replace via .pi/SYSTEM.md, append via APPEND_SYSTEM.md.
Env: PI_OFFLINE=1 disables all startup network calls. PI_CACHE_RETENTION=long for extended prompt cache.

Who Is Pi For?

If you want an opinionated workflow out of the box, use Claude Code. If you want a minimal core you can bend to your workflow — extensions for your stack, skills for your domain, themes for your taste — Pi is it.

Start minimal. Add what you need. Share what you build.

Docs: pi.dev | GitHub: earendil-works/pi-coding-agent | Discord: community invite on README