Coding Agent Harness Architecture
Overview
An LLM is neither a coding agent nor a product. A coding agent product is a text generation model coupled with a harness — a runtime that repeatedly builds context, calls the model, executes tool calls, persists state, renders to the user, recovers from failures, and loops back. This guide covers the 7-layer architecture of production-grade coding agents, drawn from analysis of real codebases including Codex (OpenAI), OpenCode, Claude Code, and Cursor.
The gap between a simple loop like while :; do cat PROMPT.md | claude-code; done and what Codex or Claude Code actually ship is product engineering. That gap — context management, safety boundaries, persistence, recovery, and multi-client support — is the subject of this skill.
When to Use
- Designing agentic systems that go beyond simple prompt loops
- Analyzing agent architectures across different products (Codex, OpenCode, Claude Code, Cursor)
- Implementing harness patterns for context building, tool orchestration, or safety
- Studying production-grade coding agent implementations and their trade-offs
- Understanding the LLM provider contract (streaming events, tool calling, multi-turn state)
- Building scalable autonomous coding systems with parallelization and specialization
Core Concepts: The 7 Layers
A coding agent harness consists of 7 layers:
- Agent Loop — Conversation turns: system prompt → user → model → tools → model → ... Each turn can include hundreds of tool calls. Context management is the agent's core responsibility.
- Context Building — Gathering relevant data: which files are relevant, what's been done, style conventions. Context engineering is UX engineering — the product decides what the model sees and when.
- Tooling Systems — Tool registry with argument schemas, multi-modal support, and parameters. Examples: shell, file edit, code search, browser automation, screenshot analysis.
- Safety — Allowlists/denylists, sandboxing, snapshotting, recovery. Safety is architecture — approvals, policies, sandboxes, and undo.
- Replay / Persistence — Forking chats and environments for debugging. Systems are made of turns, tool calls, diffs, approvals, and events that must be restorable.
- Client Surface (TUI / Web / IDE) — How the user interacts: TUI (OpenCode, Claude Code, Codex), IDE (Cursor, Antigravity, Replit Agent), or Web (Bolt.new, v0, Lovable).
- Extensibility — MCP for tool connectivity, AGENTS.md for repo-specific instructions, Skills for Anthropic's convention, and Open Responses for provider-agnostic API shape.
Capability Jumps
Four major jumps in AI capability from a user's perspective:
- GPT-3.5 (ChatGPT, November 2022) — the leap was the product itself, not just the model
- GPT-4 (Spring 2023)
- Reasoning models (o1-preview, then o3 in Spring 2025)
- Actually useful agentic systems (late 2025, strong reasoning models paired with solid harnesses)
Advanced Topics
Harness Fundamentals: The simplest agent loop, ralph wiggum pattern, and why it breaks at scale → Harness Fundamentals
Context Engineering: Prompt architecture, AGENTS.md patterns, OpenAI's lessons on context management → Context Engineering
Tooling Systems: Tool registries, compiled vs dynamic tool handlers, Codex orchestrator vs OpenCode plugins → Tooling Systems
Safety and Persistence: Allowlists, sandboxing, AST-based command analysis, replay architecture → Safety and Persistence
Client Surfaces and Extensibility: TUI vs Web vs IDE patterns, MCP integration, Skills, plugin systems → Client Surfaces and Extensibility
LLM Provider Contract: Streaming events (SSE), three-phase tool call lifecycle, multi-turn thread state, portability → LLM Provider Contract
Harness Deep Dive: Codex (Rust monolith) vs OpenCode (TS/Bun control-plane) architecture comparison across all 7 layers → Harness Deep Dive
Scaling Case Study: Anthropic's C compiler case study — parallel Claude agents, git-based coordination, lessons learned → Scaling Case Study
1---2name: agent-nirzabari-0-1-03description: Comprehensive guide to understanding and building coding agent harnesses, covering 7-layer architecture, context engineering, tool orchestration, safety systems, and real-world implementations from Codex, OpenCode, Cursor, and Claude Code. Use when designing agentic systems, analyzing agent architectures, or studying production-grade coding agent implementations.4---56# Coding Agent Harness Architecture78## Overview910An LLM is neither a coding agent nor a product. A coding agent product is a text generation model coupled with a **harness** — a runtime that repeatedly builds context, calls the model, executes tool calls, persists state, renders to the user, recovers from failures, and loops back. This guide covers the 7-layer architecture of production-grade coding agents, drawn from analysis of real codebases including Codex (OpenAI), OpenCode, Claude Code, and Cursor.1112The gap between a simple loop like `while :; do cat PROMPT.md | claude-code; done` and what Codex or Claude Code actually ship is **product engineering**. That gap — context management, safety boundaries, persistence, recovery, and multi-client support — is the subject of this skill.1314## When to Use1516- Designing agentic systems that go beyond simple prompt loops17- Analyzing agent architectures across different products (Codex, OpenCode, Claude Code, Cursor)18- Implementing harness patterns for context building, tool orchestration, or safety19- Studying production-grade coding agent implementations and their trade-offs20- Understanding the LLM provider contract (streaming events, tool calling, multi-turn state)21- Building scalable autonomous coding systems with parallelization and specialization2223## Core Concepts: The 7 Layers2425A coding agent harness consists of 7 layers:26271. **Agent Loop** — Conversation turns: system prompt → user → model → tools → model → ... Each turn can include hundreds of tool calls. Context management is the agent's core responsibility.282. **Context Building** — Gathering relevant data: which files are relevant, what's been done, style conventions. Context engineering is UX engineering — the product decides what the model sees and when.293. **Tooling Systems** — Tool registry with argument schemas, multi-modal support, and parameters. Examples: shell, file edit, code search, browser automation, screenshot analysis.304. **Safety** — Allowlists/denylists, sandboxing, snapshotting, recovery. Safety is architecture — approvals, policies, sandboxes, and undo.315. **Replay / Persistence** — Forking chats and environments for debugging. Systems are made of turns, tool calls, diffs, approvals, and events that must be restorable.326. **Client Surface (TUI / Web / IDE)** — How the user interacts: TUI (OpenCode, Claude Code, Codex), IDE (Cursor, Antigravity, Replit Agent), or Web (Bolt.new, v0, Lovable).337. **Extensibility** — MCP for tool connectivity, AGENTS.md for repo-specific instructions, Skills for Anthropic's convention, and Open Responses for provider-agnostic API shape.3435## Capability Jumps3637Four major jumps in AI capability from a user's perspective:38391. **GPT-3.5** (ChatGPT, November 2022) — the leap was the product itself, not just the model402. **GPT-4** (Spring 2023)413. **Reasoning models** (o1-preview, then o3 in Spring 2025)424. **Actually useful agentic systems** (late 2025, strong reasoning models paired with solid harnesses)4344## Advanced Topics4546**Harness Fundamentals**: The simplest agent loop, ralph wiggum pattern, and why it breaks at scale → [Harness Fundamentals](reference/01-harness-fundamentals.md)4748**Context Engineering**: Prompt architecture, AGENTS.md patterns, OpenAI's lessons on context management → [Context Engineering](reference/02-context-engineering.md)4950**Tooling Systems**: Tool registries, compiled vs dynamic tool handlers, Codex orchestrator vs OpenCode plugins → [Tooling Systems](reference/03-tooling-systems.md)5152**Safety and Persistence**: Allowlists, sandboxing, AST-based command analysis, replay architecture → [Safety and Persistence](reference/04-safety-and-persistence.md)5354**Client Surfaces and Extensibility**: TUI vs Web vs IDE patterns, MCP integration, Skills, plugin systems → [Client Surfaces and Extensibility](reference/05-client-surfaces-and-extensibility.md)5556**LLM Provider Contract**: Streaming events (SSE), three-phase tool call lifecycle, multi-turn thread state, portability → [LLM Provider Contract](reference/06-llm-provider-contract.md)5758**Harness Deep Dive**: Codex (Rust monolith) vs OpenCode (TS/Bun control-plane) architecture comparison across all 7 layers → [Harness Deep Dive](reference/07-harness-deep-dive.md)5960**Scaling Case Study**: Anthropic's C compiler case study — parallel Claude agents, git-based coordination, lessons learned → [Scaling Case Study](reference/08-scaling-case-study.md)
tangledgroup