Key takeaways
- An agent harness is the software around a model that runs the agent loop: it calls the model, executes its tool calls, manages context and memory, and enforces permissions and sandboxes.
- Claude Code, the Claude Agent SDK, Claude Managed Agents, Codex CLI, Cursor's agent, OpenCode and DeepSeek Harness are all harnesses.
- In the Trial by Trace study, the same nine models passed 44.0% of tasks in Claude Code and 35.8% in Codex, an 8.2-point gap from the harness alone.
What is an agent harness, in plain terms: it is the software around an AI model that turns it into an agent. The model only reads and writes text. The harness runs the loop: it sends the model its context, carries out the tool calls the model asks for (read a file, run a command, search the web), feeds the results back, enforces permissions, manages memory and the context window, and decides where commands run. Anthropic's Claude Code docs put it in one line: Claude Code "is the layer around the model that provides the tools and manages the context the model sees," and that layer "is what the term agentic harness refers to."
The word is suddenly everywhere because the harness now matters about as much as the model. The same model can score very differently depending on the harness it runs in, and labs have started to build both together. Alibaba's Qwen4-Max launch post on November 16, 2026 says the model was built through "model-harness-product co-design."
What an agent harness does
Anthropic's engineering team gives the shortest definition in its post on Managed Agents (April 8, 2026): a harness is "the loop that calls Claude and routes Claude's tool calls to the relevant infrastructure."
In practice that loop has a handful of jobs. The Claude Code docs and the Codex docs describe the same pieces under different names:
| Job | What the harness does | Example |
|---|---|---|
| The loop | Calls the model, runs the tools it asks for, sends results back, repeats until the task is done | Claude Code's "gather context, take action, verify results" cycle |
| Tools | Defines what the model can do: read and edit files, run shell commands, search the web, call MCP servers | Claude Code's file, search, execution and web tools |
| Context management | Decides what goes into the context window and summarizes old turns when it fills up, a step called compaction | Claude Code compacts automatically as the window nears its limit |
| Memory | Loads instructions and notes that last between sessions | CLAUDE.md and AGENTS.md files |
| Permissions | Decides which actions run on their own and which need a person to approve | Claude Code's permission modes, Codex's approval policies |
| Sandbox | Limits where commands run and what they can touch | Codex's read-only, workspace-write and danger-full-access modes |
| Sessions and undo | Saves the conversation and file snapshots so work can be resumed or rolled back | Claude Code's checkpoints, resume and fork |
None of this is the model's intelligence. It's plumbing, but it decides what the model sees and what it may do.
Harness vs model vs framework
Three words get mixed up.
- The model is the trained network: Claude Opus 5.5, GPT-6.1 Sol, Qwen4-Max. Give it text, get text back. It can ask to call a tool, but it can't run one.
- The harness is a working program that wraps a model and runs the agent loop for you, with opinions built in: which tools exist, how context is trimmed, when to ask permission.
- A framework is a library of parts for building your own loop. Anthropic's guide to building effective agents says frameworks make it easy to start "by simplifying standard low-level tasks" like calling models and chaining calls, and warns that they can add layers that "obscure the underlying prompts and responses."
The line between the last two is blurry. The Claude Agent SDK gives developers "the same tools, agent loop, and context management that power Claude Code," in Python and TypeScript. When Anthropic renamed it from the Claude Code SDK in September 2025, it wrote that "the agent harness that powers Claude Code" can power other kinds of agents too.
A rough rule: if you have to write the loop, you are using a framework or an SDK. If the loop already runs and you configure it, you are using a harness.
Examples of agent harnesses
| Harness | Maker | What it is |
|---|---|---|
| Claude Code | Anthropic | Terminal, IDE, desktop and web coding agent; the docs call it an agentic harness |
| Claude Agent SDK | Anthropic | Claude Code's harness as a Python or TypeScript library |
| Claude Managed Agents | Anthropic | A hosted harness on the Claude API, in beta, with sessions in a cloud or self-hosted sandbox |
| Codex CLI | OpenAI | "A coding agent from OpenAI that runs locally on your computer," Apache-2.0 licensed |
| Cursor | Cursor | An AI code editor whose agent runs on a harness Cursor builds and tunes per model |
| OpenCode | OpenCode | "An open source coding agent" with built-in support for many model providers, MIT licensed |
| DeepSeek Harness | DeepSeek | An open-source, plugin-based harness (dsh) in developer preview, MIT licensed |
Managed Agents shows where this is going. The overview calls it a "pre-built, configurable agent harness that runs in managed infrastructure," with bash, file tools, web search and MCP built in, and Anthropic's engineering post describes it as a "meta-harness" that other harnesses can run on. It separates the "brain" (Claude and its harness) from the "hands" (the sandboxes and tools), so each can fail or be swapped on its own.
See also what DeepSeek Harness is and what it costs and what an AI agent is.
Why the same model scores differently in different harnesses
Agent benchmarks don't test a model alone. They test a model inside a harness, and the harness changes the result.
Anthropic said so plainly when it reported its SWE-bench Verified result in January 2025: an agent is "the combination of an AI model and the software scaffolding around it," and performance "can vary significantly based on this scaffolding." That's why the Terminal-Bench 4.1 leaderboard lists an Agent column next to every Model. As of November 16, 2026, its entries come from harnesses including Claude Code, Codex, Antigravity CLI, Grok Build, Muse Code and mini-swe-agent, a deliberately minimal harness.
The leaderboard also shows harnesses being mixed with other labs' models. Claude Code appears with Kimi K3.1 Pro (59.7%), GLM-5.3 (41.2%), DeepSeek V4.1 Flash 1017 (38.5%) and Qwen3.8-Max-0902 (27.0%), all at max reasoning effort. Those compare models inside one harness, not harnesses.
The cleanest harness comparison so far is academic. In "Trial by Trace," posted to arXiv in October 2026, a team at TraceLite AI ran the same nine models through four harnesses on 95 tasks. Averaged over those nine models, the task pass rate was 44.0% in Claude Code, 40.0% in DeepSeek Harness, 38.2% in OpenClaw and 35.8% in Codex. Same models, same tasks, an 8.2-point spread from the harness alone. We covered the benchmark in detail, including its limits: each combination ran once, and the team wrote the adapters itself.
Why the gap? The vendors' own engineering posts point to a few reasons:
- Tool formats. Cursor writes that it gives each model "the tool format it had during training," because an unfamiliar format "costs extra reasoning tokens and produces more mistakes."
- Tool errors. Cursor calls failed tool calls "extremely harmful to a session" and says a reliability push cut unexpected tool errors by an order of magnitude.
- Context handling. Anthropic's post on long-running agents (November 2025) had a first session set up the environment and a progress file, so each later session with a fresh context window could pick up where the last one stopped.
- Assumptions that age. Anthropic's Managed Agents post warns that "harnesses encode assumptions about what Claude can't do on its own," and those go stale. Its example: context resets helped Claude Sonnet 4.5 but were no longer needed with Claude Opus 4.5.
A score quoted without its harness is half a number.
Why labs now design the model and harness together
If the harness moves scores by several points, it makes sense to train the model for the harness it will ship in. That's the bet behind Qwen4-Max's "model-harness-product co-design," and it's what Anthropic and OpenAI already do with Claude Code and Codex. The harness also keeps changing on its own: in June 2026 Anthropic added dynamic workflows that let Claude "write its own harness on the fly" by spawning subagents for a task.
For anyone picking a coding agent, the choice is really two choices: which model, and which harness. Test the pair on your own work before trusting a leaderboard.
Frequently asked questions
Is Claude Code a harness?
Yes. Anthropic's docs say Claude Code is the layer around the model that provides the tools and manages the context the model sees, and that this layer is what the term agentic harness refers to. The Claude Agent SDK packages the same harness as a library.
Is Cursor a harness?
Cursor is an AI code editor, and its agent runs on a harness that Cursor builds itself. Cursor's April 30, 2026 post calls it "our agent harness" and says it tunes prompts and tool formats for each model.
What is the difference between an agent harness and a framework?
A framework gives you parts to build your own agent loop, such as model calls and chaining. A harness is a working program that already runs the loop, with tools, context management and permissions built in, which you configure rather than write.
Why do benchmarks list the harness?
Because agent benchmarks test a model inside a harness, and the harness changes the score. Anthropic says SWE-bench results can vary significantly with the scaffolding, and the Terminal-Bench leaderboard lists an Agent next to every model.
Sources
- How Claude Code worksAnthropic
- Scaling Managed Agents: decoupling the brain from the handsAnthropic
- Claude Managed Agents overviewAnthropic
- Agent SDK overviewAnthropic
- Building agents with the Claude Agent SDKAnthropic
- Effective harnesses for long-running agentsAnthropic
- Raising the bar on SWE-bench Verified with Claude 3.5 SonnetAnthropic
- Building effective agentsAnthropic
- A harness for every task: dynamic workflows in Claude CodeAnthropic
- openai/codexOpenAI
- Codex sandboxingOpenAI
- Continually improving our agent harnessCursor
- OpenCode docsOpenCode
- deepseek-ai/deepseek-harnessDeepSeek
- Terminal-Bench leaderboardTerminal-Bench
- Trial by Trace: Benchmarking AI Agent Harnesses for Reliability and Failure AttributionarXiv
- Qwen4-Max: Your New Teammate Has ArrivedQwen (Alibaba)

