Why Pi-mono Powers OpenClaw: A Minimalist AI Coding Assistant

From Copy‑Paste to Minimalism

Zechner’s workflow progressed from manually copying code into ChatGPT, through Copilot (which he never used effectively), to Cursor, and finally to a daily set of assistants (Claude Code, Codex, Amp, Droid, opencode) that grew increasingly complex and disruptive.

Four‑Tool Philosophy

read   # read file contents (text or image), optional line range
write  # create new file or fully overwrite, auto‑create directories
edit   # precise text replacement, oldText must match exactly
bash   # execute command, returns stdout and stderr, optional timeout

The four tools map to the core activities of programming: reading code, writing code, editing code, and running code. Example usage: read core files to analyze architecture, edit specific lines to fix bugs, write new implementations for refactoring, and bash to run tests.

Four‑Layer Architecture

┌─────────────────────────────────────┐
│        pi-coding-agent              │  ← CLI layer (session management, topics, context files)
├─────────────────────────────────────┤
│           pi-tui                    │  ← terminal UI layer (diff rendering, component system)
├─────────────────────────────────────┤
│        pi-agent-core                │  ← agent logic layer (tool execution, event flow, validation)
├─────────────────────────────────────┤
│           pi-ai                     │  ← LLM abstraction layer (multi‑provider API, context switching, cost tracking)
└─────────────────────────────────────┘

pi‑ai provides a unified LLM API supporting Anthropic, OpenAI, Google, xAI, Groq, Cerebras, OpenRouter and others. Provider‑specific quirks are handled explicitly, e.g.:

// Provider quirks example
const providerQuirks = {
  cerebras: { disallowedFields: ['store'] },
  mistral: { tokenField: 'max_tokens', disallowedFields: ['store', 'developer'] },
  grok: { disallowedFields: ['reasoning_effort'] }
};

Cross‑provider context switching converts Anthropic’s reasoning trace into a message block when switching to OpenAI.

pi‑tui: Minimal Terminal UI

pi‑tui uses diff rendering and wraps all output in synchronous escape sequences, eliminating flicker in terminals such as Ghostty or iTerm2. It avoids React‑based TUIs.

Session Management

Conversations are stored as JSONL, each entry containing id and parentId to form a tree:

{"id": "1", "parentId": null, "role": "user", "content": "Help me write a function"}
{"id": "2", "parentId": "1", "role": "assistant", "content": "Sure, here's..."}
{"id": "3", "parentId": "2", "role": "user", "content": "Make it async"}
{"id": "4", "parentId": "2", "role": "user", "content": "Add error handling"}  // branch

The /tree command visualizes the dialogue tree, /fork creates branches, and long sessions trigger automatic compression. Users can interrupt the AI with Enter (steering message) or Alt+Enter (follow‑up after a tool call).

Extension System: Primitives, Not Features

Functionality is added via TypeScript extensions rather than built‑in commands. Examples include sub‑agents, planning modes, permission controls, path protection, SSH execution, sandboxing, MCP integration, or even running Doom. Installation uses the same CLI:

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

"No‑Checklist" Philosophy

No MCP support – Popular MCP servers consume 7‑9% of the context window (e.g., Playwright MCP: 21 tools, 13.7k tokens; Chrome DevTools MCP: 26 tools, 18k tokens).

No sub‑agents – Instead of hidden sub‑agents, pi‑mono invokes itself via bash for full observability.

No planning mode – Persistent plans are written to files; TODOs go into TODO.md; background bash jobs are replaced by tmux sessions.

# Sub‑Agent example
pi --print --model claude-3-5-sonnet "Review this code: $(cat app.py)"

# Run in tmux for observability
tmux new-session -d "pi --session review 'Review the auth module'"

Ultra‑Minimal System Prompt

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

Guidelines:
- Use bash for file operations like ls, grep, find
- Use read to examine files before editing 
- Use edit for precise changes (old text must match exactly)
- Use write only for new files or complete rewrites
- Be concise in your responses
- Show file paths clearly when working with files

The prompt is under 1000 tokens, relying on modern LLMs’ inherent understanding of the coding‑assistant role.

OpenClaw Integration

import { createAgentSession } from "@mariozechner/pi-coding-agent";

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

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

The SDK enables straightforward embedding of pi‑mono as the core of OpenClaw.

Benchmark Validation

In Terminal‑Bench 2.0, pi‑mono was run against Claude Opus 4.5 on five trials per task. pi‑mono ranked highly on the leaderboard. The benchmark’s own Terminus 2, which uses a single tmux session without file‑tool abstractions, also performed well, reinforcing the effectiveness of a minimalist approach.

Four Execution Modes

pi                           # interactive (default)
pi -p "task description"    # one‑shot execution
pi --mode json               # structured JSON output
pi --mode rpc                # inter‑process communication
pi @file1.js @file2.js "refactor these files"  # batch file processing

Model switching is simple:

pi --model claude-3-5-sonnet
pi --model openai/gpt-4o
pi --model sonnet:high  # set reasoning level

YOLO Mode Realism

pi‑mono runs by default in "YOLO mode", granting unrestricted file‑system access. Zechner argues that many security measures in other agents are theatrical. He cites Simon Willison’s "dual‑LLM" approach as a poor solution, noting that an LLM with read, execute, and network capabilities creates a whack‑a‑mole security problem.

Value of Minimalism

Key observations from the design and benchmark results:

Simple tool combinations can yield complex capabilities.

Extensibility outweighs built‑in features.

Constraints foster greater creativity than unrestricted freedom.

In an era of feature bloat, subtraction can be a differentiator.

Project repository: https://github.com/badlogic/pi-mono