Key takeaways
- The pi agent harness is minimal by design: you adapt it to your workflows, not the other way around, and it ships eight documented omissions including YOLO permissions by default and no MCP support.
- That permission default decides your containment plan before your first unattended run.
- The omission list is dated 30 November 2025. Re-check it against the current release before you act on it.
Most writing about Pi describes it. Almost none of it decides anything. You already run an agent daily, you have hit a wall with it, and now you are weighing whether to move. That switching cost lands on you, personally, on a working setup. So this page skips the tour and goes at the three questions that actually gate the call: what the omissions cost on your task shapes, whether default-open permissions are survivable, and which of three postures fits your team.
What is an agent harness, mechanically
The harness is the part that isn't the model. It is the code that wraps the model, drives the agent loop, renders the UI, and handles token caching. The model does none of that. It receives a context window and emits tokens. Everything else, every decision about what goes into that window and which tool calling requests get to execute, belongs to the harness.
That boundary decides how the same model behaves in two different tools. If you have ever wondered why one feels sharp and the other dull, look at the harness before you look at the weights.
Do not feel behind if the word still slides around on you. It is genuinely unsettled. A long-time reader of a major local-LLM community recently posted asking what a harness even is, after following the sub for a long time. The field draws this line in different places. You cannot look it up and be done.
Pi sits squarely in that layer and says so in one line: a minimal agent harness you adapt to your workflows, not the other way around. Hold that word "minimal." It is the whole argument, and it is also the whole bill.
Which pi agent harness posture fits you
Here is the artifact. Three postures, keyed to the things that actually change the answer: who owns the setup, what an unattended agent can reach, and whether you depend on MCP servers, which the documented feature set does not have, alongside plan mode, background bash and sub-agents.
| Adopt as-is | Fork it | Stay on your incumbent | |
|---|---|---|---|
| Who owns the setup | Engineers who each own and maintain their own tooling | One named person who will own the harness as a real component | Nobody has budget to own a tool layer |
| Codebase risk | Low blast radius. Sandboxed repos, throwaway branches, nothing production-adjacent | Any, once you have built and tested the gate you actually trust | High. Regulated, production-adjacent, or shared with people who did not opt in |
| MCP dependency | None. Any live MCP dependency rules this row out on the documented feature set | You are prepared to build the bridge yourself | Your workflow already leans on MCP servers |
| Named disqualifier | You need plan mode, sub-agents, or background bash, and the current release still omits them | Nobody will own upstream merges in twelve months | You genuinely need to see and control everything entering context |
| First action | Stand up a containment layer before the first unattended run | Read the omission list, then audit it against the current release | Invest in your existing extension layer instead |
One honest caveat before you use it: this matrix is reasoned from published design decisions, not from measured migrations. Treat it as a starting position you can argue with rather than a benchmark. Switching cost in hours is the one input it does not carry, so time one real workflow on the new setup before you price the move.
Which omissions you'll actually feel
The documented list is eight items: minimal system prompt, minimal toolset, YOLO by default, no built-in to-dos, no plan mode, no MCP support, no background bash, and no sub-agents.
Read that as an operations bill, not a philosophy. Each line is a consequence you inherit. The useful question is which ones your work actually triggers and which ones it never touches.
| Omission | The task shape that makes you feel it | What it means, on the documented feature set |
|---|---|---|
| No MCP support | Any workflow already routed through MCP servers | Rules out adopt-as-is, not a preference |
| No sub-agents | Fanning out three investigations and merging the findings | No fan-out. That work runs as one serial session |
| No background bash | Test suites, builds, watchers, anything long-running | No background execution. You wait on it in the foreground |
| No plan mode | Multi-step work you used to stage inside the tool | Only a loss if you used it. A scratch file is the substitute |
| No built-in to-dos | Tracking your own steps across a session | Only a loss if you tracked steps in-tool |
| Minimal toolset | Work that expected a broad built-in tool surface | Few built-in tools. Anything past the defaults is yours to add through extensions |
| Minimal system prompt | Work that assumed the tool already knew your conventions | Little standing instruction ships by default. What the agent knows is what you put there |
| YOLO by default | The first unattended run against anything you care about | Not a feature gap. It is a containment decision, covered below |
Compaction is the interesting one, and its absence is not on that list at all. The only published signal about it is a personal account: Pi's creator reports cramming hundreds of exchanges into a single session without missing compaction. Take that for exactly what it is. One person's sessions, unquantified, from the person who built the thing. If your work runs multi-week sessions against a large codebase, treat compaction as an open risk rather than a settled non-issue, and test it on a real repo of yours before you commit.
The reason any of this is defensible sits underneath. Controlling exactly what enters the model's context produces better code output, and harnesses that inject unsurfaced content behind your back make that control hard or impossible. That is context engineering as an engineering constraint, not a buzzword. You trade features for visibility.
Default-open permissions and where containment belongs
YOLO by default means the agent executes tool calls without asking you first. Permission popups exist, they are just off out of the box. On a scratch repo, fine. On anything you care about, that is the single decision you make before the first unattended run.
There are two published positions on where to put the wall, and they disagree.
The in-harness gate is opt-in and lives in the extension layer. You register a listener on tool_call events and return block: true in the result to stop the call. It is simple, it is a few lines, and it sees the semantics of the call.
The counter-position says that is the wrong layer entirely: put the agent in an OS-level sandbox such as bwrap instead.
| In-harness block hook | OS-level sandbox | |
|---|---|---|
| Where it sits | In the harness, as an extension listener | At the operating system boundary, outside the harness |
| How you turn it on | Register a tool_call listener, return block: true | Launch the agent inside bwrap |
| Default state | Off. Permission popups exist but are not used out of the box | Off. It is not part of the harness, so nothing sets it up for you |
Two credible practitioners, two incompatible answers. Both are arguments, not test results, so do not take either on authority. Write down the ten calls you would never want executed against your machine, run them against whatever you configure, and see what actually stops.
The conservative reading is belt and braces. Register the hook, and launch the agent in a sandbox as well, so a gap in one is not the whole of your containment.
What you can change without forking
The named surface is extensions, skills, prompt templates, and themes. Whether that stretches far enough for you depends on how the code underneath is cut.
It is cut by layer. The project ships as separate packages, with pi-agent-core as the agent runtime handling tool calling and state management. That split is what makes the seams reachable. You can swap a layer without owning the whole tree, which is the practical difference between customizing a harness and rewriting one.
The project describes its coding agent as self-extensible, and the skills surface is where that pays off. The pattern is documented on the incumbent harness rather than on Pi: teach the agent a workflow once, then call it by name forever, instead of re-supplying the same standing instructions every session. If you have ever kept a block of instructions in a note and pasted it in each morning, you already know the failure this fixes.
If you are working out how to build an agent harness of your own, start from these seams rather than from an empty file. The package split tells you what you would actually have to write: a runtime that owns tool calling and state management, then a UI, a prompt layer, and an extension loader sitting on top of it. So how to build a custom agent harness is mostly a question of which of those layers you keep and which you replace.
One limit worth stating: this customization surface is a feature list, not a demonstrated outcome. Build one real extension and one real skill before you assume the layer will carry your whole workflow.
Forking is the supported answer, and that cuts both ways
Most projects treat a fork as a failure of the relationship. This one does not. The creator explicitly invites you to fork it if it does not fit your needs, and puts it strongly: "I implore you to fork it. I truly mean it." That is unusual and genuinely useful. It converts "this tool is 80% right" from a dead end into a plan.
It also matters that this layer is a real dependency, not just an end-user tool. Pi is the minimalist, self-modifying coding agent that OpenClaw is built on top of. When another agent product sits on a harness, that harness's defaults become the product's defaults too. Yours as well, if you build on it.
Now the other edge. A fork you own is a fork you maintain. Every upstream release becomes a merge decision, and on a project shipping at this pace that is a standing tax on someone's week. Price it yourself before you commit. The honest test is whether you can name the person who will own the merges in twelve months.
How pi harness agents sit against what you already run
Staying put is a real option, and the field is wider than the argument usually admits. Practitioner surveys of this space cover Codex, the Claude desktop app, Cursor, Antigravity, VS Code and WebStorm alongside the minimal harnesses. This is not a two-horse race.
The current numbers, as of late June 2026. On the public Terminal-Bench 2.1 leaderboard, Codex CLI with GPT-5.5 leads at 83.4%, and Claude Code with Opus 4.8 is the top runnable Claude pairing at 78.9%. On open-source reach, opencode leads at 180,312 stars under MIT, ahead of Claude Code at 134,868, Gemini CLI at 105,641 and OpenAI Codex at 94,277. Both sets move. Re-check them before you quote them.
Give the incumbent its due, because this is where the minimal option loses. If you run the Anthropic agent harness today, you already have compaction, and you have an extension layer mature enough that a workflow encoded once can be called by name forever. Those are the exact things you would be handing back.
The dimension that genuinely separates them is not benchmark score. It is whether you can see and control what enters the context window. If that is not your bottleneck, stay where you are.
Re-check the omission list before you act on it
Here is the part nobody does, and the caveat comes first: we have not run the release-by-release audit ourselves, so nothing below is a finding. It is a procedure you run before you trust any of this, including the rows in this page's own tables.
The omission list everyone quotes is dated 30 November 2025. Read on 19 July 2026, the repository stood at 247 releases with commits from within hours. That is roughly eight months of shipping between the write-up driving your decision and the code you would install.
So treat every omission above as a re-check item rather than present fact, including the ones this page calls disqualifiers. If an omission is load-bearing for your decision and you have not confirmed it on the version you would install, you do not yet have the input you need, and neither this page nor any of the write-ups can supply it for you.
Before you act, do three things. Open the changelog and search it for the five load-bearing items: MCP, sub-agents, plan mode, background bash, compaction. Check whether the default permission posture has changed. Then write today's date next to whatever you conclude, because it will go stale the same way.
What you have to find out for yourself
Four gaps, stated plainly so you do not go looking for answers that are not there.
Cost on a real coding workload. The only figure circulating is a self-managed deployment on open models, under $20 a month including inference, on a VPS the practitioner runs themselves. That was a Discord bot. A coding agent chewing through a large repository is a different workload, so the number does not transfer. Run a week of your own real work through it and read the bill.
Cross-provider context handoff mid-session. If you plan to switch providers inside a session, work out how your context carries across before you rely on it, and test it on something you can afford to lose.
Migrating your existing hooks and skills. If you have already invested in an extension layer, that investment is exactly the kind of encoded workflow you would have to rebuild. Port one workflow and time it, then multiply.
Where the canonical repository actually lives. Two reputable sources name different owners. This page does not publish an install path or a repository link because of it. Verify the source before you clone anything, and be suspicious of any guide that skips that step.
Where to start, by posture
If you are adopting as-is: stand up your containment layer before the first unattended run, not after. Register the tool_call listener, decide which call classes you block, and put the agent in a sandbox as well. Do it on a repo you would not mind losing.
If you are forking: read the omission list, audit it against the current changelog, and name the person who owns the merges. Then fork, because the invitation is explicit and you are not fighting the project by taking it.
If you are staying put: spend the switching cost you saved on your extension layer instead. Encode the three workflows you retype most often, then see how much of the original problem is left.
Whichever you pick, notice what the decision was actually about. Not the model. The layer around it, and how much of it you can see, change, and stop. That is the discipline Rifty works in: control layers built to be legible, steerable, and reversible, so nothing irreversible ships without your sign-off. If you have decided the agent layer is your bottleneck, Rifty's research on building agentic AI systems is where that argument gets made in full.
And if you want a harness you never open the hood on, none of this is your problem, and Rifty is not your answer.
Next: where the blast-radius line sits before you let an agent run unattended, and how the current coding agents compare.