Claude Code, pi, and Hermes look different on the surface, but they're solving the same ten underlying problems — the ones that separate an agent that runs reliably for two hundred turns from a demo that quietly breaks on turn ten. These are the ten concepts worth understanding, in roughly the order you'd hit them building a harness from scratch, each with a real example and a concrete thing to build.
TL;DR
| # | Concept | What it solves |
|---|---|---|
| 1 | The agent loop | Turning a single request-response call into a repeated plan-act-observe cycle |
| 2 | Tool contracts | Giving the model a well-defined way to act on a real system |
| 3 | Permission gates | Bounding what an agent can do without asking first |
| 4 | Sandboxing | Limiting the blast radius of any single mistake |
| 5 | Streaming and partial results | Keeping a long-running turn legible while it's still in progress |
| 6 | Context budgets and compaction | Surviving a session longer than one context window |
| 7 | Persistent memory | Carrying state across sessions, not just within one |
| 8 | Checkpointing and resumability | Not losing hours of progress to a crash |
| 9 | Failure classification and retries | Distinguishing a transient error from a real dead end |
| 10 | Sub-agent orchestration | Splitting work too large for one agent's context |
1. The agent loop
Everything else on this list is a subsystem that plugs into this one. An agent loop takes a raw model call — one prompt in, one completion out — and wraps it in a repeated cycle: the model proposes an action, the harness executes it, the result gets fed back in, and the loop continues until a stop condition is met (the task is done, a budget is exhausted, or a human interrupts it). Build this first, by hand, with nothing but a message array and a while loop that keeps calling the model until it stops requesting tool calls — every other concept below only makes sense once you've felt what it's like to run that loop without any of the other nine in place.
2. Tool contracts
A model can't touch a real filesystem or terminal directly — it can only request that an action happen, described in a structured format the harness then executes and reports the result of. A tool contract is that structured schema: what parameters a read_file or run_shell_command tool takes, what it returns, and what errors look like. Getting this schema design right matters more than it sounds — a loosely specified tool invites the model to call it incorrectly in ways that are hard to debug, while an overly rigid one makes legitimate edge cases awkward to express.
3. Permission gates
Once a model can call real tools, the next question is which ones require a human's explicit approval before executing. Claude Code's permission modes are the clearest public example: read operations typically run without asking, while anything destructive — deleting a file, running an unrecognized shell command — pauses for approval by default. Getting this balance wrong in either direction breaks the product: too many prompts and the agent is unusable for real autonomous work; too few and one bad tool call can do real damage before anyone notices.
4. Sandboxing
Permission gates control whether an action runs; sandboxing controls how much damage it can do if something goes wrong anyway — a misbehaving tool call, a prompt injection, or a bug in the harness itself. This is the blast-radius problem: running an agent's shell tool inside a container or restricted environment rather than directly on a production machine, so a worst-case failure is contained rather than catastrophic. It's the same design principle explainx.ai covered in Meta Muse's Secure VM architecture and in guides to restricting Claude Desktop's own access — enforcement that doesn't depend on the model behaving correctly under pressure.
5. Streaming and partial results
A single turn in a coding agent can take tens of seconds — writing a long file, running a slow test suite — and a harness that only shows output once the whole turn finishes is a much worse experience (and much harder to debug when something goes wrong mid-turn) than one that streams tool calls and partial results into a terminal UI as they happen. This is a UX concern with real engineering weight: it requires threading partial state through the loop rather than treating a turn as one atomic black box.
6. Context budgets and compaction
Every model has a finite context window, and a long-running agent session will eventually fill it if nothing manages what stays and what gets evicted. Compaction — summarizing or dropping older parts of a conversation to make room for new work while preserving what's still relevant — is the concrete mechanism; context engineering more broadly is the discipline of deciding what enters the window on a given turn at all. Claude Code's automatic compaction around specific token thresholds is the clearest public reference implementation of this concept working at scale.
7. Persistent memory
Compaction manages state within one session; persistent memory carries it across sessions, so an agent doesn't relearn the same context from scratch every time it's invoked. The most widely adopted pattern is a file-based convention — MEMORY.md and its variants, which explainx.ai has covered in depth — where an agent writes and re-reads a small set of durable facts about a project or user rather than relying on the prompt alone to re-establish context every session.
8. Checkpointing and resumability
For any harness meant to run long, unattended tasks, the question isn't if something will crash or disconnect mid-task, it's when — and whether hours of progress survive that event. Checkpointing means saving enough state after each meaningful step (a completed tool call, a passed test) that the harness can resume from the last good point rather than starting over, and it's the single concept most often skipped in a first-pass harness build precisely because it only matters once something has already gone wrong once.
9. Failure classification and retries
Not every tool failure means the same thing, and a harness that retries everything identically wastes time on genuine dead ends while sometimes giving up too early on transient issues (a flaky network call, a momentarily locked file). Real failure classification distinguishes categories — retry-safe transient errors, errors that need a different approach entirely, and errors that should surface to a human — and routes each differently rather than treating "the tool call returned an error" as one undifferentiated case.
10. Sub-agent orchestration
Some tasks are simply too large for one agent's context window to hold end to end — a large refactor spanning dozens of files, or a task that benefits from one agent researching while another implements. Sub-agent orchestration is the pattern for splitting work across multiple agent contexts and merging the results back together, with a coordinator deciding what gets delegated and a defined handoff format for passing results between agents — the same underlying pattern Claude Code Projects extended to coordinate parallel cloud sessions rather than sub-agents inside one session.
Honest limitations
- This list orders concepts by when you'd typically hit them, not by universal importance — a short, supervised task genuinely doesn't need checkpointing or sub-agent orchestration.
- Reading about these ten concepts isn't the same as internalizing them — each one is easiest to actually understand by hitting the specific failure it solves while building, not by reading a definition.
- Production harnesses (Claude Code, pi, Hermes) implement all ten with far more nuance than a first learning pass will — treat a self-built minimal harness as a way to understand why those systems are built the way they are, not as a replacement for them in production.
How to actually build one
The fastest way to internalize all ten is to build a minimal harness yourself, in order: a hand-rolled loop first, then real tools wired to your own filesystem, a permission gate before anything destructive, streaming output, a context budget with basic compaction, a persistent memory file, checkpointed execution, retry logic with failure classification, and finally a sub-agent dispatcher for a task too big for one context. explainx.ai's what is harness engineering guide covers the conceptual map this list is drawn from in more depth. If you'd rather build it live with instructor review, the AI Builder Workshop covers the same fundamentals hands-on — see the complete AI Builder Bootcamp guide for the curriculum and schedule.
Related on explainx.ai
- What is harness engineering? The layer that turns a model into an agent
- What is an agent harness? The scaffolding layer that makes AI agents reliable
- Top 10 AI agent loops for coding workflows
- Claude Code subagents and multi-agent workflows
- Claude Code permission modes, explained
- MEMORY.md: long-term persistent memory for AI agents
- Multi-agent orchestration patterns: a complete guide
- Claude Code Projects: coordinating parallel cloud threads
- 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.