Anatomy of a coding harness: what makes AI coding agents work
A practical overview of the core parts of a coding harness, the principles behind reliable agent loops, and how Goose, Pi, OpenCode, and DeepSeek Harness fit into the picture.
“Coding agent” is the label we use in conversation, but the thing doing the real work is usually a coding harness: the runtime around a language model that turns text predictions into a useful loop. The model proposes; the harness decides what context the model sees, which tools exist, when actions are allowed, how results are recorded, and when to stop.
That distinction matters. Two products can use similar models and feel completely different because their harnesses make different choices about state, tools, permissions, and feedback. If you want to understand why an agent is fast, careful, brittle, or extensible, you usually need to look under the model layer.
This post is the start of a series. Here I want to map the common anatomy and principles first, then use that lens in follow-up breakdowns of four open-source harnesses:
What a coding harness actually is
A coding harness is not just a chat UI and not just a prompt. It is the system that mediates between a model and an environment: files, shells, tests, compilers, APIs, editors, and people.
At minimum, a harness has to do four things:
- Assemble context for the next model call (instructions, history, tool results, environment facts).
- Expose capabilities the model can ask to use (tools, commands, subagents, external services).
- Execute and arbitrate those requests (dispatch, permissions, sandboxing, retries, error handling).
- Persist state so the interaction can continue coherently across turns, sessions, or interfaces.
Everything else - TUI polish, IDE integration, multi-agent orchestration, plugin ecosystems - is built on top of those basics.
The core loop
Most harnesses reduce to an agent loop: call the model, interpret its output, run requested actions, feed observations back, and repeat. The details vary, but a useful way to read any implementation is to ask the same questions:
- What counts as a turn or step? One model request? One request plus all tool calls? Can the loop continue after a “stop” if tools are still pending?
- How does it terminate? Model decides, user cancels, turn/step budget is hit, a hook blocks progress, or an error escapes.
- What is retried automatically? Provider/network failures, malformed tool calls, context overflow, or nothing at all.
- Where does control live? In a simple
whileloop, in a state machine, or in an effect/event pipeline.
These choices shape behavior users feel directly. A harness with aggressive retries and compaction may recover from messy long sessions. A harness with strict step budgets and explicit approvals may feel slower but more predictable. A harness that treats malformed tool calls as recoverable data gives the model another chance; one that throws can collapse the whole run.
Context is the real product
Model quality sets a ceiling, but context assembly often determines whether an agent reaches it. A harness typically builds each request from several layers:
- System and product instructions: the base behavior, safety posture, and interface-specific rules.
- Project instructions: files like
AGENTS.md,CLAUDE.md, or repo-specific guidance that tell the agent how this codebase works. - Conversation and session history: prior messages, tool calls, tool results, summaries, and sometimes branches or forks.
- Tool descriptions and schemas: what actions are available right now, with parameter constraints the model can target.
- Environment facts: working directory, git state, open files, diagnostics, time, selected model, and runtime limits.
Good harnesses are opinionated about this assembly. They decide what is always included, what is discovered on demand, and what gets compressed when the window fills up. Compaction, memory, prompt templates, and skills are all answers to the same problem: the model needs the right information at the right moment, not all information all the time.
Tools turn text into work
Tools are where a harness meets reality. A tool boundary defines what “taking action” means: reading files, editing code, running shell commands, querying an LSP, calling an MCP server, searching docs, opening a browser, or delegating to another agent.
The important design questions are less about tool count and more about the contract:
- Interface: Are tools native functions, MCP servers, plugins, or all of the above behind one abstraction?
- Selection: Is the tool set fixed, or rebuilt per session/model/agent?
- Validation: Are arguments coerced, schema-checked, or passed through as-is?
- Execution: Do tools run inline, concurrently, in subprocesses, remotely, or in isolated environments?
- Feedback: Does the harness return raw output, structured errors, truncation/spill files, diagnostics, or follow-up hints?
This is also where many “smart” behaviors live. For example, a harness can feed compiler or linter diagnostics back into the next turn after an edit, turn large outputs into files instead of flooding context, or normalize model-mangled tool names so a near-miss call still resolves. These are not model tricks; they are harness mechanics.
Permissions and safety are part of the runtime
A coding agent is most useful when it can act, and most dangerous for the same reason. Harnesses handle this tension with policy layers: allow, ask, deny rules; approval prompts; sandbox boundaries; environment-variable filtering; path restrictions; and hooks that can inspect or block actions.
A practical permission model usually answers:
- What is allowed by default? Reading files, writing files, network access, shell execution.
- What scope does a decision have? Once, for this session, for this project, or always.
- Who can override whom? User choice, project config, agent mode, enterprise policy.
- Is enforcement centralized? One gate before execution is easier to reason about than scattered checks.
Permission design is inseparable from UX. If everything asks, people stop reading prompts. If nothing asks, people stop trusting the agent. The harness has to make risk legible.
State, persistence, and observability
A single prompt-response pair is easy; long-running work is where harnesses earn their keep. Sessions may need to survive restarts, support undo/redo, branch or fork, stream progress to multiple interfaces, or hand work to subagents.
Common persistence patterns include:
- In-memory conversation state for short-lived runs.
- Session files or databases for resumable history.
- Append-only event logs that make replay, auditing, and projection possible.
- Snapshots and summaries for compaction, checkpoints, or recovery.
Observability follows from the same design. If a harness records structured events (messages, tool calls, results, permissions, retries, compaction), it becomes easier to debug failures, render live UIs, and build higher-level automation on top.
Extensibility: where harnesses diverge
The biggest differences between harnesses often show up in their extension model:
- Configuration-first: users customize prompts, rules, providers, and tool servers.
- Plugin/extension APIs: users add behavior in code (hooks, commands, UI, custom tools).
- Protocol-first: capabilities arrive through a standard like MCP, so the agent mostly acts as a client.
- Composition-first: the whole application is assembled from swappable parts or bundles.
There is no universally correct choice. A minimal core can be easier to understand and bend. A protocol-heavy system can be more interoperable. A deeply structured runtime can enforce stronger invariants. Each approach trades simplicity, power, and portability differently.
Principles that make a harness work
Across implementations, a few principles show up again and again:
- Close the feedback loop: tool results, test output, and diagnostics should flow back into the next decision quickly.
- Keep actions legible: the system should make it clear what the agent did, what it wants to do next, and why.
- Bound autonomy: timeouts, turn limits, approvals, and scoped permissions keep failures contained.
- Prefer recoverable errors: when possible, turn failures into information the loop can use instead of hard crashes.
- Treat context as a budget: select, summarize, and structure information deliberately.
- Separate concerns: model reasoning, tool execution, persistence, and UI are easier to evolve when they are not tangled.
The series ahead
With this anatomy in mind, the next posts will break down each harness through the same lens:
- Goose: an MCP-native, extension-driven harness with a strong approval model and an agent loop that is actively migrating toward an effect-sourced state machine.
- Pi: a minimal, highly extensible harness that treats customization surfaces (extensions, skills, packages, RPC/SDK) as core product design.
- OpenCode: a dual-runtime coding agent with session persistence, model-adaptive tooling, and LSP feedback wired into the edit loop.
- DeepSeek Harness: an “everything is a plugin” system built on Cordis, where composition, durable session events, and capability seams define the architecture.
The goal is not to crown a winner. It is to make the design space visible: once you can name the parts, it becomes much easier to evaluate agent tools, debug them, and choose the tradeoffs that fit the way you work.
Sources
- Goose repository and Goose architecture docs
- Pi repository, How Pi Works, and Pi docs
- OpenCode repository, OpenCode docs, and Agent Harness Anatomy: OpenCode
- DeepSeek Harness repository and architecture docs
Weekly series
Read the posts in order:
- Adding a blog to my personal site (without starting over) - 2026-11-11
- Why PostHog is one of the first tools I add to a new product - 2026-11-18
- Anatomy of a coding harness: what makes AI coding agents work (this post) - 2026-11-11
- Context management in coding harnesses: what gets sent, and why it matters - 2026-11-18
- Goose under the hood: an MCP-native harness with a protocol at the center - 2026-11-11
- Pi under the hood: a minimal harness built around session trees and primitives - 2026-11-18
- OpenCode under the hood: one loop, many models, real environment feedback - 2026-11-11
- DeepSeek Harness under the hood: everything is a plugin, and the log is the contract - 2026-11-18
Previous: Why PostHog is one of the first tools I add to a new product Next: Context management in coding harnesses: what gets sent, and why it matters