Pi agent harness

pi — Mario Zechner’s (badlogic, libGDX author) minimal terminal coding harness, since April 2026 under Earendil Inc. (Armin Ronacher’s PBC). Repo: pi (OSS) (earendil-works/pi, 112.6k★, TS; formerly badlogic/pi-mono; site pi.dev). The origin complaint (Zechner’s Nov 2025 essay “What I learned building an opinionated and minimal coding agent”): Claude Code was “a spaceship with 80% of functionality I have no use for” — system prompts and tool definitions changed between releases, hidden context injections made the model’s actual context unreconstructable. Pi’s answer: adapt pi to your workflows, not the other way around.

The minimal core

• Four default tools: read, write, edit, bash. System prompt + tool definitions under ~1,000 tokens. Shell covers search/ls/git (“frontier models are extensively trained on shell utilities”; every schema-visible tool competes for attention in every request).
• Four modes: interactive TUI · pi -p print/JSON (scripts) · RPC over stdio · SDK (createAgentSession() — this is how OpenClaw embeds it, the “Clawdfather” steipete ecosystem from Local archives & crawlers).
• Monorepo DAG: pi-ai (unified multi-provider LLM API — usable standalone) → pi-agent-core (agent loop, steering, event streaming) → pi-tui (retained-mode terminal UI, differential rendering) → pi-coding-agent (CLI harness).

The deliberate “no” list (the philosophy IS the product)

No MCP (“adds latency when shell commands + READMEs already work” — build CLI tools with READMEs, Agent Skills format, or mcporter) · no sub-agents (spawn pi --print via tmux, output stays visible) · no plan mode (PLAN.md files, full observability) · no built-in to-dos (“they confuse models” — TODO.md) · no permission popups (“break flow” — run in a container or build your own gates) · no background bash (tmux). Each “no” ships with a “build it as an extension or install a package” answer — bloat is the failure mode worth avoiding even at the cost of feature parity.

Extension layers

Skills (SKILL.md, progressive disclosure — token-cheap) · prompt templates (/name Markdown) · TypeScript extensions (tools/commands/TUI widgets/events, hot reload) · pi packages (pi install npm:… or git:… — the community ecosystem). Sessions: tree-structured with branch/fork/rewind (/tree, /fork), compaction; sessions auto-save under ~/.pi/agent/sessions/.

Why it matters to this vault

• The harness-minimalism pole of the harness spectrum against Claude Code’s maximalism — the same “pin the cheap slots, keep the core small” instinct as the witcheer/portal-affordable analysis and KISS preference.
• The ecosystem other tools target: pstack-claude has a Pi version, HarnessRouter routes it, sideshow/plannotator hook it, omnigent (OSS) meta-orchestrates it. “Pi first” is a real compatibility tier now.
• Kinship: Agent Client Protocol (harness-neutral boundaries), CLIs for agents (bash + README over MCP), Vibecoding vs AI engineering (observability over convenience), cron/tmux orthodoxy — do-nothing-scripting’s “full observability, direct interaction.”

Related: pi durable · Agent Client Protocol · CLIs for agents · Local archives & crawlers (OpenClaw embeds pi’s SDK)

The discipline’s empirical foundation: the eleven-harness study

arXiv:2609.00006 (captured) — source-code anatomy of eleven production harnesses (Claude Code, Codex CLI, Gemini CLI, Mistral Vibe, OpenHands, Aider, Mini-SWE-Agent, Hermes, Pi, OpenCode, OpenClaw) + Omnigent as first meta-harness; 7 canonical subsystems, 29 recurring design patterns, 18 recommendations, a 90-line minimum-viable-harness scaffold. The findings that vindicate this note’s subject: no runtime imports a general-purpose agentic framework; none retrieves code with vector embeddings (~4M lines audited — hand-rolled async loops + deterministic retrieval won); SKILL.md skills lead MCP 9/11 vs 8/11; ACP in six systems with a new “harness hosting” role; one-quarter longitudinal diff shows “convergence becoming imitation and behavioral policy migrating from prompt prose to configuration”; thesis: the coding harness turned from tool to platform in H1 2026. Pi appears here as one of the eleven — the minimal pole officially in the canon.

Team harnesses: the multi-user lane (2026-10-06)

Two captures define the space. femke_plantinga: “Claude Code is built for one person. What do you use when your whole team needs the same agent?” — six open-source team harnesses with fit notes: Deep Agents (LangChain; Stripe’s Kai runs on it — 100+ teams, 1,000+ skills; for engs building their own), QM (YC; per-person/per-room memory + access rules; Slack-native startups), Cloudflare OS (agent builds small private apps for non-technical staff; every action recorded, changes wait for human approval), Omnigent (Databricks; teammates join the same coding session by link; admin budgets/permissions — the meta-harness from the eleven-harness study), OpenClaw 2.0 (shared sessions, joinable/takeoverable without context loss; trust-each-other small teams), Goose (Linux Foundation; runs on each person’s machine, company packages provider+data connections — the managed-distribution pole). Her closer is the thesis this vault runs on: “whichever one you pick, it can only work with the context you give it: your docs, your processes and who owns what” (the ebook = 9+ company-brain structure breakdowns).

TencentAI_News: Octop (OSS) (7.1k★ Python, Tencent Cloud) — the multi-user lane from the consumer side: self-hosted “AI workspace for yourself, your family and your team”; per-user logins, multi-agent with per-agent workspaces, strict account isolation; models/storage/memory/plugins all swappable; each agent gets a browser + terminal + remote desktop; hands off work to Claude Code/Codex/Cursor/OpenCode/CodeBuddy; lives in Telegram and Discord group chats; octop run one-command start. The interesting bit vs the six above: Octop treats coding agents as swappable engines inside a social container — the inverse of the harness-makers adding chat (OpenClaw channels, Pi Discord). Homelab-relevant: self-hosted multi-user agent container that speaks Telegram is exactly the doombox shape.

• The layer above this note’s landscape now has its own note: Meta harness — Omnigent as the exemplar (orchestrate harnesses per task, governance as the product, sessions across devices).

In-harness subagents mature: the championswimmer manager (2026-10-07)

championswimmer (Arnav Gupta; thread + pi-subagent-manager (OSS) captured, 15★ — day-old, npm-published): his arc tracks the capability shift — subagents felt “like overkill… ai factory psychosis” until the Opus 5.5 / GPT 6 generation, which “knew how to use another instance of themselves as a separate agent… when to fork the context and when to start independent sessions.” His claim: with this generation it’s better to run models as subagents than to orchestrate worktrees yourself. Pi (his harness: “clearly gets most tasks done faster and at much less cost… because it bloats the context much less”) lacked subagents — so he built one borrowing from @nicopreme and @nicht_tintin’s designs: Claude-Code-style agent types (Markdown files w/ frontmatter) × Codex-style paths (/root/fix-auth/review), type and path independent — parallel, nested, resumable, steerable, multiple models per agent with availability/permission fallback. Plus two modes: opportunistic (main model spawns when it wants) vs orchestrator (main thread always delegates and stays free to talk to you). Kin: Git worktrees (the Conductor/T3 lane he explicitly distinguishes — orchestration across harness instances vs within one session), Meta harness (the layer above both).

The unbundling follow-up (2026-10-08)

TencentAI_News: Octop’s four core components open-sourced separately, all MIT, each usable without the rest of the stack: octop-harness (agent execution; 51★ — “production-grade agent runtime engineered from the Harness Engineering philosophy,” an honest encapsulation layer around LangChain’s deepagents with model routing, tiered memory, multi-agent registry, pluggable backends, ACP server, tool guardrails/PII redaction) · octop-memory (persistent memory, L0→L3 distillation, “bring your memory to the next agent”) · octop-browser (“direct CDP, no Playwright” — agent-first browser automation) · octop-gateway (multi-platform IM bridge with unified message abstraction). The move matters for the landscape: a social-container vendor deciding its value is the workspace, not the plumbing — commoditize your complements, written in MIT. The memory/browser/gateway trio slots straight into the swappable-lanes picture: pick any one beside Claude Code/Pi/Hermes. Kin: Meta harness (paperclip/Omnigent pole vs unbundled-components pole — two opposite bets on where value pools), the octop-harness ACP server (Agent Client Protocol as the connective tissue).