Agent Harness Architecture

A harness is the product/runtime shell around a model: it owns instructions, context assembly, tools, skills, approvals, memory surfaces, filesystem/editor access, and proof collection.

Open this page when comparing coding-agent or personal-agent environments. Use Agent Runtime Architecture for the internal execution loop of one run, and Agent Control Plane Architecture for provisioning and governing many workers.

Boundary

The harness is not the model and not merely the UI. It is the layer that turns model output into controlled work.

Layer	Owns	Examples
Model	Inference and token generation	GPT, Claude, Gemini, Hermes models
Harness	Rules, context, skills, tools, permissions, workspace, approvals, proof	Cursor, Claude Code, Codex, Hermes Agent, OpenClaw
Runtime	Step execution, tool dispatch, state, trace, resume semantics	LangGraph runner, OpenAI Agents SDK runner, Codex session loop, Hermes `AIAgent`
Control plane	Fleet lifecycle, routing, credentials, schedules, dashboards, billing	Agent Machines, managed agent platforms

Harness Components

Component	Contract
Instruction stack	Loads system rules, repo docs, skill summaries, memory, and task context in a deterministic order.
Workspace adapter	Gives the agent files, terminal, editor buffers, browser, remote machine, or chat channels.
Tool bridge	Normalizes built-in tools, MCP servers, CLIs, browser control, and external APIs.
Skill loader	Selects procedural `SKILL.md` guidance without dumping every skill into context.
Permission gate	Blocks or asks before destructive shell, file, network, credential, or user-impacting actions.
State and memory surface	Persists sessions, summaries, user facts, traces, artifacts, and learned procedures.
Proof loop	Runs tests, doctors, screenshots, qmd queries, or human review before declaring completion.

Harness Comparison

Harness	Center of gravity	State model	Tool/skill model	Best use
Cursor Harness	IDE-native coding and project context	Workspace/editor state plus rules and MCPs	Cursor rules, MCPs, skills bridge	Fast interactive repo work
Claude Code Harness	Terminal coding agent with strong repo rules	Shell session, working tree, hooks, subagents	Skills, hooks, commands, repo docs	Deep codebase work and review loops
Codex Harness (OpenAI)	Codex desktop/API coding threads	Thread/workspace state, tool sessions, local commands	Skills, MCP/apps, browser/computer tools	Background coding, wiki maintenance, multi-step local work
Hermes Harness (Nous Research)	Persistent self-hosted personal runtime	SQLite sessions, memory files, skills, cron, messaging	AgentSkills, MCP, memory/context plugins	Long-lived personal agent on a machine
OpenClaw Harness	Local-first multi-channel assistant gateway	Gateway daemon, JSONL transcripts, nodes, channels	AgentSkills, MCP, hooks, sandbox modes	Messaging/channel gateway and personal assistant routing
LLM Wiki Agent Harness	Canonical second brain projected into all runtimes	Markdown/qmd/wiki logs, skills source tree, generated packs, config projections	Skills, routing pages, doctors, qmd, agent-docs packs	Keeping every harness grounded in the same memory and procedures
CoTCodec Harness Architecture	Evaluation harness for orchestration variables	Experiment configs, traces, metrics, adapters	Benchmark plugins and routing policies	Researching agent orchestration variables

Invariants

Harness configuration must be source-controlled or explicitly discoverable.
Tool authority must be narrower than model imagination.
Skills must be progressively disclosed.
Destructive actions need permission gates and recoverable state.
Memory writes need provenance and conflict handling.
Completion needs proof, not just a fluent final answer.
Cross-harness shared skills should live in the canonical skill source tree and project through runtime links.

Kevin Stack

Kevin's current architecture treats harnesses as interchangeable shells over a shared brain:

kevin-wiki owns persistent knowledge, skills, and protocols.
LLM Wiki Agent Harness is the explicit architecture for that shared brain: the wiki remains the durable memory and each runtime gets a projection.
skills/.runtime/all and ~/.agents/skills project skill truth across harnesses.
config/codex/, config/claude/, config/cursor/, and related projections tune each harness without forking the brain.
Agent Machines turns long-lived harnesses such as Hermes/OpenClaw/Claude Code/Codex into routable machine workers.
Generated Surface Contract keeps generated packs, registries, and qmd indexes downstream of source pages.

Failure Modes

Failure	Cause	Fix
Agent acts outside policy	Harness loads vague or stale instructions	Source-control rules, regenerate projections, run doctors
Skill bloat pollutes context	Harness eagerly loads every playbook	Progressive disclosure and resolver summaries
Tool call becomes unsafe side effect	Permissions are implicit	Explicit approval gates, sandbox defaults, idempotency keys
Memory drifts across harnesses	Each harness stores its own truth	Write back to wiki or canonical skill source, then project out
Brain becomes a runtime cache	Runtime-local memory is treated as authority	Promote durable facts into wiki pages, skills, config, generated packs, qmd, and logs
Work cannot be audited	No trace, command log, or validation record	Proof-carrying work contract and durable logs

Timeline

2026-07-01 | Added LLM Wiki Agent Harness as the shared-brain harness boundary after the Hermes scan clarified the split between runtime-local memory and Kevin-Wiki as canonical memory. Source: User request, 2026-07-01; Hermes docs/repo scan
2026-07-01 | Created as the missing family architecture page connecting Claude Code, Codex, Cursor, Hermes, OpenClaw, CoTCodec, Agent Machines, and the cross-agent skill/config projection model. Source: User request, 2026-07-01

Source: User request, 2026-07-01; Hermes docs/repo scan