What is an agent harness?

An agent harness is the software around an AI model that turns it into a working agent. The model decides what to do next; the harness gives it tools, runs them safely, manages what it remembers, and connects it to whichever model you choose.

The model and the harness

A language model on its own only turns text into more text. It can't read your files, run your tests or remember yesterday's conversation. Everything that makes an AI coding tool feel like a colleague rather than a chat box lives outside the model, in the harness:

  • Tools. Functions the model can call: read and edit files, search code, run shell commands and builds, use git, fetch documentation. Good tools return results the model can act on in one step.
  • The loop. Send the conversation to the model, run the tools it asks for (often several at once), feed the results back, repeat until the task is done.
  • Safety. Permission rules for what the agent may do, and a sandbox so a shell command can't read your SSH keys or write outside the project.
  • Context. Deciding what goes into the model's limited context window: retrieving the relevant code instead of whole files, compacting long conversations, remembering facts across sessions.
  • Models. Talking to any provider, switching models mid-task, and routing simple work to cheaper models.
  • The interface. Where you watch and steer the work: a terminal UI, an editor panel, or a script.

Swap the model and keep the harness, and your workflow stays the same. Keep the model and swap the harness, and the same model can be faster, cheaper, safer or simply better at the job.

Agent harness vs coding agent

"Coding agent" describes what the tool is for. "Agent harness" describes what it is: the part that is not the model. Tools like Claude Code and Codex CLI are harnesses built around their vendor's own models. A model-independent harness is built to work with any of them, including models running on your own machine.

What makes a good agent harness

  • Fast to start and light to run. You open it dozens of times a day; it shouldn't need a runtime to boot or eat memory while it waits.
  • Safe by default. Commands the model runs should be confined by the operating system, not just guarded by a confirmation prompt.
  • Frugal with context. Every token of irrelevant code costs money and attention. Retrieval beats pasting whole files.
  • Not locked to one model. The best or cheapest model changes every few months.
  • Inspectable. You should be able to see every tool call, every diff, and rewind when it goes wrong.

agentty: an agent harness for your terminal

agentty is an open-source agent harness written in C++26: one 23.0 MB static binary that starts in about ~2 ms, with no Node, Python or Electron.

  • Any model. Sign in with the Claude Pro/Max, ChatGPT, GitHub Copilot or Kimi plan you already pay for, use an API key for OpenAI, DeepSeek, Gemini, Grok, Groq or OpenRouter, or run a local model through Ollama. Providers
  • Kernel-enforced sandbox. Every shell command runs inside claybin; ~/.ssh, ~/.aws and .env files are masked. Sandboxing
  • Context it earns. Local retrieval (BM25 plus embeddings), automatic compaction and memory across sessions. Retrieval
  • Routing between models. Smart Mode puts each turn on the model it deserves and delegates mechanical work. Smart Mode
  • Parallel tools and subagents. Independent tool calls run at once; a subagent can take a task in its own context. Tools
  • Anywhere you work. In the terminal, inside Zed over ACP, as an MCP server, or on an air-gapped machine over SSH. ACP

Frequently asked questions

What is an agent harness?

An agent harness is the software that runs around a language model and turns it into an agent that does real work. The model only produces text; the harness gives it tools to call, runs those tools safely, decides what goes into the model's context, keeps the conversation going across many turns, and connects to whichever model provider you use.

Is an agent harness the same as a coding agent?

A coding agent is an agent harness pointed at software work: its tools read, search and edit code, run builds and tests, and use git. The harness is the part that is independent of the model. agentty is a coding agent in that sense, and it calls itself a harness because it is built to work with any model rather than one vendor's.

Why does the harness matter if the model does the thinking?

Because most of what makes an agent useful, safe and cheap happens outside the model: which tools it has and how well they report results, whether shell commands are sandboxed, how much irrelevant text is kept out of the context window, and whether you can switch models when a better or cheaper one appears. The same model can do very different work in two different harnesses.

Can I use my own model with an agent harness?

That is the point of a model-independent harness. agentty works with the Claude, ChatGPT, GitHub Copilot or Kimi subscription you already have, with API keys for providers like OpenAI, DeepSeek, Gemini, Grok, Groq and OpenRouter, or with a local model through Ollama.

Try it

One line installs it on Linux, macOS or Windows:

sh
curl -fsSL https://agentty.org/install.sh | sh

Then read the quick start, or see how it compares with Claude Code.