An agent harness is the runtime layer that wraps an LLM and gives it skills, persistent memory, lifecycle hooks, and multi-agent routing. Claude Code, Codex, and OpenCode are all harnesses -- not models. Building your own means configuring four pillars: system prompt, tools, context, and subagents. Here is the practical guide for 2026.
I built my first proper agent harness in early 2026 by accident. I was trying to make Claude Code remember context between sessions, enforce consistent behavior across brand workflows, and hand off sub-tasks to a second agent without losing state. What I ended up building was not a smarter prompt -- it was an architecture. This is the guide I wish existed before I started.
What Is an Agent Harness?
An agent harness is the software layer between your LLM and the world. It owns the tool registry, context management, memory persistence, lifecycle hooks, and subagent coordination. None of these capabilities live in the model itself -- they live in the infrastructure wrapped around it. A harness is what lets an AI agent take deterministic, reproducible actions across sessions.
When you compare Claude Code, OpenCode, and Codex in 2026, you are not comparing models. You are comparing harnesses. Claude Code wraps Claude Opus 4.7 in a TypeScript harness with 29 documented lifecycle events, each hookable with shell scripts the model cannot skip, per MindStudio's architecture breakdown. OpenCode uses a Go-based TUI talking HTTP to a Bun server -- model-agnostic, 75+ provider support. Codex wraps GPT-4.1 in a Rust CLI integrated with GitHub, Slack, and cloud sandboxes for async delegation. Same underlying model families. Very different harnesses.
As of May 2026, nine terminal-native AI coding agents compete per the agents-radar weekly digest. Claude Code leads production usage -- over 10% of all public GitHub commits, peaking at 326,000 commits per day in March 2026, per comparative analysis from Medium and Morph LLM. OpenCode leads GitHub stars at over 160,000 with 2.5 million monthly active developers. The gap between the two is not model quality. It is harness depth.
The Four Pillars of Any Production Harness
Every reliable agent harness runs on four components: a system prompt defining the agent's behavioral contract, a tool registry giving the agent actions to take, a context manager controlling what the agent sees at session start, and a subagent layer for delegating work to parallel specialists. All four are required. Miss one and you get an expensive autocomplete that forgets everything overnight.
Pillar 1 -- System Prompt. Your system prompt is the behavioral contract between you and the agent. In Claude Code, this lives in CLAUDE.md files -- ~/.claude/CLAUDE.md globally and in the repo root for project-local rules. The official Claude Code documentation is explicit: keep CLAUDE.md under 60 lines of universally applicable instructions. Longer system prompts dilute attention across the context window. Domain-specific behavior belongs in skills. Your system prompt should cover the agent's role, the priority order for conflicting instructions, and hard non-negotiable rules.
Pillar 2 -- Tool Registry (MCP). Tools are how your agent acts. The Model Context Protocol is the 2026 standard for connecting agents to external services -- file systems, databases, APIs, browsers, custom scripts. Every MCP tool needs a clear name, a tight input schema, and a description the model can reason about. Vague descriptions produce vague tool use. In Claude Code, MCP servers are declared in .claude/settings.json. Keep your registry lean -- every tool you add widens the action space and multiplies unexpected behavior.
Pillar 3 -- Context Manager (Memory Layer). Context is what the model sees at session start. Solo AI tools give the model conversation history and some file contents. A harness manages context deliberately: you decide what loads, what stays compressed, and what persists across sessions. The working pattern is semantic path memory -- markdown files at structured paths like memory/user/role.md or memory/project/architecture.md. The agent reads a memory index on SessionStart and loads only what is relevant to the current task. The core rule from Towards Data Science research on unified agentic memory: merge, never append. Each semantic path is a living document. A log grows unbounded; a merged document stays searchable.
Pillar 4 -- Subagent Orchestration. A single agent has one context window. When tasks exceed that window or need parallel execution, you need subagents. Anthropic shipped Managed Agents in public beta in April 2026 -- a REST API handling the harness loop, tool execution, sandbox containers, and state persistence. Pricing is standard token costs plus $0.08 per session-hour, per MindStudio's Code with Claude breakdown. The API supports up to 20 parallel specialist agents per orchestration run.
How to Wire Skills Into Your Harness
Skills are the modularity layer of a harness. Instead of stuffing every instruction into CLAUDE.md, you write standalone skill files -- each focused on one task or domain -- and load them only when needed. This keeps the active context window small and agent behavior predictable across hundreds of sessions without hand-holding every run.
A skill file has three parts: a name and description in YAML frontmatter (used for routing and discoverability), a role definition describing what the agent becomes when the skill is active, and a workflow or checklist the agent follows step by step. On Claude Code, the Skill tool loads the file and the agent reads it as a runbook for the current task.
The GitHub repo agent-skills-for-context-engineering catalogs production patterns: research analyst skills, debugging skills, deployment skills, QA review skills. Every pattern is the same -- small, self-contained, chain-able skill files. You invoke a debugging skill when a build fails, then invoke a review skill after the fix. The harness handles sequencing. You do not micromanage the model.
Keep skills in .claude/skills/ in your project root for project-specific skills and ~/.claude/skills/ for global skills across all your projects. Name them after what they do: research-analyst.md, code-reviewer.md, deploy-checklist.md. Add a trigger field to the YAML frontmatter listing phrases that should activate the skill. Your routing layer pattern-matches user intent against triggers and loads the right skill automatically.
Want the templates from this tutorial?
I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.
Join Free on Skool
Hooks: The Lifecycle Gates That Make Agents Predictable
Hooks are shell scripts that fire at specific lifecycle events in your harness. They enforce deterministic behavior -- blocking tool calls before execution, validating outputs after, running tests automatically. The model cannot skip hooks. This is the mechanism that separates a production harness from a demo that works until it does not.
Claude Code exposes seven canonical hook events per the official harness documentation: SessionStart (fires once at conversation start), UserPromptSubmit (fires before the model processes input), PreToolUse (fires before any tool call and can block it by returning non-zero), PostToolUse (fires after tool execution and can validate results), Stop (fires when the model finishes a response), SubagentStart, and SubagentStop. Each hook receives the event payload as JSON on stdin. Your shell script reads it, runs whatever check you need, and exits with 0 (allow) or non-zero (block).
Practical examples: a PreToolUse hook that blocks any bash command containing rm -rf before it executes. A PostToolUse hook that runs your test suite after every file edit and returns non-zero if coverage drops below threshold. The model does not decide whether to run tests. The hook runs them every time. That enforceability is the point -- you are not trusting the model to remember your rules, you are wiring them into the execution layer.
Addy Osmani's write-up on agent harness engineering describes the composability pattern: stack hooks into dispatchers (one dispatcher handles a family of related hooks), dispatchers into skills, skills into agents, agents into workflows. This hierarchy is how mature production harnesses enforce constraints at scale without bloating the system prompt.
Building Your Memory Layer
Memory is the hardest part of harness engineering to get right. Most harnesses have either no persistence across sessions or naively append everything to a single log until the agent drowns in stale context. The solution is a tiered memory architecture with deliberate write patterns designed to stay compact and searchable over time.
Tier 1 is working memory -- the current session's context window. The harness manages this automatically; no special action needed. Tier 2 is daily memory -- a file like memory/daily/2026-05-26.md that captures what happened today: decisions made, tasks completed, open loops. The agent writes to this via PostToolUse and Stop hooks at the end of each session. Tier 3 is core memory -- semantic path files like memory/user/role.md and memory/project/architecture.md. These evolve slowly and hold the permanent knowledge the agent needs across all sessions.
The critical rule at Tier 3: merge, never append. When the agent learns something new about project architecture, it updates architecture.md in place rather than appending a new entry. A memory index file at memory/MEMORY.md lists every Tier 3 file with a one-line summary. The agent reads the index on SessionStart and loads only what is relevant to the current task. This keeps context load fast even as your memory system grows over months.
CowAgent, an open-source harness on GitHub, automates this with nightly distillation -- a process that reviews daily memory, extracts patterns, and promotes durable findings to core memory. Anthropic's Dreaming feature (available via the Managed Agents API) takes the same approach: it runs between sessions, reviews past transcripts, prunes stale memories, and surfaces patterns no single session could find. Harvey, the legal AI platform, reported a 6x task completion improvement after enabling Dreaming in production, per VentureBeat's May 2026 coverage of the Anthropic announcement.
Subagent Orchestration: When One Context Window Is Not Enough
Single-agent harnesses hit a ceiling when tasks require parallel execution or exceed the context window. The orchestration pattern that works in production: one coordinator agent receives the task, breaks it into sub-tasks, spawns specialist subagents for each, and synthesizes the results. The coordinator owns the memory layer. Subagents write structured outputs back to shared context so the coordinator has a complete picture.
Anthropic's Managed Agents API (public beta, April 2026) handles this at the infrastructure level. You define coordinator and specialist agents, wire them through the REST API, and the API manages tool execution, sandboxes, and state persistence. It supports up to 20 parallel specialist agents per orchestration run at $0.08 per session-hour per agent. For teams scaling past individual developer productivity into fully autonomous workflows, this is the current production path on Anthropic's infrastructure.
The failure mode to watch: context inconsistency between subagents. Each subagent has its own context window, and unless you are deliberate about what each one receives, they produce conflicting outputs. The fix is a shared context object -- a structured JSON or markdown document the coordinator passes into each subagent's context at spawn time. The subagent reads it, completes its task, returns a structured result. No freeform handoffs. Structured contracts between agents prevent drift.
For open-source orchestration without the Managed Agents API: CrewAI implements per-agent short-term, long-term, and entity memory with built-in coordination patterns. AutoGen (Microsoft's open-source multi-agent framework) offers an AgentChat API for high-level patterns and a Core API for fine-grained control over agent interactions. Both are production-ready in 2026. The coordinator-specialist-shared-context architecture applies regardless of which framework you use.
FAQ
What is the difference between an agent harness and an AI coding assistant?
An AI coding assistant like GitHub Copilot suggests code inside your editor -- you accept or reject each suggestion. An agent harness wraps an LLM with tools, memory, hooks, and multi-agent coordination so it can take autonomous actions: reading files, running commands, committing code, calling APIs. Claude Code, Codex CLI, and OpenCode are harnesses. GitHub Copilot's autocomplete is an assistant. The harness executes; the assistant suggests.
How long does it take to build a basic agent harness?
A basic harness -- CLAUDE.md system prompt under 60 lines, two or three MCP tools, semantic path memory with a daily log and a few core files, and one or two lifecycle hooks -- takes an experienced developer a weekend to assemble and a week to tune. The hard part is not the code; it is identifying which behaviors need hook enforcement versus which ones the model handles reliably without them. Start minimal.
Can I build an agent harness on OpenCode instead of Claude Code?
Yes. OpenCode is model-agnostic and supports 75+ providers through a clean HTTP interface between the TUI and the server. You can run Claude Opus 4.7, GPT-4.1, Gemini 3.1 Pro, or any local model through the same harness architecture. The tradeoff: OpenCode does not have the Anthropic-native lifecycle hook system or Managed Agents API integration. If you are building specifically on Anthropic's infrastructure, Claude Code's native harness is tighter and more complete.
How do I prevent my agent harness from taking irreversible actions?
PreToolUse hooks are your primary defense. Every destructive or irreversible action -- file deletion, git reset, production deploys, financial transactions, external sends -- gets a hook that validates the action against a policy file before executing. The model proposes the action; the hook approves or blocks it. Pair this with a hard rules section in your system prompt and an explicit permissions allowlist in your harness settings. The model should never self-authorize irreversible actions.
Want the templates from this tutorial?
I share every workflow, prompt, and template inside the free AI Creator Hub on Skool. 500+ builders sharing what actually works.
Join Free on Skool
