Pi Agent: Minimal AI Harness for Model-Agnostic Coding with Token Control

The author evaluates Pi Agent after testing multiple coding agents including Claude Code, Codex, OpenCode, and Kimi Code. While those agents offer complete out-of-the-box tooling (Plan, Todo, Subagent, Web Search, MCP, Skills, LSP, Permission, Context Management), switching between them disrupts personal workflow stability because each enforces its own preset working style.

What Is Pi Agent?

Pi Agent is not just a coding CLI; it is an extensible Agent Runtime with a minimal four-layer core: pi-ai: Handles model providers, supporting most mainstream coding subscriptions (Anthropic, Codex, Kimi, xAI) and API keys (OpenCode, DeepSeek). pi-agent-core: Manages the Agent Loop, Messages, Tools, and State. pi-coding-agent: Adds coding capabilities on top of the core. pi-tui: Provides the terminal interaction UI.

Default tools are only read, write, edit, bash; grep, find, ls are built-in but opt-in. Features like Web Search, Subagents, Permission, Plan, Todo, MCP are deliberately excluded from core — not because they are unfinished, but as an architectural choice. The author quotes: "Bash itself can call many mature dev tools. Dedicated tools provide structured I/O, making model invocation easier and reducing shell command errors. But more tools do not directly mean better coding results."

Installation and Base Configuration

Install via: curl -fsSL https://pi.dev/install.sh | sh Run pi to enter the TUI. Use /login to add subscription accounts or API keys (Anthropic, Codex, Kimi, xAI, OpenCode, DeepSeek). Use /scoped-models to enable only needed models, avoiding a cluttered selector. In ~/.pi/agent/settings.json, extend defaultTools to include the three optional built-ins:

{
  "defaultTools": [
    "read",
    "bash",
    "edit",
    "write",
    "grep",
    "find",
    "ls"
  ]
}

Extension Configuration

Pi distinguishes Prompt Templates (what to do) from Skills (how to do it). Core customization mechanisms fall into four categories: System Prompt, Prompt Templates, Skills, and Extensions. The official extension marketplace hosts many packages; the author recommends a minimal set: pi-web-access (required): provides web search capability. @gotgenes/pi-permission-system (required): adds a security sandbox; Pi defaults to fully open, especially bash running in the current user environment. pi-open-tui (optional): improves terminal UI without changing coding ability. @gotgenes/pi-subagents or pi-subagents (optional): two design philosophies — one dispatches workers from a main agent and aggregates results; the other spawns specialized agents for different scenarios (multi-agent style).

Permission Blacklist Configuration

To avoid excessive approval prompts, the author configures a deny-list in settings.json:

{
  "permission": {
    "*": "allow",
    "path": {
      "*": "allow",
      "*.env*": "deny",
      "*.env.example": "allow"
    },
    "bash": {
      "*": "allow",
      "git commit*": "ask",
      "git push*": "ask",
      "pnpm dev*": "ask",
      "*gradlew*bootRun*": "ask",
      "sudo *": "ask",
      "rm -rf *": "deny",
      "git push --force*": "deny"
    },
    "external_directory": {
      "*": "ask",
      "/Users/eric/CodeBase/XymProjects/xym-skills/*": "allow"
    }
  }
}

Advantages Over Other Coding Agents

No fixed harness lock-in : Switch models freely; keep your own Skills, rules, and workflows. Achieves agent-agnostic, model-swappable, user-controlled workflows.

Strong models perform better without heavy agent logic : Many tasks need only a few tools plus codebase context. The author compared Codex CLI and Pi both using GPT 5.6 Sol High for SDD document generation: Pi was much faster, quality was comparable, but token consumption dropped dramatically.

Token and context cost control : Vendors are cutting subscription quotas and raising prices. Pi's minimal core avoids loading large amounts of useless built-in context. Long-context tasks suffer from two issues: (a) frequent context compression loses core project context (exemplified by Codex); (b) price doubling after context thresholds (e.g., Grok Build CLI > 200K tokens).

Decoupled models, quotas, and harness : Same model/subscription can be used across Pi, OpenCode, Hermes, etc., without re-purchasing API access.

The author concludes: "You switch to Pi not because it has more features than Claude Code / Codex / OpenCode, but because it finally decouples 'model, harness, skills, permissions, subagents' so you decide what the agent looks like."

Evaluation Criteria

Run agents in parallel and compare on actual tasks:

Completion quality

Stability

Context usage

Token consumption

Manual rework required

Not on who has the longer feature list.

Closing Thought

Pi Agent is quick to adopt and easy to extend with plugins. The viable path may be: codebase (context) + strong model + minimal harness.