Claude Code, pi, and Hermes all call roughly the same class of model APIs underneath. What actually separates a coding agent that runs reliably for two hundred turns from a demo that quietly breaks on turn ten isn't the model — it's everything wrapped around it: the loop that keeps the agent working, the tools that let it act on a real filesystem or terminal, the context machinery that keeps a long session coherent, and the recovery systems that keep it alive when something fails. That layer now has a name in the field: harness engineering. Here's what it actually covers, how it differs from prompt and context engineering, and where to look if you want to learn it by building one yourself.
TL;DR
| Question | Answer |
|---|---|
| What is it? | The discipline of building the runtime around a model — loop, tools, permissions, context, recovery — that turns it into a working agent |
| How is it different from prompting? | Prompting is one instruction, one completion; a harness is the system a model operates inside across hundreds of turns |
| How is it different from context engineering? | Context engineering (what the model sees each turn) is one subsystem inside a harness, not the whole thing |
| Real examples | Claude Code (full-featured reference harness), pi (minimal, extensible), Hermes (Nous Research's open harness) |
| Why it matters now | Most reliability gains in agentic products increasingly come from the harness layer, not from a stronger underlying model |
| How to actually learn it | Read what an agent harness contains, then build a minimal one yourself — see the top 10 harness engineering concepts to start with |
The layer between "model" and "agent"
It's worth being precise about the distinction this term is drawing, because it's easy to conflate "the model" with "the agent" when a product works well. A model, called directly, is transactional: you send a prompt, it returns a completion, the interaction is over. An agent is something that runs a loop — plans, acts, observes the result, decides whether it's done, and repeats — potentially for hundreds of turns, minutes or hours of wall-clock time, and multiple tool calls per turn. Nothing about a raw model API gives you that loop, or the infrastructure that has to exist around it for the loop to survive contact with the real world: tool calls that fail, context windows that fill up, sessions that get interrupted, and tasks large enough that one agent can't hold the whole thing in its head at once.
Harness engineering is the name for the discipline of building that surrounding infrastructure. The core pieces, roughly in the order a builder typically hits them:
- The agent loop itself — how turns are structured, what counts as a stop condition, how streaming and partial tool results get handled.
- Tools and the execution environment — schemas that define what an agent can do (read, write, edit, run a shell command), and the sandboxing and permission gates that bound how much damage a mistake can cause.
- Context engineering — what enters the model's context window on a given turn: memory, compacted history, retrieved state. This is a real, distinct skill in its own right, but it's one subsystem inside a harness, not a separate layer sitting beside it.
- Durability and recovery — checkpointing progress so a crash doesn't lose hours of work, retry and failure-classification logic, resumable sessions.
- Orchestration — sub-agents, handoffs, and human-in-the-loop approval gates for when a single agent's context can't hold an entire task.
Why this is a distinct skill from prompt or context engineering
The field has already named two adjacent disciplines, and it's worth being precise about how harness engineering relates to both rather than treating all three as synonyms. Prompt engineering — crafting one good instruction for one good completion — was the dominant skill when interactions were transactional: one request in, one response out. It's still necessary, but it's nowhere near sufficient for a system that has to keep working across two hundred turns without a human checking every step.
Context engineering — deciding what enters the model's context window on a given turn, including memory, compaction, and retrieved state, which explainx.ai has covered in depth — is a genuinely distinct, important skill. But it answers a narrower question than harness engineering does: "what does the model see this turn," not "what is the entire system the model operates inside." A harness still needs an answer for what happens when a tool call throws an error, how a sub-agent gets dispatched and its results merged back in, and what a permission-approval flow looks like when an agent wants to run something destructive — none of which context engineering by itself addresses.
What a production harness actually contains
The clearest way to see this concretely is to look at real, public examples rather than an abstract description. Claude Code, which explainx.ai has covered extensively, is the most fully-featured reference harness publicly documented: permission modes that gate what actions require approval, hooks that run code at defined points in the loop, skills that package reusable capability, MCP for connecting external tools, distinct subagent types for delegating sub-tasks, and automatic context compaction so long sessions don't simply run out of room. None of that lives in the underlying Claude model — it's all harness.
pi takes the opposite design bet: a deliberately minimal, small-surface harness that's easy to fully understand, built to be extended rather than to arrive fully-featured. It's proof the same underlying job — loop, tools, context, recovery — doesn't require a large framework to be real; a small, legible harness can still be a genuine production agent. Hermes, from Nous Research, is a third public example with its own distinct set of design tradeoffs for the same core problems, useful precisely because comparing its choices against Claude Code's and pi's makes the design space concrete rather than abstract.
Why benchmark gains increasingly come from the harness, not the model
This is the part that makes harness engineering worth learning specifically, rather than treating it as plumbing to abstract away. The failure modes that actually break a long agentic task in practice — losing track of state across a 200-turn session, a tool call silently failing without the agent noticing, running past the context budget and forgetting an earlier constraint, a process crash with no way to resume — are runtime problems, not reasoning problems. A stronger underlying model helps at the margins, but it can't fix a harness with no checkpointing, no failure classification, and no sub-agent dispatch for tasks too large for one context window. Most of the practical gap between "an impressive demo" and "an agent a team actually trusts to run unattended overnight" lives in this layer — which is exactly why explainx.ai has tracked loop engineering, multi-agent orchestration patterns, and Claude Code's own subagent system as their own distinct topics rather than folding them all into "prompting."
The tradeoff between building your own harness and using an existing one
For production work, reaching for an existing, battle-tested harness — Claude Code, pi, Hermes, or another established agent framework — is almost always the right call, and it's worth being honest about why: each has already spent real engineering hours solving the unglamorous parts that are genuinely hard to get right the first time — streaming partial tool results into a legible UI, permission approval flows that don't annoy a user into disabling them entirely, context compaction that preserves what actually matters across a long session. Reinventing that from scratch for a production product is rarely the best use of engineering time.
Where building your own pays off is specifically as a learning exercise, not as a production strategy. Implementing a minimal loop, wiring up real tools, and hitting the exact moment a session runs out of context or a tool call fails silently is what makes Claude Code's specific design choices — why hooks exist, why skills are packaged the way they are, why compaction triggers at a particular threshold — stop being abstract documentation and start being obviously necessary, because you've already felt the problem they solve firsthand.
How to actually learn it
The fastest way to internalize why Claude Code's hooks, skills, and compaction system exist the way they do is to hit the exact problems they solve yourself, by building a minimal harness from scratch — a hand-rolled agent loop, real tool calls wired to your own filesystem, a permission gate before anything destructive, and a checkpoint system that survives a crash. explainx.ai's top 10 harness engineering concepts guide walks through exactly those building blocks in order, each with a concrete example you can implement yourself. If you'd rather learn it hands-on in a live, instructor-led format with code review, explainx.ai runs the AI Builder Workshop, covering the same agent-building fundamentals — see the complete AI Builder Bootcamp guide for the full curriculum and schedule.
Related on explainx.ai
- Top 10 harness engineering concepts every AI builder should know
- What is an agent harness? The scaffolding layer that makes AI agents reliable
- What is loop engineering for AI agents?
- Top 10 AI agent loops for coding workflows
- Claude Code subagents and multi-agent workflows
- Multi-agent orchestration patterns: a complete guide
- Oh My Pi: Mario Zechner's minimal terminal coding agent
- Hermes agent vs. OpenClaw: a comparison
- The complete AI Builder Bootcamp guide
This guide reflects publicly documented harness design patterns from Claude Code, pi, and Hermes as of September 2026. Framework internals evolve quickly — check each project's own documentation for current specifics before building against it.