Pi Agent Harness: Minimalist AI Coding Agent Returning Control to Developers

What Is Pi Agent Harness?

Pi is a minimalist terminal coding agent created by Mario Zechner (GitHub user badlogic, creator of libGDX). Its core philosophy: provide a usable default capability set but avoid hard-coding every workflow into the product. Developers can extend Pi via TypeScript extensions, Skills, prompt templates, and shareable packages. The article examines Pi not just as a coding tool but as a way to expose the usually hidden Agent Harness — the execution framework that surrounds the model and handles task definition, context/memory management, tool execution, loop control, verification, and failure handling.

Pi vs. Other Coding Agents

A comparison table highlights key differences:

Product philosophy: Pi — minimal core, self-extended workflows; Claude Code/Cursor — out-of-the-box experience; oh-my-pi (omp) — Pi fork with more built-in editing/debugging.

MCP: Pi initially omitted MCP; added core MCP + Codemode in late September 2026.

Sub-agents: Pi — via extensions, packages, or tmux; Claude Code/Cursor — built-in workflows; omp — sub-task orchestration.

Session history: Pi supports tree-shaped branching; others have varied checkpoint mechanisms.

Model providers: Pi supports 15+ providers (Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi, MiniMax, OpenRouter, Ollama, etc.); specifics vary by version.

Integration: Pi offers terminal, Print/JSON, RPC, SDK; others focus on IDE/CLI.

Best for: Pi — custom harness, context engineering, platform embedding; others — daily coding and collaboration.

The article emphasizes that "minimal" does not mean "few features"; Pi retains the backbone to run an agent while leaving planning mode, sub-agent orchestration, and approval policies to the user, granting greater control but also more configuration, testing, and security responsibility.

Six Components of an Agent Harness

Task Definition — turn user requests into executable, verifiable tasks.

Context / Memory Management — control what instructions, code, and history are sent to the model each turn.

Tool Execution — read/write files, run shell commands, call APIs.

Loop Controller — decide whether to continue or stop based on tool calls and results.

Verification — check that code actually meets requirements, not just trust the model's "done" claim.

Failure Handler — retry, abort, or hand off to a human on tool failure, timeout, drift, or verification failure.

Pi provides task interaction, context management, tool calling, loop, and basic error handling. Business-level acceptance criteria and verification flows remain the user's responsibility; Pi does not automatically guarantee business reliability.

Minimal Execution Loop (Illustrative, Not Pi Source)

User requests a change
    ↓
Load system instructions, project rules, relevant context
    ↓
Call LLM
    ↓
Model decides: answer directly or call tool?
    ├── Direct answer → output result
    └── Call tool (read / write / edit / bash)
         ↓
      Execute tool
         ↓
   Return tool result to model
         ↓
Next round of reasoning and tool calls
         ↓
End or enter custom verification flow

Example: user asks "add input validation and run tests." Model reads source, edits files, runs test command. Harness executes actions and feeds stdout/stderr back as next context. Model can iterate on failures, but final acceptance requires independent verification.

Installation and First Run

Install via npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Or macOS/Linux install script (verify script first): curl -fsSL https://pi.dev/install.sh | sh Note: package name and repo organization have changed; older tutorials may reference @mariozechner/pi-coding-agent — do not mix versions.

Run in a project directory:

cd /path/to/your/project
pi

Authenticate with /login or set API keys (e.g., export ANTHROPIC_API_KEY="your-key"). Pi supports many providers; model selection via /model, shortcuts Ctrl+L (model switcher) and Ctrl+P (favorite models).

Recommended first step: use a Git-tracked test repo, ask Pi to read README and explain entry points, directory structure, test commands — without modifying files. Then request a scoped change: "Only modify input validation code to add explicit error for empty string; run corresponding tests; report modified files, test command, results, and unverified items; do not touch unrelated modules." This lets you observe Pi's file reading, tool use, and feedback handling.

Four Running Modes

Interactive ( pi) — daily coding, real-time view of tool calls and results.

Print / JSON ( pi -p "query" or --mode json) — scripts, CI, machine-readable event streams.

RPC — JSONL messages over stdin/stdout; control Pi from other languages or external processes.

SDK — Node.js API to embed Pi's agent capabilities into your own software or service.

SDK and RPC are key for platform integration: instead of reimplementing model calls, context maintenance, tool execution, and session management, use Pi as the middle execution layer. OpenClaw is cited as an architectural example where the upper product handles messaging, scheduling, and skills, while Pi provides the lower-level agent execution. (Integration details vary by version.)

Mode selection guide: Interactive for trying Pi; Print/JSON for automation pipelines; RPC for non-Node.js hosts controlling the agent; SDK for deep Node.js service integration. Warning: "Agent will execute" ≠ "suitable for unattended operation." Add explicit boundaries for deletions, deployments, pushes, and external network access.

Context Engineering: AGENTS.md, SYSTEM.md, Compaction, Skills, Extensions

AGENTS.md — Project-Level Rules

Pi reads AGENTS.md from global config, parent directories, and current project. It acts as a working procedure referenced on every project entry, not a long-term memory DB. Example:

# Project Rules

- Read README and existing tests before modifying code.
- Only modify modules relevant to the current task.
- Do not modify generated directories, historical backups, or production secrets.
- Run relevant tests after each change.
- If tests cannot run, explicitly state why.

SYSTEM.md — System Prompt Override

SYSTEM.md

replaces or appends the default system prompt, altering the agent's role, boundaries, and behavioral preferences. This is a harness-layer config; no fork needed. AGENTS.md suits project constraints; SYSTEM.md suits base agent behavior. Loading order and priority depend on installed version.

Compaction — Context Compression

As conversation grows, Pi compresses older messages and allows extensions to customize compression logic (topic summaries, retain key code decisions, use cheaper models for summarization). Compaction ≠ lossless memory. Summaries may drop early constraints; critical test commands, forbidden modification ranges, and confirmed conclusions should be written to project files, not rely solely on chat history.

Skills & Prompt Templates — Progressive Disclosure

Skills — package task instructions, references, and procedures into reusable capabilities for specific tasks or tech stacks.

Prompt Templates — define reusable prompts via Markdown, invoked with commands like /name.

Both avoid stuffing all task instructions into the resident system prompt; context expands only when needed — a progressive disclosure strategy.

Extensions — Runtime Behavior Changes

TypeScript extensions hook into events, commands, keybindings, tools, TUI, and can pre-process context before model calls. Common uses: inject dynamic messages, filter history, integrate RAG or long-term memory.

Skills ≠ Extensions. Comparison:

Form: Skills = Markdown instructions + resources; Extensions = running TypeScript programs.

Role: Skills tell agent how to complete a task type; Extensions change tools, events, interaction, and execution flow.

Typical uses: Skills — code review standards, test steps, business guides; Extensions — custom tools, permission confirmations, logging, dynamic context.

Key risk: Skills may induce dangerous actions; Extensions themselves may hold system-level execution permissions.

Rule of thumb: if you only need unified acceptance steps, write a Skill; if you need new event hooks or tool-call behavior, consider an Extension.

Tree-Shaped Sessions: Multiple Exploration Paths

Pi supports tree-structured conversation history. Use /tree to navigate and branch from any prior node without overwriting the original path. Additional commands: /export (HTML export), /share (e.g., GitHub Gist). Example: same test failure explored via two branches — one from config, one from code logic — preserving decision paths better than starting new chats.

Branch history ≠ Git code branches and does not auto-revert disk changes. For reversible code experiments, combine with Git commits, worktrees, or isolated working directories.

Mid-Run Steering: Steer vs. Follow-up

Enter (Steer) — send new requirement as mid-course correction; processed after current tool execution, may interrupt remaining tools in the batch.

Alt+Enter (Follow-up) — queue message; delivered after current task round finishes.

Steer for "you misunderstood, don't touch the database now"; Follow-up for "after finishing, tell me which tests ran." This is a lightweight human-in-the-loop mechanism, but does not replace per-dangerous-tool approval . Production projects still need independent authorization design.

Why Pi Doesn't Pre-Install Everything

Pi's design philosophy shows in what it omits by default:

MCP: not built-in early; added to core with Codemode in late Sept 2026 — version-dependent.

Sub-agents: organize via tmux, extensions, or third-party packages.

Permission prompts: implement via container isolation or custom confirmation mechanisms.

Plan Mode: use plan files, extensions, or existing packages.

Built-in TODO: maintain via TODO.md or extensions.

Background Bash: manage via tmux or external process tools.

Pi isn't saying these capabilities are unimportant; it argues not all users should be forced into the same workflow . One team may require stepwise file-write approval; another runs the whole agent in a container with full autonomy — different security models.

MCP (Model Context Protocol) connects model apps to external tools/resources; Codemode emphasizes code-organized tool usage. Not all third-party MCP servers are automatically safe in Pi — connection, auth, tool exposure, and compatibility must be verified individually.

Pi Extending Pi: /reload and Shareable Packages

Pi can help write its own TypeScript extensions; after changes, /reload reloads them without maintaining a separate fork. Extensions, Skills, prompt templates, and themes can be packaged as Pi Packages and distributed via npm or Git:

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

@foo/pi-tools

is a placeholder; pi-doom demonstrates extension power — even running DOOM, not just adding editor buttons. Self-extension carries risk: model-generated extension code may alter tool permissions, file operations, or context injection rules. Shared or team-production extensions should undergo code review, version pinning, and isolation testing.

Pi vs. oh-my-pi, Claude Code, Cursor, OpenClaw

oh-my-pi (omp): notable fork adding hashline editing, LSP, DAP, more model providers, sub-agent orchestration. Choose base Pi for lightweight self-organized capabilities; omp for richer built-in editing, diagnostics, debugging. Capabilities evolve per version.

Claude Code & Cursor: prioritize out-of-the-box daily dev experience. Pi prioritizes programmable harness control. Choice depends on whether you truly need to modify context assembly, execution events, and tool control logic.

OpenClaw: architectural example of SDK integration — upper layer handles messaging, scheduling, skills, UI; lower harness (Pi) handles model/tool calls. Actual integration details vary by version; don't treat as permanent dependency.

When to Choose Pi

Pi fits when you:

Want fine-grained control over AGENTS.md, system prompts, dynamic context, and compaction strategies.

Need to switch model providers without binding the execution framework to a single model.

Are building your own AI software and want to embed an agent via SDK or RPC.

Need branching sessions, experimental paths, and observable execution history.

Are willing to build your own verification, permission, and multi-agent orchestration mechanisms.

If the goal is simply faster daily coding without maintaining extensions or integration config, more feature-complete products save time. For pre-installed LSP, DAP, and sub-agent workflows, evaluate oh-my-pi.

Building a Verifiable Pi Workflow from Scratch

Start simple, add capabilities incrementally. Five steps:

Define boundaries: allowed modification directories, forbidden credentials/resources, permitted test commands.

Define acceptance criteria: e.g., "new input validation must pass unit tests, existing tests must not regress."

Use only Pi default tools for first task: core tools are read, write, edit, bash. Avoid plugins initially.

Add independent verification: automated scripts or CI judge test pass/fail via exit codes, not just model's textual log interpretation.

Record execution results: minimally keep modified files, tool commands, test results, failure info, and human-pending items.

Reusable AGENTS.md Template

# Agent Work Constraints

## Task Scope
- Only modify files in src/ and tests/ directly related to the current requirement.
- Do not modify secrets, dependency lock files, or deployment configs unless explicitly authorized.

## Work Order
1. Read relevant code and existing tests.
2. State expected modification scope.
3. Modify code and add tests.
4. Run relevant tests; run full suite if needed.
5. Summarize changes and outstanding items.

## Completion Criteria
- Key functionality has automated tests.
- All executed tests pass.
- No unrelated modifications introduced.
- Unverifiable parts must be explicitly reported; do not claim they passed.

This is a generic illustration, not a Pi-generated default. Adapt to build process, team requirements, and risk level.

Security & Sandbox: Minimal Harness Responsibility Boundaries

Pi core lacks mandatory per-tool permission prompts; security must be implemented at runtime environment, tool layer, or extension layer (Docker, other isolation tools). Four risk categories:

Shell execution permission: bash can delete files, access network, run install scripts. Use dedicated user, container, or restricted working directory.

Third-party packages & extensions: they execute real code, not just prompts. Review source and pin versions before install.

Prompt injection: repo docs, web pages, tool outputs may carry untrusted instructions; context presence ≠ elevated privilege.

Sensitive info & session sharing: before export/share, scrub API keys, private paths, internal source code, and other secrets.

Distinguish container isolation from business authorization : even inside a container, the agent should not have rights to publish to production or use real access tokens.

Recent Developments (2026)

Aug 5, 2026: Earendil cited Databricks internal coding agent benchmark claiming Pi achieved higher pass rate with less context and lower cost under specific model/inference config. Result is condition-specific , not a universal guarantee. Shopify reported significant metric improvements using pi-autoresearch extension — case-specific, not general promise.

Late Sept – Oct 1, 2026: Pi added MCP and Codemode to core, invalidating earlier "no MCP" descriptions.

Oct 2, 2026: Pi 1.0 released with experimental Pi Durable for longer-running sessions. Still experimental; usability, state recovery, and failure guarantees need version-specific verification — not yet a mature production durable system.

Why Pi Is Worth Studying

Pi's core value isn't replacing mainstream coding agents but exposing the usually hidden mechanisms: how the model receives tasks, gains context, calls tools, handles history branches, and where custom behavior hooks in. It serves as a reminder: Agent reliability depends not only on model intelligence but on how the harness organizes context, executes tools, verifies results, and controls risk.

If the goal is personal coding efficiency, evaluate existing tools first. If the goal is building custom agent workflows, embedding intelligence into products, or researching Agent Harness Engineering, Pi offers a concrete, hackable starting point.