You open Claude Code, or flip GitHub Copilot into agent mode, type one sentence, and watch it read four files, edit two of them, run your test suite, and fix the failure it just caused, all without you touching the keyboard again. It feels like magic.
Most explanations of "how this actually works" fall into one of two camps. Either it gets waved off as "it's just AI now," or it jumps straight into vector databases and embeddings, which isn't actually the piece doing the work here. Both explanations skip the one layer that turns a language model into something that can act.
There are exactly three layers between "a language model" and "a tool that edits your codebase unattended." Once you can name them, Copilot and Claude Code stop looking like magic and start looking like software you could build yourself, which is exactly what the rest of this series is going to do, starting with the smallest working version in about 80 lines of TypeScript.
What is an agent harness, anyway?
"Agent harness" isn't a standardized term. Nobody voted on it, and you won't find it in a spec anywhere. It's the term this series uses because it's descriptive, and because it's the same word the team behind one of the most-used coding agents around uses for their own system: Anthropic's engineering blog describes how the Claude Code team builds "a harness for every task" to orchestrate its agents.
A harness is the code that sits between a model and the outside world. It isn't the model. It isn't the chat window. It's the part that decides what the model is allowed to touch, hands it tools, catches what it asks for, actually executes it, and feeds the result back in, on repeat, until the task is done.
Strip away the branding and Copilot, Claude Code, and Cursor collapse into one shape: a capable model, wrapped in a harness that gives it a loop, a set of permissions, and some form of memory. Different vendors, different interfaces, three identical parts underneath.
To see why the harness is the interesting part, and not the model, walk through the three layers one at a time.
Layer one: the chatbot
A plain chatbot is a language model in a request-response loop you drive by hand: you send text, it sends text back. It can't check anything, run anything, or change anything. Ask it "what's in this file right now" and it can only guess, based on whatever you happened to paste into the conversation. It can't go look.
This is the layer most people mean when they say "I asked ChatGPT." Genuinely useful for drafting, explaining, and brainstorming. Structurally, though, it's a one-way pipe: text in, text out, no side effects.
Layer two: the tool-calling LLM
Now give the model a menu of things it's allowed to ask for. This is what the industry calls tool calling or function calling: alongside your prompt, you send a list of tools the model can request, each described with a name, a plain-language description, and a schema for its arguments. OpenAI's own documentation lays out the flow in five steps: send the model a request along with the tools it could call, receive a tool call back, execute it on your end, send the result back to the model, then get a final answer (or another tool call).
That third step, "execute it on your end," is the part most beginner explanations skip past. You might assume the model runs the code itself. It doesn't. A tool-calling LLM can only ask: "I'd like to call read_file with path: src/index.ts." It has no hands. Something else has to actually open that file, actually run that shell command, actually hit that API, and hand the result back in a format the model can read.
That something else is the harness.
Layer three: the harness
This is the part that turns a model that can only ask for things into a system that can actually get things done.
A harness itself is just a loop, and not a complicated one: send the model the conversation so far plus the tool list, read what it asks for, execute it, append the result to the conversation, send it back, repeat. Anthropic's own description of what separates an "agent" from a scripted workflow matches this almost exactly. In their framing, workflows are systems where the code paths are decided in advance; agents are systems "where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks." Their blunter summary of what that looks like in practice: agents "are typically just LLMs using tools based on environmental feedback in a loop."
That's it. No separate reasoning engine bolted on the side. No second model secretly supervising the first (usually). Just a loop, plus two responsibilities that turn "a loop" into "something you'd trust near your codebase":
Permissions. The harness decides what the model can do without asking, and what needs a human to say yes first. Reading a file: fine, do it automatically. Deleting a branch, running rm -rf, pushing to main: stop and ask. This is precisely the distinction VS Code's own agent documentation builds in with configurable permission levels and checkpoints, snapshots you can roll back to if a session's changes go somewhere you didn't want.
Memory. Two different problems hide under one word here. Inside a single session, memory means the running conversation: every tool call and result fed back so far, which is what lets the model reason about step four while still remembering what it learned in step one. Across sessions, memory means something persists after the process exits, so the agent doesn't start over from zero tomorrow. Claude Code, for example, reads a CLAUDE.md file at the start of every session and also builds its own notes as it works, so a lesson like "here's the actual build command" survives between runs.
Loop, permissions, memory. Nearly everything marketed as an "AI agent platform" is a variation on those three.
| Layer | Holds a conversation | Can request an action | Can actually execute it |
|---|---|---|---|
| Chatbot | Yes | No | No |
| Tool-calling LLM | Yes | Yes | No, it can only ask |
| Harness (agent) | Yes | Yes | Yes, that's its whole job |
This is what Copilot, Claude Code, and Cursor actually are
Name the three layers and the "magic" resolves into something ordinary: a model, wrapped in a harness someone else already built and hardened.
GitHub Copilot's agent mode in VS Code runs this exact loop. You send a request, the agent decides which tools to call, edits files, runs terminal commands, and searches your codebase, then keeps going across multiple turns, with configurable permission levels and automatic checkpoints you can roll back to.
Claude Code runs that loop too, from your terminal, an IDE extension, a desktop app, or a browser: it reads your codebase, edits files across your project, runs shell commands, works directly with git, and can spawn several instances of itself to work on different parts of a task in parallel, with a lead agent coordinating the work.
Cursor and the other AI-first editors are built on this exact pattern, with their own harness wrapped around it. Most of them, Copilot and Claude Code included, can also connect to external tools through the Model Context Protocol, a separate open standard for plugging a harness into tools someone else built.
The defaults for what's allowed without asking differ by product. So do the memory systems. The three-layer shape underneath does not.
The model is rented. The harness is the product.
That's also, not coincidentally, why this series exists. Understanding the harness is what lets you build agent-shaped features into your own product instead of only ever being a customer of someone else's.
What a harness can't do
A harness doesn't make the underlying model smarter. If a model can't reliably tell src/ from dist/, wrapping it in the best-designed harness in the world won't fix that. You'll just get faster, more confident wrong answers.
It isn't free, either. Every extra turn through the loop costs tokens and latency, which is exactly why Anthropic's own guidance is to reach for the simplest setup first: a single well-prompted call is enough for most tasks, and you should only add a loop, tools, and autonomy once a simpler approach has demonstrably fallen short.
And a badly designed harness is actively dangerous. One that grants a model unrestricted shell access with no confirmation step first isn't "more powerful," it's a harness with no permission layer, which is a security bug wearing a feature's clothing. This series spends an entire post on exactly that failure mode later on.
The shift this represents
With the three layers named, the interesting question about any AI coding tool stops being "how smart is the model" and starts being "how good is the harness": what tools does it expose, what's allowed to run without asking, what does it remember, and what happens the moment a tool call fails.
The rest of this series builds exactly that, one post at a time: the smallest loop that works first (about 80 lines, one hardcoded tool, no framework), then real tools, real permissions, real memory, and eventually something you could actually deploy. I already leaned on this loop-plus-tools pattern to replace four freelance roles with an agent for a landing page video; the harness underneath is loop, permissions, and memory, just like everything above.
Want an agent-shaped feature built into your actual product, not just another chatbot bolted onto the sidebar? I help SaaS teams design the harness part, tool design, permission boundaries, and memory, not just the API call to the model. Book a consultation to discuss your project.
Same three questions, every time: what can it do, what does it need permission for, and what will it remember tomorrow.
FAQ
Is "agent harness" an official term?
No. There's no standards body defining it. It's descriptive shorthand for the loop-plus-permissions-plus-memory layer around a model, and it's the same word Anthropic's own engineering team uses to describe how Claude Code orchestrates its agents.
Do I need to know Python, or can I build one in TypeScript?
You can build a harness in almost any language with an HTTP client and a JSON parser. This series builds its harness in TypeScript on Node.js, since that's the stack most of this site's readers already ship in day to day (and the one I reach for too).
Is an agent harness the same thing as a framework like LangChain?
A framework is a pre-built harness (or a kit for building one) with someone else's decisions already made about how the loop, permissions, and memory work. That's genuinely useful once you know what you actually need. Anthropic's own advice is to start by building the loop yourself with a direct API call before reaching for a framework, so an abstraction isn't hiding decisions you don't yet understand. This series follows that advice: frameworks show up later, once the fundamentals are muscle memory.
Do I need the Model Context Protocol (MCP) to build one?
No. MCP is a separate, optional standard for connecting a harness to tools someone else already built, described in its own docs as "a USB-C port for AI applications." You can give your harness tools without it. This series opens up MCP properly later on.