Why the Minimalist pi Coding Agent Beats Feature‑Heavy Claude Code and OpenCode

Core Philosophy: Primitives, Not Features

pi provides low‑level primitives (read, write, edit, bash) instead of built‑in features, allowing users to compose their own workflows.

Contrast with Other Agents

Other agents (Claude Code, Cursor, Windsurf) add built‑in sub‑agents, plan mode, MCP support, permission dialogs, backend Bash, and TODO management.

pi removes these built‑ins and replaces them with extensible mechanisms:

Sub‑agents → spawn via tmux or custom Extension

Plan mode → read/write a PLAN.md file

MCP → CLI tool + progressive README loading

Permission → YOLO default or custom Extension

Backend Bash → direct tmux usage

TODO → write a TODO.md file

System Prompt Size

Claude Code’s system prompt runs into tens of thousands of tokens; OpenAI Codex is similarly long. pi’s combined system prompt and tool definitions stay under 1,000 tokens.

You are an expert coding assistant. You help users with coding tasks by reading files, executing commands, editing code, and writing new files.

Available tools:
- read: Read file contents
- bash: Execute bash commands
- edit: Make surgical edits to files
- write: Create or overwrite files

Mario explains that modern RL‑trained LLMs already understand what a coding agent should do, so a short prompt suffices.

Why No MCP?

Playwright MCP defines 21 tools and consumes 13,700 tokens; Chrome DevTools MCP defines 26 tools and consumes 18,000 tokens, occupying 7‑9% of the context window before any work begins, while most tools are never used.

CLI‑Based Alternative

Wrap functionality as a CLI tool.

Attach a README.md to each tool.

Agent reads the README only when needed (progressive disclosure).

Invoke tools via bash.

Benefits include on‑demand token loading, composability via pipelines, easy extensibility, and token efficiency.

Mario maintains the repository github.com/badlogic/agent-tools, a collection of simple CLI tools for pi.

YOLO By Default: Security Perspective

pi runs in a fully YOLO mode—no filesystem restrictions, no bash checks, no permission dialogs. Mario states, "If your agent can write and execute code, it’s basically game over. Most other agents’ safety measures are just security theater." He also cites Simon Willison’s dual‑LLM pattern as a flawed solution.

Recommendation: run pi inside a container if security is a concern.

Multi‑Model Support

pi supports over 15 providers and hundreds of models, including Anthropic, OpenAI, Google, Azure, AWS Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi, MiniMax, OpenRouter, Ollama, and more.

Switch models mid‑session with /model or Ctrl+L; cycle saved models with Ctrl+P.

Unified LLM API (pi‑ai)

pi‑ai normalizes four major APIs: OpenAI Completions, OpenAI Responses, Anthropic Messages, and Google Generative AI. Mario notes quirks such as missing store fields in Cerebras/xAI, token field differences in Mistral, and lack of streaming in Google.

Tree‑Structured Session History

/tree

visualizes all branches.

Navigate to any node to continue a conversation.

All branches live in a single file; bookmarks are supported. /export saves as HTML. /share uploads to GitHub Gist and returns a shareable link.

This enables exploring multiple paths without losing context.

Extension System (TypeScript)

Extensions are TypeScript modules that can access tools, commands, keyboard shortcuts, the event system, and a full TUI.

Examples of what extensions can do:

Custom sub‑agents

Plan mode

Permission gating

Path protection

SSH remote execution

Sandboxing

Run Doom inside the terminal 🎮

Install extensions with:

$ pi install npm:@foo/pi-tools
$ pi install git:github.com/badlogic/pi-doom

Version locking ( @1.2.3), batch updates ( pi update), and test‑without‑install ( pi -e git:...) are supported.

Four Runtime Modes

Interactive TUI.

Print/JSON mode: pi -p "query" or --mode json for script integration.

RPC mode: JSON protocol over stdin/stdout for non‑Node.js integration.

SDK mode: embed pi in your own application.

clawdbot is a real‑world Slack bot built with the SDK mode.

Benchmark Results: Minimalism Wins

Mario ran Claude Opus 4.5 on Terminal‑Bench 2.0 (five runs per task) against Codex, Cursor, Windsurf, etc. The leaderboard shows pi outperforming almost all competitors.

The Terminal‑Bench team’s own minimal agent, Terminus 2 , also performed strongly with only a tmux session and no extra tools, reinforcing the claim that a minimalist approach can match complex solutions.

Context Engineering

AGENTS.md : project‑level instruction file loaded from ~/.pi/agent/ upward.

SYSTEM.md : replace or augment the default system prompt.

Compaction : automatic summarization of old messages, fully customizable via extensions.

Skills : on‑demand capability packs with progressive disclosure.

Prompt Templates : reusable Markdown prompts invoked with /name.

Dynamic Context : extensions can inject messages, filter history, implement RAG, or build long‑term memory before each turn.

Runtime Interaction Controls

Enter

: send a turn‑changing message immediately, interrupting ongoing tool calls. Alt+Enter: queue a message to be sent after the current task finishes.

This lets users steer the agent in real time without waiting for the full workflow to complete.

Why Build Your Own Stack?

Mario cites Armin Ronacher’s blog: building on top of provider SDKs gives full control and a smaller surface area. pi‑ai is already used in seven production projects and offers request abort (including tool calls), partial results, browser‑environment execution, and type‑safe model definitions.

Installation and Getting Started

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

Run pi in a project directory to start an interactive session.

References

[1] Tens of thousands of tokens: https://cchistory.mariozechner.at

[2] Blog post on MCP omission: https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/

[3] Agent tools repository: https://github.com/badlogic/agent-tools

[4] Dual LLM pattern discussion: https://simonwillison.net/2023/Apr/25/dual-llm-pattern/

[5] Sub‑agent example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/subagent/

[6] Plan mode example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/plan-mode/

[7] Permission gate example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/permission-gate.ts

[8] Path protection example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/protected-paths.ts

[9] SSH remote execution example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/ssh.ts

[10] Sandbox example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/sandbox/

[11] Doom overlay example: https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/doom-overlay/

[12] clawdbot repository: https://github.com/clawdbot/clawdbot

[13] Terminal‑Bench 2.0 repository: https://github.com/laude-institute/terminal-bench

[14] Blog post on agent complexity: https://lucumr.pocoo.org/2025/11/21/agents-are-hard/