Table of Contents
DEVELOPER TOOLS ·
AI ·
CLI

Pi.dev: A Minimal Terminal Coding Harness

Pi.dev: A Minimal Terminal Coding Harness
Table of Contents

Introduction

Pi is a minimal terminal coding harness: an environment where you steer an LLM with a small set of core primitives—reading files, editing them, and running shell commands—while everything fancier arrives through extensions, skills, prompt templates, and themes. The project positions itself as something you adapt to your workflows rather than a sealed product that dictates how you work.

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.

Why “minimal” is intentional

Many coding agents ship with bundled planners, sub-agents, MCP integrations, permission dialogs, and background processes. Pi deliberately omits several of those so the core stays small; if you want them, you extend the harness or install a Pi package from npm or git (installation examples show pi install npm:… and pi install git:…).

That philosophy shows up in the docs as trade-offs you opt into: for example, no built-in MCP—you can add MCP via an extension if you need it, following the project’s argument that not every workflow requires the protocol (background). Similarly, no built-in sub-agents, no permission popups, no plan mode, no built-in to-do list, and no background bash are documented as gaps you fill with files (TODO.md), containers, tmux, or TypeScript extensions.

Models and providers

Pi advertises 15+ providers and hundreds of models—Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding, MiniMax, OpenRouter, Ollama, and others—with authentication via API keys or OAuth. You can switch models mid-session (/model or Ctrl+L) and cycle favorites (Ctrl+P). Custom providers and models can be wired through models.json or extensions.

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 — project instructions loaded from ~/.pi/agent/, parent directories, and the working directory.
  • SYSTEM.md — replace or augment the default system prompt per project.
  • 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

Pi runs in four modes, which matters if you script or embed it:

  1. Interactive — full TUI.
  2. Print / JSON — e.g. pi -p "query" for scripts, --mode json for event streams.
  3. RPC — JSON over stdin/stdout for non-Node integrations (rpc.md).
  4. SDK — embed Pi in applications; OpenClaw is cited as a real-world integration.

Steering while the agent works

The UI distinguishes steering from follow-up: Enter sends a steering message (delivered after the current tool and interrupting remaining tools), while Alt+Enter queues a follow-up that waits until the current turn finishes.

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.

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