Since the start of the year, everyone talks about the "harness". Harness engineering, agent harness, best harness. Ask around for a definition. You will get five different answers.
Yet the definition fits in one sentence.
TL;DR: the harness is the software that coordinates exchanges between the model and its environment. It prepares context, runs authorized tools and returns their results to the model. It can include checks and limits. You encounter it in a product, a library, custom code or a hosted service. You can shape this execution environment.
This article is for developers and CTOs who use AI agents and want to know what they are really tuning.
The harness is everything except the model
A model produces a response from the content it receives. That response may contain text or a tool request. It does not run a command on your machine by itself. The surrounding software receives that request and decides how to handle it.
An agent reads code, runs tests and fixes its own mistakes. The harness coordinates these exchanges with files, tools and the user.
The formula going around is simple: agent = model + harness.
The word became common in February 2026. Mitchell Hashimoto, the creator of Terraform, described how he works with agents. He wrote that he knew of no established term, and that he called it "harness engineering". OpenAI published a report under the same name a few days later.
The word also has another use.
In software testing, a test harness is the bench that runs a program to test it. Model benchmarks kept that meaning: the evaluation harness runs the model on tasks and scores the result.
In "agent harness", the meaning shifted. The harness is no longer the test bench. It is the software that runs the agent every day.
When you read "harness" in an article, first check which of the two is being described.
A bug fix, step by step
Imagine a simple request: "Fix the date calculation and check the result." Here is one possible loop:
- The harness sends your request, the project instructions and the available tool definitions to the model.
- The model requests a file. The harness checks permissions, then performs the authorized read.
- The harness adds the file contents to the context. The model then proposes a change.
- The harness applies the authorized change with its editing tool. It returns the result to the model.
- The model requests a test. The harness runs it if permissions allow, then returns the output.
- If the test fails, the loop can continue. It stops on a final response, a limit or your interruption.
The model proposes the next steps. The harness manages their execution and the session state. Software must enforce mandatory checks: the model might forget to request a test.
What is inside
I opened my own configuration to make the list. Here are the seven parts I find in it.
- The loop. It calls the model, runs the requested tool, sends the result back, and starts again.
- The tools. Read a file, run a command, search the web. Without tools, the model touches nothing.
- The context. The instructions loaded on every message, the project memory files, the skills loaded on demand.
- The permissions. What the agent can do alone, what needs your approval, what is forbidden.
- The subagents. Secondary agents with their own context. They can review code or write tests.
- The verification. Tests, linter, build, run before saying "done".
- The observation. Records of tool calls, permissions and session endings. They help explain what happened.
The orchestration relies on ordinary software. Some parts also use models, such as a subagent or a context summarizer. A small harness does not need every part.
The four forms of a harness
This is where many people get lost. What does a harness look like? It depends on who wrote it.
A product you configure. Claude Code, Cursor, Codex CLI. The loop and the tools are already there. You tune the rest: instructions, permissions, hooks, subagents. This is the most common form.
A library. Some vendors publish their harness as an SDK. Anthropic did it with the one behind Claude Code. You keep the loop and embed it in your product.
Your own code. I have a Go agent that sorts my email. Simple rules run first, then a small classifier, and the model last. The code picks the action and decides what can go out without me. All of that code is a harness.
A hosted service. The provider runs the loop, the tools and the sandbox on its servers. You send a task and get the result back.
These forms can overlap. Your application can use an SDK that calls a hosted service. Check where the loop runs, who executes the tools and which limits you can enforce.
Same model, different environment
Return to our bug fix. A tool that can read files but cannot run tests receives less feedback. Another tool may retain earlier errors and present them to the model on the next attempt.
The model can be identical. Yet the available information and actions change. Compare the model, but also the tools, context and execution limits.
Some configuration is portable. Cursor can load SKILL.md files, including those in Claude directories. Hooks, permissions and their behavior still need checking in each product. Copying a skill does not copy every execution rule.
My guardrail tests illustrate this distinction. Out of 17 destructive commands, the old script blocked 4. Its replacement blocked 17 in that same test set. That is a result for those cases, not a general guarantee.
A misresolved variable or a Python script could still get through. Permissions, isolation and backups remain complementary layers. I discuss them in the article on agent permissions.
It also decides what the agent sees
The harness chooses the information included in each call. Always loading long instructions leaves less room for files and tool results.
I learned it on a client workstation with a capped budget. The first version loaded a long instruction file and about forty skill descriptions. I brought the permanent context under 2,000 tokens. The rest loads on demand.
The model was the same before and after. I only changed what the harness showed it.
The checklist
You can shape the model's execution environment.
- [ ] List what is loaded on every message, and measure it in tokens
- [ ] Write your guardrails in hooks or permissions, not in the prompt
- [ ] Test your guardrails on a list of legitimate and dangerous commands
- [ ] Keep a backup the agent cannot modify
- [ ] Have the harness run the tests before every commit
- [ ] Log tool calls, so you can reread what the agent did
- [ ] Use a subagent when a separate task needs its own context
- [ ] When you compare two tools, note which model runs in each
What to remember
A harness can be a small loop or part of a complete product. It organizes what the model receives, what its requests trigger and what feedback it gets.
To understand yours, trace one complete task. Who loads the files? Who runs the tools? Who enforces the limits? The answers show where you can act.
Want to frame your team's agents, permissions and guardrails included? Let's talk.
Sources: Mitchell Hashimoto, My AI Adoption Journey · OpenAI, Harness engineering · Anthropic, Effective harnesses for long-running agents · Anthropic, Claude Agent SDK · Cursor, Agent Skills · cc-safety-net
Top comments (0)