Why pi-mono’s Agent Design Is an Anti‑Pattern (and What Works Better)

Background and Motivation

pi-mono is the Agentic framework behind OpenClaw. After finding Claude Code overly feature‑rich—80% of its functionality unused and frequent breaking updates—the author, preferring simple tools, built pi as a lean alternative.

1. Core Requirements

Fully controllable : inspect every interaction detail instead of a black box.

Simple and portable : clear session format, easy post‑processing, custom UI possible.

Multi‑model support : seamless switching between models with context carried over.

Self‑hosting friendly : runs locally without relying on Vercel AI SDK or similar services.

The goal was a “just right” tool, not an over‑engineered solution.

2. pi Architecture

pi-ai : unified LLM API supporting major providers (Anthropic, OpenAI, Google, xAI, Groq) with streaming, tool calls, reasoning mode, context passing, and token tracking.

pi-agent-core : implements the Agent Loop handling tool execution, verification, and event streams.

pi-tui : terminal UI framework offering differential rendering, flicker‑free updates, an auto‑complete editor, and Markdown rendering.

pi-coding-agent : combines the above, adding session management, custom tools, theming, and project‑level context files.

Principle: “If you don’t need it, don’t build it.”

3. Design Insights of pi‑ai

3.1 Only Four Provider APIs

Despite many providers, the underlying HTTP APIs fall into four categories:

OpenAI Completions API

OpenAI Responses API

Anthropic Messages API

Google Generative AI API

All other providers are wrappers of these, with differing fields (e.g., store, max_tokens vs max_completion_tokens, reasoning_content vs reasoning). pi‑ai includes extensive tests covering image input, reasoning tracking, and tool calls.

3.2 Context Propagation

When switching providers, the context must travel with the model. For example, moving from Anthropic to OpenAI converts reasoning content into a <thinking></thinking> tag inside the message.

// Switch to GPT – it will see Claude’s reasoning content
const gpt = getModel('openai', 'gpt-5.1-codex');
context.messages.push({ role: 'user', content: 'Is that correct?' });
const gptResponse = await complete(gpt, context);

3.3 Structured Tool Results

LLM‑visible tool output can differ from UI presentation. Example weather tool returns both a textual response for the model and a structured details object for the UI.

const weatherTool = {
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: weatherSchema,
  execute: async (toolCallId, args) => {
    return {
      // Text for LLM
      output: `Temperature in ${args.city}: ${temp}°C`,
      // Structured data for UI
      details: { temp }
    };
  }
};

4. pi‑tui Design

4.1 Two TUI Modes

Full‑screen mode takes over the viewport (used by Amp and opencode) but loses scrollbars and search. Append mode writes like a normal CLI, occasionally rewrites lines (used by Claude Code, Codex, Droid). The author chose append mode to leverage native terminal scrolling and search.

4.2 Differential Rendering

Each component implements render(width) returning rendered lines. The container compares new lines with the previous render and only redraws changed lines. Rendering algorithm:

// Algorithm:
// 1. Initial render: output all lines
// 2. Width change: clear screen and re‑render
// 3. Normal update: find first changed line and redraw from there

To avoid flicker, pi‑tui wraps all output in synchronous escape sequences ( \nCSI ?2026h and \ CSI ?2026ln) which most modern terminals support.

5. pi‑coding‑agent “Anti‑Patterns”

5.1 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
- Use write only for new files or complete rewrites
- Be concise in your responses

Compared to Claude Code, Codex, and opencode, which use multi‑thousand‑token prompts, this minimal prompt works because modern LLMs already understand the coding‑assistant role.

5.2 Minimal Tool Set

read : read files, supports images.

write : write files, auto‑creates parent directories.

edit : precise text replacement.

bash : execute commands.

Additional read‑only tools (grep, find, ls) are disabled by default; the model already knows how to use bash.

5.3 YOLO Mode (Full Permissions)

pi runs with full permissions, no sandboxing. The author argues security checks are “security theater” and that the only effective safeguard is disconnecting the network, which defeats the agent’s purpose.

5.4 No Built‑in Todo or Planning

Todo tracking adds state‑management overhead and error risk. Users should manage tasks via plain files (example # TODO.md snippet). Planning is also external; a simple # PLAN.md file outlines goals, approach, and current step.

5.5 No MCP (Massive Context Prompt)

MCP servers are heavyweight (e.g., Playwright MCP with 21 tools and ~13.7k tokens). They consume 7‑9% of the context window even when most tools are unused. A lighter approach is to write CLI tools with README documentation and let the agent read them on demand.

5.6 No Background Bash

Background processes require tracking, buffering, cleanup, and input handling. Claude Code’s background bash lacks observability. The author recommends using tmux for session management and debugging.

5.7 No Sub‑Agents

Sub‑agents in other systems are black boxes with poor context handling. If needed, pi can spawn itself via bash, e.g., pi --print --model claude-opus-4-5 "Review this code...".

6. Performance Comparison

The author ran Terminal‑Bench 2.0, comparing pi + Claude Opus 4.5 against Codex, Cursor, Windsurf, etc. The benchmark chart (shown below) demonstrates that pi’s system prompt plus tool definitions total under 1 000 tokens yet achieve strong results.

Another evidence is Terminus 2, a minimal agent that only receives a tmux session. It competes well with heavily‑armed agents, showing that a simple design can be equally effective.

7. Conclusion

Benchmarks are fun, but daily work proves pi performs excellently. While many posts discuss “context engineering,” few frameworks truly enable it. pi‑mono is the author’s attempt at a controllable, simple tool. Future additions (compression, streaming tool results) are optional.