Pi.dev: A Minimal Terminal Coding Harness

Pi.dev: A Minimal Terminal Coding Harness

Introduction

Pi is a minimal terminal coding harness: the shipped built-in tools are read, bash, edit, write, grep, find, and ls (CLI reference), with heavier behavior layered through extensions, skills, prompt templates, themes, and Pi packages. The project treats the core as something you adapt rather than a sealed product.

Pi is open source (MIT), with documentation at pi.dev/docs/latest and the coding-agent package developed in the monorepo under earendil-works/pi. This article summarizes what Pi offers on the website today and why that design matters.

When you steer where shell commands land—OCI images, Lima guests, LXC, Firecracker-class isolation—our AI coding devbox ladder post names the kernel boundary without replacing Pi’s harness story.

Why “minimal” is intentional

Many coding agents ship with bundled planners, sub-agents, MCP integrations, permission dialogs, and background processes. Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages; install shared setups with Pi packages (pi install npm:…, pi install git:… per the CLI reference).

The Design principles section of the docs states explicitly that Pi does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash—you add those via extensions or packages, or rely on external tools (containers, tmux, a TODO.md on disk, etc.). That section also links a longer essay for narrative context; the no-built-in-MCP claim is stated in Pi’s own documentation, not only in external commentary.

Models and providers

Per Providers, Pi supports subscription OAuth (e.g. ChatGPT Codex, Claude Pro/Max, GitHub Copilot) and a long list of API-key-backed and cloud providers—Anthropic, OpenAI, Google Gemini, Azure OpenAI, Amazon Bedrock, Mistral, Groq, Cerebras, xAI, OpenRouter, Hugging Face, Kimi For Coding, MiniMax, Together, Fireworks, Cloudflare gateways, and others—with credential resolution documented there. The installable model catalog is updated with each Pi release. Mid-session switching uses /model or Ctrl+L; Ctrl+P cycles a scoped favorites list (/scoped-models). Ollama, LM Studio, vLLM, and similar are typically wired through models.json and/or custom providers.

Sessions as trees

Conversation history is stored as a tree, not a flat chat log. The /tree command navigates to earlier points so you can branch from them; branches live in one file. You can filter by message type, bookmark entries, export to HTML (/export), or share via GitHub gist (/share) for a renderable URL—see Pi’s example session.

Context engineering

Pi emphasizes control over what enters the context window:

  • AGENTS.md / CLAUDE.md — project instructions loaded from ~/.pi/agent/, parent directories, and the working directory (context files).
  • SYSTEM.md / APPEND_SYSTEM.md — replace the default system prompt, or append to it, via .pi/ / ~/.pi/agent/ (system prompt files).
  • Compaction — automatically summarizes older messages as limits approach; customizable via extensions (topic-based or code-aware summaries, different summarizer models).
  • Skills — capability bundles (instructions + tools) loaded on demand for progressive disclosure.
  • Prompt templates — Markdown snippets invoked with /name.
  • Dynamic context — extensions can inject pre-turn messages, filter history, implement RAG, or add long-term memory.

The default system prompt is kept minimal by design (source).

Modes of operation

The CLI “Modes” table defines non-interactive and structured output entry points:

  1. Interactive (default) — full TUI.
  2. Print — -p / --print: one-shot reply and exit; can pipe stdin into the prompt.
  3. JSON — --mode json: newline-delimited JSON events (JSON mode).
  4. RPC — --mode rpc: JSONL over stdin/stdout (RPC mode).

Separately, --export [out] writes a session to HTML without driving the interactive UI. Embedding is not another --mode flag: the SDK exposes createAgentSession and related APIs from @earendil-works/pi-coding-agent for Node integrations (examples). openclaw/openclaw is one downstream project that embeds the agent for messaging-style UIs.

Steering while the agent works

The message queue behavior is: Enter queues a steering message (delivered after the current assistant turn finishes executing its tool calls), Alt+Enter queues a follow-up (delivered after the agent finishes all work), Escape aborts and restores queued text to the editor, and Alt+Up pulls queued messages back into the editor. Delivery timing is configurable via steeringMode / followUpMode in settings.

Extensions as the real surface area

Extensions are TypeScript modules with access to tools, commands, keyboard shortcuts, events, and the full TUI. The repo lists 50+ extension examples, and Pi encourages self-modification: have the agent adjust its own setup, hit /reload, and continue—or publish what you built as a package.

When Pi might fit your stack

Pi is a strong match when you want:

  • A hackable terminal agent whose behavior you own via code and config.
  • Predictable primitives with optional complexity layered on.
  • Heavy provider flexibility and mid-session model switching.
  • Branching, exportable sessions for debugging or sharing reviews.

It is less ideal if you expect every enterprise-grade convenience (MCP, sub-agents, plan mode, permission UX) to ship in the box without installing or writing extensions.

Related on this site: Archon turns agent steps into reviewed YAML workflows; Varlock separates checked-in @env-spec from plaintext secrets—useful beside minimal harness prompts; cmux multiplexes parallel agent terminals on macOS; Terax is the GUI-heavy alternative framing when “terminal” includes editor and preview chrome. dev-ore devbox documents Lima golden disks and disposable clones when Pi’s bash tool should run inside a VM, not on the host.

Learn more

Pi’s pitch is consistent: change the harness, not your workflow—and treat pi.dev as the hub for that ecosystem of packages, docs, and examples.

Featured Posts