What Is an Agent Harness? The Infrastructure Layer Behind Every AI Agent
By Tyler Cyert
If you build with AI agents, you've already used an agent harness — you just might not have called it that. An agent harness is the infrastructure layer that sits between a language model and the work it does. It manages the conversation loop, decides which tools the model can call, handles permissions, loads context files, and persists memory across sessions.
Every coding agent ships inside a harness. Claude Code is a harness. Cursor is a harness. Aider, OpenCode, Codex, Copilot Workspace — all harnesses. The model provides intelligence. The harness provides structure.
Why the Harness Matters More Than the Model
Models are increasingly interchangeable. You can swap Sonnet for GPT-5 for Gemini and get comparable results on most coding tasks. What you *can't* easily swap is the harness, because the harness owns three things the model doesn't:
- Context management. How does the system decide what the model sees? Which files get loaded, how conversation history is compressed, what survives compaction — these decisions determine whether your agent remembers what it's doing or loses the plot after 50 messages.
2. Tool orchestration. Which tools can the agent use? Can it read files, write files, run shell commands, spawn subagents? The harness controls the permission boundary. A model without tools is a chatbot.
3. Memory. What carries over between sessions? If your agent learned yesterday that your project uses Drizzle ORM instead of Prisma, does it remember today? Memory is the harness's job — and it's where lock-in lives.
The Lock-In Problem
Here's the concern that's driving the conversation around agent harnesses right now: if the harness controls your memory, switching providers means losing your accumulated context.
When you use a stateful API where conversation threads and memory live on the provider's server, you're building on rented land. Your agent gets smarter over time — but that intelligence belongs to the platform, not to you. Want to switch models? Start over.
The alternative is a harness where memory lives in files you own. Claude Code stores everything on your filesystem: CLAUDE.md in your repo, auto-memory in ~/.claude/, agent definitions as markdown files you can cat. It's not perfect, but it's portable in the ways that matter.
What a Harness Actually Contains
| Component | What It Does | Example in Claude Code |
|---|---|---|
| Conversation loop | Manages the request/response cycle with the model | The agentic loop that processes tool calls |
| Tool registry | Defines which tools exist and how they're called | Read, Write, Edit, Bash, Glob, Grep, Agent |
| Permission layer | Controls which tools the agent can use without asking | settings.json allow/deny rules + permission modes |
| Context loader | Decides what enters the model's context window | CLAUDE.md, rules, skills, agent definitions |
| Memory system | Persists information across sessions | Auto-memory at ~/.claude/projects/, agent memory |
| Extension system | Lets users add capabilities | Skills, hooks, MCP servers, plugins |
| Subagent manager | Spawns and coordinates child agents | .claude/agents/ definitions + agent teams |
Open vs Closed Harnesses
The current landscape splits roughly into two camps:
Closed harnesses keep the infrastructure behind an API. You send prompts, you get responses, but you don't control how context is managed, how memory is stored, or how tools are orchestrated. Migration means starting from zero.
Open harnesses run on your machine or your infrastructure. The configuration lives in files you own. Memory is a directory on your filesystem. Switching models means changing a config value, not rebuilding your entire setup.
Most file-based coding agents — Claude Code, OpenCode, Aider — fall on the open side. Your CLAUDE.md, agent definitions, and settings are version-controlled markdown and JSON. The agent reads them at startup. You can inspect, edit, and migrate everything.
For a comparison of specific harnesses, see our Cursor vs Claude Code and Aider vs Claude Code comparisons.
How to Evaluate a Harness
When choosing (or building on) an agent harness, ask:
- Where does memory live? On their server or on your filesystem?
- Can you export your configuration? If you leave, what do you take with you?
- Is the context management documented? Do you know what survives compaction?
- Can you swap models? Does the harness lock you to one provider?
- Who controls the tool boundary? Can you add, remove, and scope tools?
Building Portable Agent Systems
The safest approach is to treat your agent configuration as code — version-controlled, portable, and independent of any single runtime.
That means: - Agent definitions as markdown files with explicit frontmatter (name, tools, model, permissions) - Instructions in files you own (CLAUDE.md, AGENTS.md) committed to your repo - Skills as standalone packages following open standards like agentskills.io - Settings as JSON that you can read, diff, and migrate
This is the approach DotBox takes: you design your agent system visually, and we compile it into portable files that any compatible harness can read. The output is plain markdown and JSON — no vendor lock-in, no proprietary formats.
The Bottom Line
The model is the engine. The harness is the car. You can swap engines more easily than you think — but rebuilding the car is expensive. Choose a harness that puts your configuration and memory in files you control, and you'll never be stuck.