Agent Harnesses: A Standard for a Word Nobody Agrees On

A commenter on Hacker News summed up the state of the term in May, under a post arguing that the agent harness belongs outside the sandbox:

Into that mess walks Daniel Warfield, who has spent the past few weeks building an open standard called Agent Harnesses. Before he can specify a harness he has to say what one is, and that turns out to be the hard part.

Two definitions, both from reputable sources

LangChain’s engineering blog puts it as an equation: agent = model + harness. The harness is the loop, the tool dispatch, the state management. It’s the code that turns a text-in-text-out model into something that does things.

Anthropic’s engineering team uses the word for a layer above that. Their post on effective harnesses for long-running agents describes an initializer agent plus a coding agent that makes incremental progress each session and leaves artifacts for the next one, all built on the Claude Agent SDK. There, the harness is the structure you wrap around an already-existing agent to point it at one job.

Same three syllables, opposite direction. Under LangChain’s definition the harness makes the agent; under Anthropic’s the agent comes first and the harness aims it.

Warfield takes the second, and his reasoning is sound: “agent” already has a definition, and spending a second word on it is wasteful. He lands on:

A harness is information and tools that allow a general purpose agentic system to do specific, complex tasks in a repeatable and maintainable manner.

In practice, that means a directory.

The format

A harness is a folder with a HARNESS.md at the root and whatever top-level subdirectories the domain calls for. HARNESS.md carries name and description frontmatter plus a deliberately short body, and it gets loaded in full on every activation. The spec is blunt about why brevity matters: every token in that body competes with task context.

Below the root, each top-level directory gets a routing file named after it in all caps. tools/ gets TOOLS.md, data/ gets DATA.md, and the name propagates all the way down the subtree, so tools/database/ also has a TOOLS.md rather than a DATABASE.md.

my-harness/
├── HARNESS.md
├── .leaf-detectors
├── tools/
│   ├── TOOLS.md
│   ├── database/
│   │   ├── TOOLS.md
│   │   └── query-database/
│   └── files/
│       └── TOOLS.md
└── data/
    ├── DATA.md
    └── schemas/
        └── DATA.md

A routing file answers exactly one question: should I look in here? The agent reads a branch summary instead of opening every file in it.

The termination mechanism is the part I like most. A .harnessleaf file marks a directory as a stopping point, and a root-level .leaf-detectors file declares patterns that do it automatically, in a one-line-per-rule format:

skill=SKILL.md

That line means any directory containing a SKILL.md is a skill leaf: load and execute it, don’t wander into its scripts/ and assets/. There are no built-in patterns, so a harness that bundles Agent Skills has to say so explicitly. Given how much of context engineering is preventing agents from reading things they shouldn’t, having a declared boundary beats hoping the model exercises restraint.

Getting started is one command. pip install agentharnesses-cli, then ahar init, which scaffolds HARNESS.md, skills/, references/, and a .claude/settings.json that registers the harness as a Claude Code plugin. The default preset also clones a metaskill that teaches Claude to explore the harness progressively. Then you tell Claude to load the harness. ahar validate and ahar prompt handle checking structure and rendering the whole thing as prompt XML.

The naming problem is real

Look at how the word gets used by everyone else. On Hacker News this year: Zot, a coding agent harness. pu.sh, a coding-agent harness in 400 lines of shell. peerd, an agent harness that runs in the browser. Every one of them means the runtime.

The May arXiv paper asking whether grep is all you need for agentic search is the clearest case. It compares “a custom agent harness (Chronos)” against “provider-native CLI harnesses (Claude Code, Codex, and Gemini CLI)”. That’s LangChain’s definition, in a peer-reviewable venue, treating Claude Code itself as the harness. Its finding is worth sitting with anyway: grep generally beat vector retrieval, and accuracy depended heavily on which harness and tool-calling style was used even when the underlying data was identical. Structure around the model matters. The industry just hasn’t settled on what to call it.

Meanwhile, when a founder posted about building agents without harness engineering on 11 June, his own list of what harness engineering covers was “the agent loop, session management, tools, memory, skills, automations, sandboxed deployment, and self-learning.” Infrastructure, all of it. A commenter’s reply was fair: “effectively they’re deferring harness engineering onto another developer?”

So Warfield is proposing a spec for the minority reading of a word that a majority uses differently. Agent Skills had it easier, because “skill” was mostly unclaimed when Anthropic shipped the format.

Worth using anyway

Strip the word off and what’s left is a small, clear convention for organising the markdown that an agent role needs, with an explicit answer to the question of when to stop reading. The repo went up on 15 June and Warfield says the concrete isn’t dry, which is the right time to argue with it. Two things I’d push on: the routing-file naming rule (deriving the name from the top-level directory rather than the local one is clever, and it will confuse every human who opens the tree), and versioning, currently just a recommendation to use git and pin skills by directory.

One caution. A harness is a pile of instructions your agent loads and follows without review, which is the same trust model that makes prompt injection through ordinary-looking repo content work. A portable, shareable harness format is a portable, shareable instruction-injection format. Read harnesses you didn’t write before you ahar init next to them.

Sources: Agent Harnesses standard · Specification · CLI docs · Agent Harnesses — Intuitively and Exhaustively Explained (Daniel Warfield, 16 June 2026) · Agent Harnesses with Claude · How to build a custom agent harness (LangChain) · Effective harnesses for long-running agents (Anthropic) · Is grep all you need? (arXiv 2605.15184) · HN: The agent harness belongs outside the sandbox · HN: Building agents without harness engineering · agentharnesses/agentharnesses on GitHub