Pi Coding Agent

Pi is an open-source, minimal terminal coding agent by Mario Zechner. Four built-in tools (read, write, edit, bash), a sub-1000-token system prompt, and a TypeScript extension system. Everything else is user-configured.

Install

volta install @mariozechner/pi-coding-agent

Authentication

OAuth (subscription-based)

pi
/login
# Select provider: Anthropic, OpenAI, GitHub Copilot, Google Gemini, etc.

API Keys

export ANTHROPIC_API_KEY=sk-ant-...
pi

Supported providers: Anthropic, OpenAI, Azure OpenAI, Google Gemini, Google Vertex, Amazon Bedrock, Mistral, Groq, Cerebras, xAI, OpenRouter, Hugging Face, and any OpenAI-compatible endpoint.

Configuration

~/.pi/agent/             # Global config
  settings.json          # Global settings
  AGENTS.md              # Global agent instructions
  SYSTEM.md              # Override default system prompt
  APPEND_SYSTEM.md       # Append to system prompt
  models.json            # Custom providers/models
  sessions/              # Auto-saved sessions
  prompts/               # Prompt templates (slash commands)
  skills/                # Global skills
  extensions/            # Global extensions
  themes/                # Custom themes

.pi/                     # Project-local (overrides global)
  settings.json
  AGENTS.md
  SYSTEM.md, APPEND_SYSTEM.md
  prompts/, skills/, extensions/, themes/

Pi loads AGENTS.md from cwd and all parent directories plus ~/.pi/agent/AGENTS.md. All matching files are concatenated and injected as context.

CLI

pi                           # Interactive session
pi -c                        # Continue most recent session
pi -r                        # Browse and select past sessions
pi --no-session              # Ephemeral (nothing saved)
pi --print "prompt"          # Non-interactive, print and exit
pi --mode rpc                # RPC mode (stdin/stdout JSONL)
pi --tools read              # Restrict to read-only tools
pi -e extensions/my-ext.ts   # Load extension(s)
pi @file1.ts @file2.md "prompt"  # Attach files and prompt

Slash Commands

Command	Action
/login	OAuth authentication
/model	Switch model
/scoped-models	Enable/disable models for cycling
/settings	Configure options
/resume	Select previous session
/new	Start fresh session
/fork	Branch from current point
/tree	Navigate session history tree
/compact	Compress context manually
/copy	Copy last assistant message
/export	Export session as HTML
/reload	Refresh extensions, skills, prompts

Custom prompt templates are also slash commands (e.g., /review for prompts/review.md).

Keyboard Shortcuts

Key	Action
Ctrl+C	Clear editor (twice to quit)
Escape	Cancel/abort (twice for /tree)
Ctrl+L	Model selector
Ctrl+P / Shift+Ctrl+P	Cycle models forward/backward
Shift+Tab	Cycle thinking level
Enter (while working)	Queue steering message
Alt+Enter	Queue follow-up message
@ in editor	Fuzzy file search
!command	Run shell, send output to LLM

Extensions

TypeScript modules that hook into Pi's lifecycle:

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "deploy",
    description: "Deploy the application",
    parameters: { env: { type: "string" } },
    execute: async ({ env }) => { /* ... */ },
  });

  pi.on("tool_call", async (event, ctx) => {
    // intercept, log, or gate tool calls
  });
}

Load with pi -e extensions/my-ext.ts. Extensions can register tools, slash commands, keyboard shortcuts, event handlers, and UI elements across 30+ lifecycle events (session, input, tool, bash, agent, message, context).

Packages

Bundle and share extensions, skills, prompts, and themes:

pi install npm:@foo/pi-tools        # From npm
pi install git:github.com/user/repo # From git
pi list                             # Show installed
pi update                           # Update all
pi remove npm:@foo/pi-tools         # Uninstall

Key Differences from Claude Code

• System prompt: ~1000 tokens, user-replaceable vs ~10,000+ opaque
• Tools: 4 built-in + extensions vs many built-in + hooks
• Permissions: None by default vs permission dialogs
• MCP: Not built-in (use CLI tools instead) vs built-in
• Sessions: Tree-structured with branching vs linear
• License: MIT open source vs proprietary

Pi's strength is control — you see and configure everything that reaches the model. The trade-off is more setup work for capabilities other tools include out of the box.