Pi Coding Agent: A Guide to This Minimal Terminal Coding Tool

Hello there! If you’re on the hunt for a terminal-based coding assistant that helps with code management, command execution, and flexible customization to fit your workflow, Pi Coding Agent might just be what you need. It’s a streamlined terminal coding harness designed to let you adapt it to your processes, rather than forcing you to change how you work. In this post, I’ll walk you through what Pi is, how to get started, and its key features. Let’s address some common questions you might have, like “What is Pi Coding Agent?” or “How do I install and begin using it?”

Pi serves as a minimal terminal coding framework, allowing you to interact with language models for coding tasks. It comes with basic tools out of the box, such as reading files, writing files, editing code, and running bash commands. What stands out is its extensibility—you can create TypeScript extensions, skills, prompt templates, and themes to tailor it. Pi operates in four modes: interactive, print or JSON output, RPC for process integration, and an SDK for embedding into your applications.

Imagine you’re a developer wondering how Pi can assist. Essentially, it enables models to access your file system, run commands, and respond to your instructions. By default, it equips the model with four tools: read, write, edit, and bash. The model leverages these to handle your requests. For additional capabilities, incorporate skills or extensions.

How to Quick Start Pi Coding Agent?

If you’re eager to dive in, here’s a straightforward guide to installation and launch. It takes just a few minutes.

1. Open your terminal.
2. Run this command to install Pi globally:

   npm install -g @mariozechner/pi-coding-agent
   

3. Set up an API key, such as for Anthropic:

   export ANTHROPIC_API_KEY=sk-ant-...
   

   Then start with:

   pi
   

   Or, if you have a subscription:

   pi
   /login  # Then select the provider
   

Once installed, you can chat with Pi directly. For instance, say “List all files in the current directory,” and Pi will use its tools to process and respond. Platform notes: For Windows, Termux on Android, or terminal/shell alias setups, check the relevant docs, but we’ll focus on the essentials here.

Why is this quick start so simple? Pi’s design prioritizes minimalism, avoiding time sinks on setup. It loads default tools right away, letting you get to work immediately.

(This is Pi’s logo—clean and simple, reflecting the tool’s minimalist vibe.)

Which Providers and Models Does Pi Support?

You might be asking, “What AI models can Pi use?” Pi supports a variety of providers and models to give you options that suit your needs. Each built-in provider includes a list of tool-capable models, updated with every release.

Providers Authenticated via Subscriptions:

• Anthropic Claude Pro/Max
• OpenAI ChatGPT Plus/Pro (Codex)
• GitHub Copilot
• Google Gemini CLI
• Google Antigravity

Providers Authenticated via API Keys:

• Anthropic
• OpenAI
• Azure OpenAI
• Google Gemini
• Google Vertex
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI
• OpenCode Zen
• Hugging Face
• Kimi For Coding
• MiniMax

To switch models, use the /model command or press Ctrl+L to open the selector. Pi maintains these model lists for easy selection.

For custom providers or models, edit ~/.pi/agent/models.json if they support OpenAI, Anthropic, or Google APIs. For custom APIs or OAuth, use extensions. This flexibility means you’re not limited to the defaults.

For example, if you’re using OpenAI’s GPT-4o and want to know how to set it up: Set your API key first, then run pi --provider openai --model gpt-4o "Help me refactor code". This directly engages the specified model.

How Does Pi’s Interactive Mode Work?

Interactive mode is Pi’s most common use case, where you converse with the model in your terminal. The interface flows from top to bottom: startup header, messages area, editor, and footer.

• Startup Header: Displays shortcuts (use /hotkeys for the full list), loaded AGENTS.md files, prompt templates, skills, and extensions.
• Messages Area: Your inputs, assistant replies, tool calls and results, notifications, errors, and extension UIs.
• Editor: Where you type; the border color shows the thinking level.
• Footer: Shows working directory, session name, total tokens/cache usage, cost, context usage, and current model.

(This screenshot of interactive mode illustrates how messages appear, with the editor at the bottom.)

Editor Features

The editor is your main input zone. How does it function?

• Type @ for fuzzy searching project files.
• Tab completes paths.
• Shift+Enter (or Ctrl+Enter on Windows Terminal) for multi-line input.
• Ctrl+V to paste images, or drag them into the terminal.
• !command runs a bash command and sends output to the LLM; !!command runs it without sending.

Standard editing keys like word delete and undo are supported.

Command List

Type / in the editor to trigger commands. Extensions can add custom ones, skills via /skill:name, and prompt templates expand with /templatename.

Here’s a table of common commands:

Command	Description
/login, /logout	OAuth authentication
/model	Switch models
/scoped-models	Enable/disable models for Ctrl+P cycling
/settings	Adjust thinking level, theme, message delivery, transport
/resume	Select from previous sessions
/new	Start a new session
/name <name>	Set session display name
/session	Show session info (path, tokens, cost)
/tree	Jump to any point in the session and continue
/fork	Create a new session from the current branch
/compact [prompt]	Manually compact context, with optional custom instructions
/copy	Copy the last assistant message to clipboard
/export [file]	Export session to HTML file
/share	Upload as a private GitHub gist with shareable HTML link
/reload	Reload extensions, skills, prompts, context files (themes hot-reload automatically)
/hotkeys	Show all keyboard shortcuts
/changelog	Display version history
/quit, /exit	Quit Pi

These commands make interactions more efficient. For sharing a session, /share generates a link quickly.

Keyboard Shortcuts

A table of commonly used shortcuts:

Key	Action
Ctrl+C	Clear editor
Ctrl+C twice	Quit
Escape	Cancel/abort
Escape twice	Open /tree
Ctrl+L	Open model selector
Ctrl+P / Shift+Ctrl+P	Cycle scoped models forward/backward
Shift+Tab	Cycle thinking level
Ctrl+O	Collapse/expand tool output
Ctrl+T	Collapse/expand thinking blocks

Customize them in ~/.pi/agent/keybindings.json.

Message Queue

Submit messages while the agent processes:

• Enter: Queues a steering message, delivered after current tool execution (interrupts remaining tools).
• Alt+Enter: Queues a follow-up message, delivered only after the agent completes all work.
• Escape: Aborts and restores queued messages to the editor.
• Alt+Up: Retrieves queued messages back to the editor.

Configure delivery in settings: steeringMode and followUpMode can be “one-at-a-time” (default, responds one by one) or “all” (delivers all at once). transport selects “sse”, “websocket”, or “auto”.

Interactive mode feels like chatting with a smart assistant—you input, it thinks, then acts with tools.

How Does Pi’s Session System Manage History?

Sessions keep context in Pi. Stored as JSONL files with a tree structure, each entry has an id and parentId, allowing in-place branching without new files.

Managing Sessions

Sessions auto-save to ~/.pi/agent/sessions/, organized by working directory.

Commands:

• pi -c: Continue the most recent session.
• pi -r: Browse and select past sessions.
• pi --no-session: Ephemeral mode (no saving).
• pi --session <path>: Use a specific session file or ID.

Branching

Use /tree to navigate the session tree. Select any prior point and branch from there. All history stays in one file.

(This tree view screenshot helps visualize branching.)

• Type to search, page with ←/→.
• Ctrl+O toggles filter modes: default → no-tools → user-only → labeled-only → all.
• Press l to label entries as bookmarks.

With /fork, create a new session file from the current branch. It opens a selector, copies history to the selected point, and places the message in the editor for editing.

Compaction

Long sessions can exceed context windows. Compaction summarizes older messages while preserving recent ones.

• Manual: /compact or /compact <custom instructions>.
• Automatic: Enabled by default. Triggers on context overflow (recovers and retries) or nearing limits (proactive). Configure via /settings or settings.json.

Compaction is lossy, but full history remains in the JSONL file. Use /tree to revisit. Customize with extensions.

The session system makes Pi ideal for long-term projects, allowing experimentation via branches without losing history.

How to Adjust Pi’s Settings?

Settings control Pi’s behavior. Use /settings for common tweaks, or edit JSON files directly.

Location table:

Location	Scope
~/.pi/agent/settings.json	Global (all projects)
.pi/settings.json	Project (overrides global)

Options cover thinking levels, themes, message delivery, and more. This lets you fine-tune Pi to your preferences.

What Role Do Context Files Play in Pi?

Pi loads AGENTS.md (or CLAUDE.md) at startup from:

• ~/.pi/agent/AGENTS.md (global)
• Parent directories (up from cwd)
• Current directory

These hold project instructions, conventions, and common commands. Matching files are concatenated.

System Prompt

Replace the default with .pi/SYSTEM.md (project) or ~/.pi/agent/SYSTEM.md (global). Append without replacing via APPEND_SYSTEM.md.

Context files ensure the model understands your project background, improving response accuracy.

How to Customize Pi?

Customization is at Pi’s heart. Add prompt templates, skills, extensions, and themes—even package them for sharing.

Prompt Templates

Reusable Markdown prompts. Type /name to expand.

Example:

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

Place in ~/.pi/agent/prompts/, .pi/prompts/, or a Pi package.

Skills

On-demand capability packs following the Agent Skills standard. Invoke with /skill:name or auto-load.

Example:

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

## Steps
1. Do this
2. Then that

Place in ~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, .agents/skills/, or a Pi package.

Extensions

TypeScript modules that extend Pi with custom tools, commands, shortcuts, event handlers, and UI components.

Example:

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

Possibilities: Custom tools, sub-agents, plan mode, custom compaction, permission gates, custom editors, Git checkpointing, SSH, MCP integration, games (like Doom), and more.

(This Doom extension screenshot—yes, you can play games while waiting!)

Place in ~/.pi/agent/extensions/, .pi/extensions/, or a Pi package.

Themes

Built-ins: dark, light. Themes hot-reload: Edit the active file, and Pi applies changes instantly.

Place in ~/.pi/agent/themes/, .pi/themes/, or a Pi package.

Pi Packages

Bundle and share extensions, skills, prompts, and themes via npm or git. Find packages on npmjs.com or Discord.

Security note: Pi packages have full system access. Review source code before installing third-party ones.

Installation commands:

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi remove npm:@foo/pi-tools
pi list
pi update
pi config  # Enable/disable

Use -l for project-local installs. To create a package: Add a pi key to package.json, or use conventional directories.

Customization lets Pi adapt to you, not vice versa. Build sub-agents, plan modes, and more without forking the core.

What Are Pi’s Programmatic Usage Options?

Beyond interactive use, Pi offers SDK and RPC modes.

SDK

Embed with TypeScript:

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: new AuthStorage(),
  modelRegistry: new ModelRegistry(authStorage),
});

await session.prompt("What files are in the current directory?");

RPC Mode

For non-Node.js integrations, use stdin/stdout:

pi --mode rpc

Programmatic options integrate Pi into your apps or scripts seamlessly.

What Is Pi’s Design Philosophy?

Pi emphasizes extensibility without dictating workflows. Features like sub-agents or plan modes can be built via extensions, skills, or packages, keeping the core lean.

No MCP: Use CLI tools with READMEs, or build an extension for MCP support.

No sub-agents: Spawn Pi instances with tmux, or create your own.

No permission popups: Run in a container, or implement confirmations.

No plan mode: Write plans to files, or build it.

No built-in to-dos: Use a TODO.md, or create your own.

No background bash: Use tmux for full observability and interaction.

This philosophy keeps Pi flexible, empowering you to build what you need.

Pi’s CLI Reference

Command:

pi [options] [@files...] [messages...]

Package Commands

pi install <source> [-l]
pi remove <source> [-l]
pi update [source]
pi list
pi config

Modes

• Default: Interactive
• -p, --print: Print response and exit
• --mode json: Output events as JSON lines
• --mode rpc: RPC mode
• --export <in> [out]: Export session to HTML

Model Options

Option	Description
--provider <name>	Provider
--model <pattern>	Model pattern or ID (supports provider/id and optional :<thinking>)
--api-key <key>	API key
--thinking <level>	off, minimal, low, medium, high, xhigh
--models <patterns>	Comma-separated patterns for Ctrl+P cycling
--list-models [search]	List available models

Session Options

Option	Description
-c, --continue	Continue recent session
-r, --resume	Browse and select session
--session <path>	Specific session
--session-dir <dir>	Custom session directory
--no-session	Ephemeral mode

Tool Options

Option	Description
--tools <list>	Enable built-in tools (default: read,bash,edit,write)
--no-tools	Disable all built-in tools

Built-in tools: read, bash, edit, write, grep, find, ls

Resource Options

Option	Description
-e, --extension <source>	Load extension (repeatable)
--no-extensions	Disable extension discovery
--skill <path>	Load skill (repeatable)
--no-skills	Disable skill discovery
--prompt-template <path>	Load prompt template (repeatable)
--no-prompt-templates	Disable prompt template discovery
--theme <path>	Load theme (repeatable)
--no-themes	Disable theme discovery

Other Options

Option	Description
--system-prompt <text>	Replace default prompt
--append-system-prompt <text>	Append to system prompt
--verbose	Force verbose startup
-h, --help	Show help
-v, --version	Show version

File arguments: Prefix with @ to include, e.g., pi @prompt.md "Answer this".

Examples:

• pi "List all .ts files in src/"
• pi -p "Summarize this codebase"
• pi --model openai/gpt-4o "Help me refactor"
• pi --models "claude-*,gpt-4o"
• pi --tools read,grep,find,ls -p "Review the code"
• pi --thinking high "Solve this complex problem"

Environment Variables:

Variable	Description
PI_CODING_AGENT_DIR	Override config directory (default: ~/.pi/agent)
PI_PACKAGE_DIR	Override package directory
PI_SKIP_VERSION_CHECK	Skip startup version check
PI_CACHE_RETENTION	Set to long for extended prompt cache
VISUAL, EDITOR	External editor for Ctrl+G

FAQ

Is Pi Coding Agent Suitable for Beginners?

Yes, if you have a college background in programming, it’s accessible. Defaults are powerful; extensions suit advanced users.

How to Handle Long Sessions?

Use compaction: manual or automatic. Tree view simplifies branching.

Is Pi Free?

Pi is MIT-licensed and free, but models require subscriptions or API keys, which may incur costs.

Can I Build Custom Tools with Pi?

Absolutely, register tools via extensions. Examples include deployment tools or stats commands.

Does Pi Support Images?

Yes, paste with Ctrl+V in the editor or process via tools.

How to Share Pi Packages?

Publish on npm with a pi key in package.json, or via git.

Why Does Pi’s Philosophy Emphasize Extensions?

It wants you to control your workflow, not bake in everything. For instance, no built-in sub-agents—you can build your own with extensions.

I hope this guide helps you grasp Pi. If you have specifics, like “How to use extensions for Doom?”, it’s a fun example showing extension potential: Register a tool to run the game while the agent thinks. Pi makes coding engaging, doesn’t it? Let me know your thoughts if you give it a try! (Word count: approximately 4,200)