A harness is the program around an AI model. It builds each prompt, runs the tools that the model asks for, keeps a record and decides when to stop.
Inside, harnesses are quite similar. They share one loop and the same few parts. But they make different choices in a few places: how much fixed text to send, when to summarize, when to stop, and what to allow. These choices change the quality and the cost, and no one choice is best for everyone. The right choice depends on your model, your task and your team. Today, to change one choice, you must pick another harness or write your own. A new harness also changes all its other choices, so you cannot tell which choice caused a change in the result.
I believe that we do not need more harnesses. We need one harness where each choice is a setting. You change one setting, keep the others, and see what that setting does.
In our Harness Engineering workshop, we deep dive into these settings, and how changing them affects cost and performance. Sign up here.
A harness is easy to start and hard to finish. Yet everyone is building one.
Claude Code, Codex, Hermes, Pi: if you code with an AI agent, you probably use one of these, and you may have noticed that they behave differently even when they run a similar model. Meanwhile, someone on your team is probably writing their own. The list is long: the model makers ship Claude Code, Codex CLI, Gemini CLI and Mistral Vibe. The open-source world adds Pi, Hermes, OpenCode, OpenClaw, OpenHands and Aider, and researchers run small ones such as Mini-SWE-Agent, SWE-agent and Terminus-2 (Harness Engineering study; SWE-bench experiments; Long-Horizon-Terminal-Bench).
A second wave of tools does not replace the harness but wraps around it. Caveman sits between the harness and the model provider to trim the bill, TokenEconomizer learns from past sessions, actor-gatherer picks what the model gets to see, and Omnigent drives several harnesses as interchangeable parts (same study).
Why so many? Starting is easy. Mini-SWE-Agent does the whole job in about a hundred lines. One study of eleven harnesses ends with a working one in ninety lines (Harness Engineering study). The hard part comes later.
Why it looks wasteful. When one harness finds a good idea, the others have it within weeks. Three features each spread to several harnesses in one quarter: loading tool descriptions only when they are needed, a separate planning mode, and an AI that reviews risky commands before they run (same study). The copying is visible in the code. Codex uses the hook names of Claude Code, and OpenCode reads the skills folder of Claude Code.
So, why does each team still build its own?
Teams have good reasons to build their own harness. I found several reasons, and the first is the most basic.
Mitchell Hashimoto (co-founder, Hashicorp) describes harness engineering as turning each mistake that the agent makes into a permanent fix in the harness. The mistakes depend on your codebase, your tools and your habits. A rule such as “always run this linter before you stop” is a great fix for one project and only noise for another. Thus, a harness that has grown around the mistakes of one team can feel clumsy to the next team.
The second reason is the model. Claude Code assumes a strong model and mostly stays out of its way. Mingbird starts from the opposite assumption. It is built for small open models, 2 to 9B parameters, that run on a laptop, and it steps in often. It refuses irreversible actions. It sends one corrective prompt when it detects a loop. Before it accepts that the work is done, it re-reads the task and runs the task’s own checks (Mingbird paper). Editing files shows the same pattern. To change a file, the model must quote the exact text to replace. A strong model quotes it correctly. A weak model makes small errors, so the harness must accept text that is almost the same, or ask for another format: the full new file, the old and new lines, or a diff. Aider has thirteen edit formats and chooses one for each model (Harness Engineering study).
The third reason is context, the text that the model receives on each call. The window has a limit, so a long session must remove or compress old text, and each method loses some information. One developer tracked 162 days of their own Claude Code use. Five steps after a summary, 41.9% of their messages corrected the agent. At other times, the rate was 17.7% (LangWatch). Thus, people build their own methods. Actor-gatherer, for example, adds a second program that keeps the full history and puts the related old text back before each call, even if the agent does not ask for it. On tests where the key fact is in an early user message, its authors report scores 27 to 36 points higher (actor-gatherer). The best method also depends on the size of the window. A separate study compared five methods (Fan et al., arXiv 2609.20804). With a 32k-token window, the best and the worst method differed by 35.7 points. With a 128k window, they differed by only 2.7 points.
The fourth reason is how the harness loads tools. Each tool needs a description in the prompt, and harnesses have from 1 tool (Mini-SWE-Agent) to more than 109 (OpenClaw). Many harnesses now send only the tool names, and load the full description when the model needs the tool. One paper reports that this makes the Claude Code prompt approximately 40% smaller. In my own experiments, however, the same change made the total cost 7% higher. A saving on paper does not always reach the bill, and each team must measure its own case.
The last reason is about business. A harness has become a platform worth owning. Harnesses turned into the frameworks that people build on, such as the Claude Agent SDK and the Codex SDK, and framework makers such as LangChain now ship harnesses of their own. Owning the harness also means that you control the updates. Codex downloads its prompts and settings from OpenAI’s servers, so its behaviour can change on the day a new model ships.
These are good reasons to want a harness that fits you. They are not, by themselves, reasons to write one from scratch. To see why, we first look at what all these harnesses share.
Inside, the harnesses look alike. The authors of the study from section 1 read the code of eleven harnesses (Harness Engineering, arXiv 2609.00006). They found the same structure in all of them:
AGENTS.md or CLAUDE.md. All of them find code with plain text search. None of them searches code by meaning.Thus, a new harness mostly builds the same parts again. But “quite similar” is not “the same”. In the next section, I show the real differences and why they are important.
Harness builders make different choices in a small number of places. Each choice involves one of the core features:
These choices are important because they impact results and performance:
Thus, the harnesses differ mainly in their settings: how much fixed text to send, when to summarize, when to stop, and what to allow. These values change the results, the quality and the cost. Here, I argue for a better path.
In our Harness Engineering workshop, we deep dive into these settings, and how changing them affects cost and performance. Sign up here.
We do not need more harnesses. We need one harness that we can configure. Such a harness must have these properties:
Some harnesses already take the first steps:
A personal note. To explore configurability, I build muharness, a simulator of harnesses. It is not a harness – does not call a model, and does not change files. It is a simulator of harnesses: one small core and a set of settings. I wanted to know if this design works. Some of my observations:
I don’t think so. The harnesses are quite similar underneath. They differ in a small set of choices, and each choice can be a setting. Today, a team that wants a different setting often writes a new harness. That is slow, and good ideas spread only by copying. A better direction is one configurable harness, and a simulator that shows the cost of each setting before you change it. muharness is a first step toward that simulator.
Until that harness exists, I recommend asking one question before you build: which setting do I want to change? If an existing harness, or an add-on, lets you change it, you do not need a new harness. If none does, build that one setting, and share it.
Learn to tune a harness. In our Harness Engineering workshop, we work with the loop, the tools and the checks around a model. You see what a harness costs, how much you can trust it, and which settings fit your model and your task. Join the waitlist.