Agent harnesses: how they are built, and ours

33 open-source projects taken apart down to the function that calls the model, the open-source options for each part of a harness, and a first design for our own. Sources read on 12 Oct 2026.

Step 1

An agent is a model inside a harness

A language model can only read text and write text. On its own it cannot open a file, run a test or remember yesterday.

The harness is everything around the model that turns its text into actions: it shows the model the right things, runs the tools it asks for, keeps the record, and enforces the rules.

Think of the model as the driver and the harness as the car. Every project on this page is a different car built around much the same kind of driver.

The parts every harness has

which holds these six parts:

Agent loop

the loop

Ask the model. If it wants a tool, run it and ask again. Stop when it answers without asking for one.

Select any part to read about it.

One request, step by step

1
Surface
A message arrives from a person or a program.
2
Session
The session gathers what the model should see: instructions, earlier messages, the list of tools.
3
Model layer
The request goes to the model, and the reply streams back.
4
Permissions
If the reply asks for a tool, the permission rules decide: run it, refuse it, or ask a person.
5
Tools
The tool runs in the execution environment and returns its result.
6
Session
The result is written to the session, and the loop goes back to the model with it.
7
Surface
When the model replies without asking for a tool, that reply is the answer.

Steps 3 to 6 (filled) repeat for as long as the model keeps asking for tools.

Step 2

What we learned

The patterns that showed up again and again in the code. Select a project to see it there.

1
The loop is the small part
Ask, run the tool, ask again: mini-SWE-agent does it in about a hundred lines, and even Cline keeps its loop in one file. Almost all of the code in these projects is everything around the loop.
2
Keep the record, rebuild the view
The strongest designs never edit history. They store every event in order and build what the model sees from it, so summarising old turns changes the view, not the record.
3
The big split is where the hands go
Some agents run commands on your machine; others send them to a sandbox elsewhere. The cloud designs keep the keys and the transcript outside the sandbox and treat it as disposable.
4
Permission is becoming data
Instead of code deciding what a tool may do, more projects use rule tables with three answers (allow, ask a person, deny) and priorities so an organisation's rule beats a project's.
5
Memory people can read
Long-term memory is moving to plain files, often in git, with agent-written entries held for a person's approval. Search by meaning is the exception, not the rule.
6
Everyone plugs in the same way
Tools arrive over MCP, instructions as AGENTS.md and skills folders, and outside code through hooks. The edges have standardised even where the insides differ completely.

Reference: the projects side by side

Come back to these while you work through the path: sizes, kinds and where each sits. The full comparison has its own tab.

How big is each one?

Same job, wildly different sizes: from a few thousand lines to several million.

Smallest: mini-SWE-agent; 4,358 lines
Largest: OpenClaw; 5,096,103 lines
Difference: The largest is; 1,169× the smallest

1k10k100k1M10M

lines

Each step on the scale is ten times the one before. Select a project to open it. Lines in Python, TypeScript, Rust, Go, Swift and Kotlin files in the whole repository, leaving out tests, documentation, examples, scripts, build output and any file over 50,000 lines (generated catalogues). Counted by us at the commit shown, so the numbers compare like with like but will not match a project's own claims. The Claude Agent SDK figure is only the open wrapper; the agent itself is closed.

Three kinds of project

Not everything here is the same kind of thing, and comparing across kinds misleads.

Agents you run: Complete agents with their own loop, tools and interface.
Kits for building agents: Libraries that give you a loop and its parts to assemble your own.
Systems that run many agents: Control planes and orchestrators built around an existing agent.

Where each agent sits

Two questions separate the agents you run most: how much is built into the core, and whether tools can run somewhere other than your own machine. Kits and systems are left off, because the questions do not apply to them in the same way.

Point at a project to see why it sits where it does. Select one to jump to its diagrams.

The positions are our judgement from reading the source, not a measurement.

Why each one sits where it does

mini-SWE-agent: The smallest possible core. Not a remote system, but because every command is stateless it runs in any container or cloud sandbox with a one-file adapter.
Aider: Small and single-purpose. Built entirely around a person at a terminal in a local git repository.
Trae Agent: A small core. Runs locally, with an option to run tools inside Docker.
Pi: The smallest core among the full-featured agents. Runs locally by default; remote execution arrived this year through the env package.
Crush: A mid-sized core with the loop outsourced to a library. Runs on your machine; the server is local.
Gemini CLI: A very large core with most things built in. Runs locally in a sandbox; remote reach is through A2A and headless mode, not remote execution.
Codex CLI: Large core. Commands are sandboxed locally and can run through a separate exec server; OpenAI's hosted version runs it in cloud containers.
Loop: Small like Pi but with more built in (sandbox, SQLite sessions, workflows). Tools already cross an interface into a container; remote machines are planned, not built.
ForgeCode: A mid-sized core focused on the loop and its tools. Runs on your machine; its sandbox is a git worktree.
Kimi Code CLI: A large engine with many features built in. Commands run locally; remote means remote clients through a tunnel.
Continue: A mid-sized core shared by editor extensions. Everything runs on your machine.
OpenCode: Many features built in. Tools run on the host with permission rules, not isolation; remote means remote clients, not remote execution.
Cline: A large orchestration layer around a very small loop. Sessions already live in a daemon separate from the interface, with a remote host variant.
Goose: A mid-sized core because tools live in extensions. Runs on your machine; isolation is left to you.
Hermes Agent: Very much built in, and commands can run in seven backends including three cloud sandboxes.
Qwen Code: Very large, with most features built in. Sandboxing as in Gemini CLI; remote reach through hosted workspaces and chat apps.
Kilo Code: OpenCode's large core plus Kilo's packages. Runs locally; cloud sessions are a separate service.
Codebuff (Freebuff): A mid-sized runtime with many small agents. The open code runs locally; the same agents run on GitHub repositories in its cloud product.
OpenHands SDK: Mid-sized core with a typed tool system. Remote execution is the central design, with six workspace backends.
Letta Code: Much built in around memory. Designed from the start for the agent's state to live apart from the machine doing the work.
OpenClaw: By far the most built in. Tool execution can move to containers, other machines or leased cloud boxes while the gateway keeps the session.

Words used on this page

Harness: The program around a language model that lets it do work: it runs the loop, offers tools, keeps the record and enforces rules. The model supplies judgement; the harness supplies everything else.
Agent loop: Ask the model, run any tool it asks for, give it the result, ask again. It ends when the model answers without asking for a tool.
Tool call: The model's request to do something it cannot do itself, such as read a file or run a command. The harness carries it out.
Turn: One request from the user and everything the agent does to answer it. Some projects call a single model reply a step and reserve turn for the whole exchange.
Session, thread, conversation: Three names for the same thing: the saved record of one line of work.
Context window: The amount of text the model can see at once. Long sessions outgrow it.
Compaction: Replacing older parts of a session with a summary so it fits the context window again. Also called condensation or compression.
Event sourcing: Storing every thing that happened, in order, and never editing it. The current state is worked out by replaying the events.
Prompt cache: Providers charge much less for text they have seen at the start of a previous request. Changing anything early in the prompt throws that saving away.
Sandbox: A fenced-off place to run commands, so a mistake or an attack cannot reach the rest of the machine or network.
Worktree: A second checkout of the same git repository in another folder, so two agents can edit without colliding.
MCP: Model Context Protocol. A standard way for a program to offer tools to any agent.
ACP: Agent Client Protocol. A standard way for an editor or app to drive any agent.
Skill: A folder with instructions the agent reads only when the task calls for it. Only its name and one-line description are always in view.
Sub-agent: A second agent started by the first, with its own fresh context, that reports back a summary.
Code mode: Instead of calling tools one at a time, the model writes a short script that calls many. Only the script's final output comes back, which saves context.
Hook: A point in the loop where outside code is allowed to look at what is happening and change or block it.

Package, file and function names were checked against each repository at the commit shown. A module's purpose is taken from its own description or documentation where it has one, and otherwise from its source. Positions on the map, the "what is new" lists and everything under Our design are our reading and our proposal, not the projects' own claims. Each project ends with what we did not read, and each entry under Components says how we know it. Logos belong to their owners and are shown only to identify each project.