Pi Coding Agent — The Adaptable Terminal Harness

🛠️ Terminal Coding Agent

Pi

The minimal, aggressively extensible coding harness that adapts to your workflow — not the other way around.

Write extensions in TypeScript. Share them as packages. Shape Pi to fit how you work.

30+

Providers

4

Run Modes

∞

Extensible

💡 Core Concept

What Makes Pi Different?

🧩

Minimal Core, Maximum Power

By default, Pi gives the model just 4 tools: read, write, edit, and bash. Add what you need — nothing you don't.

⚡

TypeScript Extensions

Register custom tools, slash commands, keyboard shortcuts, event hooks, and even custom UI components — all without forking Pi.

📦

Pi Packages

Bundle extensions, skills, prompts & themes. Share via npm or git. Install with one command:

pi install npm:@foo/pi-tools

🌳

Session Branching

Explore solutions in parallel. Navigate a full tree of conversation branches — all in one file. Fork, clone, compact.

🎨

Fully Themed TUI

Hot-reload themes, custom keybindings, and a rich terminal UI with message queuing, steering, and model cycling.

🔌

SDK & RPC Mode

Embed Pi in your own Node.js apps, or integrate over stdin/stdout JSONL. Pi adapts to your stack.

⚔️ Comparison

Pi vs Claude Code — The Honest Breakdown

Dimension	Claude Code	Pi
Providers	Anthropic only	30+ providers including Anthropic, OpenAI, Google, Groq, Mistral, local LLMs via llama.cpp
Extensibility	MCP servers, hooks	TypeScript Extensions — custom tools, commands, UI, sub-agents, compaction, games (Doom!)
Session Model	Linear history	Tree branching — fork, clone, navigate branches in-place. All in one JSONL file.
Run Modes	Interactive + print	4 modes: Interactive, Print, JSON streams, RPC (process integration)
SDK	Limited	Full Node.js SDK — embed Pi sessions in your own apps
Message Flow	Blocking	Steering + follow-up queue — send messages while agent works
Package system	—	Pi Packages — share extensions, skills, themes via npm/git
Context control	Compaction	Compaction + configurable logic + custom summaries via extensions
Local models	—	llama.cpp router server — download, load, run local LLMs with /llama
Trust model	Permissions	Project trust + extensions — no popups, build your own flow

Pi doesn't try to be Claude Code. It lets you build whatever Claude Code is — your way.

🔄 Run Modes

Four Ways to Run Pi

💬

Interactive TUI

Full terminal UI with slash commands, model cycling, tree navigation, message queuing, and hot-reload themes.

📄

Print Mode -p

Non-interactive one-shot: get a response and exit. Pipes stdin into the prompt. Perfect for scripts.

📡

JSON Stream --mode json

Outputs all events as structured JSON lines. Ideal for logging, analysis, or external tooling.

🔌

RPC Mode --mode rpc

Strict LF-delimited JSONL over stdin/stdout. Integrate Pi with any language: Python, Rust, Go, etc.

📦 SDK

createAgentSession()
Embed Pi directly in Node.js apps. Used by openclaw.

🔧 Extensibility

Extensions: The Real Superpower

export default function myExtension(pi: ExtensionAPI) {
  // Custom tools
  pi.registerTool({ name: "deploy", ... });

  // Slash commands
  pi.registerCommand("deploy", { ... });

  // Event hooks
  pi.on("tool_call", async (event, ctx) => { ... });

  // Custom UI
  pi.setEditor(myEditor);
  pi.setFooter("⚙️ Ready");

  // Permission gates, MCP, git hooks...
}
      

🛠️ Custom tools (or replace built-in ones)

🤖 Sub-agents & plan mode

📦 Custom compaction strategies

🔐 Permission gates & path protection

🎮 Custom editors & UI components

💾 Git checkpointing & auto-commit

🔒 SSH & sandbox execution

🔗 MCP server integration

🎨 Make Pi look like Claude Code

👾 Games while waiting (yes, Doom runs)

Place in ~/.pi/agent/extensions/ or bundle into a Pi Package.

📋 Skills & Prompts

Reusable Intelligence

🧠 Agent Skills

On-demand capability packages following the Agent Skills standard. The model loads them automatically when needed.

<!-- ~/.pi/agent/skills/docker/SKILL.md -->
# Docker Skill
Use when the user asks about containers.

## Steps
1. Check Dockerfile best practices
2. Verify multi-stage builds
3. Audit for security issues
        

Invoke: /skill:docker

📝 Prompt Templates

Reusable Markdown prompts with variable placeholders. Expand with a slash command.

<!-- ~/.pi/agent/prompts/review.md -->
Review this code for bugs, security issues,
and performance problems.
Focus on: {{focus}}
        

Invoke: /review focus=authentication

💡 Skills auto-discover from ~/.pi/agent/skills/, .pi/skills/, or Pi Packages. No configuration needed.

🌐 Providers

30+

Providers & Models — One Interface

Switch models mid-session. Mix subscription logins with API keys. Pi keeps provider-specific quirks out of your way.

Anthropic OpenAI Google Gemini GitHub Copilot DeepSeek Mistral Groq Cerebras xAI Amazon Bedrock Azure OpenAI NVIDIA NIM OpenRouter Hugging Face Fireworks Together AI Vercel AI Gateway Cloudflare AI Kimi For Coding MiniMax Xiaomi MiMo Ant Ling ZAI Coding OpenCode Zen/Go 🦙 llama.cpp

Subscriptions

Claude Pro/Max, ChatGPT Plus/Pro, Copilot

API Keys

25+ providers via env vars or /login

Local

llama.cpp router, download & manage from TUI

Custom

Add providers via JSON or TypeScript extensions

🌳 Sessions

Sessions: Branch, Fork, Compact

🌲 Tree Navigation

Every conversation is a tree. Jump to any point, branch into new directions, switch between branches — all in a single JSONL file.

/tree

🍴 Fork & Clone

Fork: create a new session from any past message. Open the selector, pick a point, and continue with a clean file.

/fork

Clone: duplicate the active branch into a new session at the current position. Keep all history.

/clone

🗜️ Compaction

Long sessions? Automatic or manual compaction summarizes older messages, keeps recent context intact. Full history preserved in the JSONL — revisit anytime via /tree.

/compact /compact "focus on tests"

📤 Share & Export

Share sessions as private GitHub gists with shareable HTML links. Export to HTML or JSONL. Import and resume from exported sessions.

/share /export session.html

🧠 Philosophy

What Pi Deliberately Doesn't Do

Pi's philosophy: aggressively extensible so it doesn't dictate your workflow. Features baked into other tools are built your way.

❌ No MCP

✔️ Build CLI tools with READMEs (see Skills), or build an extension that adds MCP support.

❌ No Sub-agents

✔️ Spawn Pi instances via tmux, build your own with extensions, or install a package.

❌ No Permission Popups

✔️ Run in a container, or build your own confirmation flow with extensions.

❌ No Plan Mode

✔️ Write plans to files, build it with extensions, or install a package that does.

❌ No Built-in To-Dos

✔️ Use a TODO.md file, or build your own with extensions. The model understands markdown checklists.

❌ No Background Bash

✔️ Use tmux for full observability and direct interaction.

Pi doesn't say "trust our defaults." It says "build what you need."

🚀 Start Now

Get Started in 30 Seconds

1

Install

One command, zero fuss.

npm i -g @earendil-works/pi-coding-agent

2

Authenticate

API key or subscription login.

export ANTHROPIC_API_KEY=... pi → /login

3

Code

Just talk to Pi.

pi "Build me an API"

🌐 pi.dev

npm 📦 Discord 💬 OpenClaw (SDK example)

If you use Claude Code, try Pi. You'll keep Claude Code for Anthropic-only workflows —
and reach for Pi when you need flexibility, extensibility, and control.