What Is an Agent Harness? A Developer's Map for 2026
TL;DR
An agent harness is everything around the model: loop, tools, context, sandbox. How Pi, DeepSeek, Codex and Claude Code differ, and how to choose.
An agent harness is everything that wraps a stateless model so it can do real work: the loop that calls it, the tools it can use, the context and memory it carries, the permissions and sandbox it runs in, and the logs you can replay afterwards. Two weeks of launches made the term unavoidable: Pi shipped 1.0, DeepSeek put a desktop app on its open-source harness, and OpenAI's DevDay moved Codex's loop behind an Agents API. This guide is the map: what a harness contains, the four kinds you will meet, and how to pick one.
Last updated: October 3, 2026
What a harness contains#
The broadest definition we have seen comes from Shrivu Shankar's essay The Harness Is the Company: all the "infra, interfaces, context, and state that surround a stateless LLM". Narrowly, the word means the coding agents and frameworks that wrap a model API, such as Codex, Claude Code, OpenCode or LangGraph.
Reading real harness code makes it concrete. When we read DeepSeek's source for our first look at DeepSeek Harness, the runtime was a session log, an agent loop, a tool scheduler, a sandbox, a web UI and an SDK. Earendil describes Pi as "a hardened, minimal, extensible agent harness that you can make your own". Those two sit at opposite ends of size and style, and both are the same species.
Why the harness matters as much as the model#
The same model behaves differently in different harnesses. Databricks measured one model through several coding harnesses and found cost per task varied by more than 2x at identical quality, which we covered in The Harness Is the New Cost Lever. A lot of that gap is context discipline: how many tokens the harness spends on its own system prompt and tool declarations before your task starts.
Harnesses also decide whether a long task survives. A session that runs for hours needs queueing, checkpoints, logs and cost limits, which is the argument of Long-Running Agents Need Harnesses, Not Hope.
The four kinds of harness#
| Kind | Who runs the loop | Examples | Pick it when |
|---|---|---|---|
| Open and local | You, on your machine | Pi (MIT licensed), DeepSeek Harness (open source, public preview), OpenCode | You want to read it, extend it and use any model |
| Vendor coding agents | The vendor's CLI or app | Claude Code, Codex CLI | You want a loop the model vendor maintains for its own models |
| SDKs and hosted loops | Your code or the vendor's cloud | Claude Agent SDK, Copilot SDK for Java, OpenAI Agents API | You are building an agent into a product |
| Layers above harnesses | An orchestrator over several agents | Omnigent, Herdr, Flue | You run many agents and need shared sessions, policy or a view of all of them |
For the head-to-head between the coding CLIs, start with pi vs Claude Code vs OpenCode.
What changed this fortnight#
- Pi 1.0 put MCP in the core through Codemode, a sandbox where the model writes JavaScript that calls tools, after the project spent a year arguing it did not need MCP. Details in our Pi 1.0 guide.
- DeepSeek Harness went from an open-source repository to a public-preview desktop app, with a plugin system where, per DeepSeek, everything is a plugin and Agent teams, Scheduled tasks and Voice input ship as experimental plugins.
- OpenAI said its Agents API now brings Codex's multi-agent capabilities, tool search, tool calling and context compaction into your application, with OpenAI running the infrastructure. See our DevDay recap.
The shared direction: harnesses are becoming pluggable and callable from other software, and the hosted ones take the infrastructure off your hands.
How to choose#
Ask five questions, in this order.
- Who should own the loop? If you need to audit or modify it, pick an open harness. If you want it maintained for you, pick a vendor's.
- Which models must it run? A vendor harness is built around its own models. An open one is built so you can swap them.
- How much context does it spend on itself? Measure the first request's token count with your tools loaded, not the marketing claim.
- How do you extend it? Look for extensions, plugins or MCP support, and whether tools can be deferred instead of declared up front.
- Where does it run and what can it touch? Check the sandbox and permission model before you give it a repository or credentials.
The strategy angle: will every company become a harness?#
Shankar's essay argues that every software-service business will become "a harness around a model": individuals first operate harnesses, then orchestrate them, until the harness orchestrates the people, who become part of it. His practical advice is that companies should own the top-level harness that decides what to build and reviews what comes back, and plug vendor products into specific steps.
The Hacker News discussion split. Several commenters said SaaS has survived every prediction of its death because most businesses prefer to outsource technology problems rather than manage the complexity themselves, and expected SaaS to adapt rather than fade. Others found the essay matched what they already suspected about where the field is going (discussion). It is an argument about business models, not a prediction we can verify, so treat it as a lens rather than a forecast.
What builders are saying#
- A builder on the Pi 1.0 thread is running a Slack harness for on-call and support on top of the Pi SDK, chose it over Codex for being more hackable and vendor-agnostic, and says the 1.0 release lets them simplify their architecture (Hacker News).
- On the DeepSeek Harness thread, the most useful caution was about defaults: a commenter reported telemetry on by default in the desktop build, which we could not confirm from DeepSeek's page, so check before you adopt any harness on a work machine (Hacker News).
FAQ#
What is an agent harness?#
The software around a model that turns it into an agent: the loop, tools, context handling, sandbox and logging. The model supplies the reasoning; the harness supplies everything else.
Is a harness the same as a framework?#
They overlap. A framework such as LangGraph is a library you build a loop with. A harness, in the narrow sense, is a ready-made loop such as Codex, Claude Code, OpenCode or Pi that you run or embed. Shankar's essay uses the word more broadly for all the infrastructure around the model.
Do I need to build my own?#
Usually no. Start with an existing harness and extend it. Build your own when you need control over the loop, the sandbox or the context that no existing one gives you, and read the open ones first: Pi and DeepSeek Harness are both open source.
Continue Reading#
- pi vs Claude Code vs OpenCode - the coding CLIs head to head
- Pi 1.0 Release Guide - MCP, Codemode and Pi Durable
- We Read DeepSeek Harness - what the runtime code actually says
- The Harness Is the New Cost Lever - why cost per task varies across harnesses
- Long-Running Agents Need Harnesses, Not Hope - the case for checkpoints, logs and limits
- Why Software Factories Fail - where full autonomy breaks down
Sources#
- Pi 1.0: Earendil's release post (primary)
- DeepSeek Harness: DeepSeek's page for the open-source harness and desktop app (primary)
- DevDay 2026 Recap: OpenAI's list of announcements, including the Agents API (primary)
- The Harness Is the Company: Shrivu Shankar's essay, source for the broad definition
- Hacker News: Every SaaS business will become a harness around a model: community discussion of the essay
- Hacker News: Pi 1.0 and Hacker News: DeepSeek Harness Desktop: community discussion (summarized from reads of the threads)
Get the next deep dive like this in your inbox
One email a week on Guide and the rest of the AI dev stack. Free.
Read next on AI coding tools
pi vs Claude Code vs OpenCode: Picking Your Agentic CLI
A decision-intent comparison of pi, Claude Code, OpenCode and Codex CLI as your main agentic coding harness in late 2026, with a verified capability matrix and pick-X-if verdicts.
10 min readPi 1.0 Release Guide: MCP, Codemode and Pi Durable
Pi 1.0 adds built-in MCP through Codemode, a fullscreen TUI by default and Pi Durable. What changed, how to install it, and what breaks on upgrade.
6 min readWe Read DeepSeek Harness: What 453K Lines of Agent Runtime Actually Say
DeepSeek open-sourced its agent harness today. We cloned it and read the code: a 453K-line plugin runtime on a vendored Cordis fork, three patterns worth stealing, V4 line signals hiding in the model adapter, and a 3-line BENCHMARK.md from a lab that published zero eval claims.
9 min readNew here? Start with
Technical content at the intersection of AI and development. Building with AI agents, Claude Code, and modern dev tools - then showing you exactly how it works.
