06: Harnesses, tools, and MCP¶
About a 35-minute read. Last checked November 8, 2026.
TL;DR - A harness is everything around the model: the agent loop, the tools, the permission system, context management, and the user interface. Agent = model + harness, and the same model can feel brilliant in one harness and clumsy in another. - Coding tools went through five overlapping generations: autocomplete (2021), chat (2022), IDE agents (2023–2025), terminal (CLI) agents (2025), and cloud or background agents (2024–2025). A sixth layer arrived in 2025–2026: desktop apps and orchestrators that drive several CLI agents at once. - MCP (Model Context Protocol) is the open standard for connecting tools and data to compatible harnesses. Anthropic released it in November 2024. OpenAI, Google and Microsoft adopted it in 2025, and it moved to the Linux Foundation's Agentic AI Foundation in December 2025. Its main costs are context bloat and security risk. - Modern harnesses share a common kit: instruction files, skills, subagents, hooks, slash commands, plugins, permission modes and sandboxes, git worktrees, and checkpoints. Learn the concepts once and they transfer across tools. - Closed products such as Claude Design, Claude in Chrome, ChatGPT agent and Google Antigravity bundle a model, a harness and tools into one experience. They're convenient, but you can't easily see inside them or swap their parts. - Pick a harness on model access, cost model, privacy, extensibility, and what your team already uses, not on demo videos.
Foundations¶
What a harness is¶
On its own, a large language model (LLM) does one thing: it takes text in and predicts text out. It can't open a file, run a test, or remember yesterday's conversation. Everything that turns that text predictor into something that edits your codebase is the harness.
A useful working definition:
Harness = agent loop + tools + permissions + context management + user interface. Agent = model + harness.
Each part, in plain terms:
| Part | What it does | Example |
|---|---|---|
| Agent loop | Calls the model, runs any tool the model asks for, feeds the result back, and repeats until the model says it's done | "Read auth.py" → file contents → "Edit line 40" → diff → "Run tests" → output → ... |
| Tools | Functions the model may call, each described by a name, a description and an input schema | read_file, edit_file, bash, web_fetch, search |
| Permissions | Rules about which tool calls run automatically, which need your approval, and which are forbidden | "Allow npm test; ask before git push; never rm -rf" |
| Context management | Decides what goes into the model's limited context window and what gets summarized or dropped | Loading instruction files, compacting long sessions, giving subagents fresh windows |
| User interface | How you see and steer the work | Terminal UI, IDE panel, web dashboard, desktop app, Slack bot |
The loop itself is simple. Most agents today are a variant of the ReAct pattern (reason, then act, then observe), described by Yao et al. (2022):
flowchart LR
U[Your task] --> M[Model]
M -->|wants a tool| T[Harness runs tool<br/>if permitted]
T -->|result| C[Context window]
C --> M
M -->|says done| R[Answer, diff, or PR]The model is the engine. The harness provides the steering, brakes, dashboard and fuel system, all of which affect how well it works.
Why the same model behaves differently in different harnesses¶
People often say "model X is bad at Y" when the real cause is the harness. Several harness choices change results a lot:
- Tool design. The SWE-agent paper (Yang et al., 2024) showed that giving a model a purpose-built "agent-computer interface" (compact file viewers, a search tool, an editor that lints on save) made the same model much better at fixing real GitHub issues than giving it a raw shell.
- The system prompt and defaults. In April 2026 Anthropic published a postmortem on user complaints that Claude Code had gotten worse. It traced the problem to three harness-level changes rather than the model weights: a lower default reasoning effort, a context-management bug that cleared earlier reasoning on every turn, and a system-prompt line that capped how much the model wrote between tool calls. All three were reverted or fixed.
- Context management decides what the model can "see" at each step: how the harness compacts history, loads instruction files, and returns tool output (module 07).
- Permission prompts. A harness that asks for approval on every command trains you to click "yes" without reading, and one that never asks can do damage.
- Benchmark scores depend on the scaffold too. When two vendors report the same agentic benchmark with different harnesses, the numbers aren't directly comparable (module 05).
Evaluate coding models in the harness you'll use.
A short history: from autocomplete to orchestrators¶
The generations overlap, and every one is still in use.
| Generation | Arrived | Examples | What you do | What the tool does |
|---|---|---|---|---|
| 1. Autocomplete | 2021 | GitHub Copilot (technical preview June 29, 2021), built on OpenAI Codex (Chen et al., 2021) | Type code | Suggests the next line or block |
| 2. Chat | late 2022 | ChatGPT, Claude.ai, IDE chat panels | Paste code, ask questions, copy answers back | Explains, drafts, reviews snippets |
| 3. IDE agents | 2023–2025 | Cursor, Windsurf, Copilot agent mode, Cline | Describe a change inside your editor | Edits many files, runs commands, shows diffs to accept |
| 4. CLI agents | 2025 | Claude Code (research preview Feb 24, 2025), Codex CLI (Apr 2025), Gemini CLI (Jun 2025), OpenCode, Amp, Factory Droid, Cursor CLI, Copilot CLI, Crush | Give a task in the terminal | Explores the repo, edits, runs tests, commits |
| 5. Cloud / background agents | 2024–2025 | Devin (2024), Codex cloud (May 2025), Copilot coding agent (May 19, 2025), Jules (2025), Claude Code on the web (Oct 20, 2025), Cursor cloud agents | Assign an issue or task, walk away | Works in a remote sandbox, opens a pull request |
| 6. Desktop GUIs and orchestrators | 2025–2026 | Conductor, T3 Code, Codex app (Feb 2, 2026), Claude desktop app, Gas Town, OpenHands Agent Canvas | Supervise several agents at once | Runs many CLI agents in parallel, each in its own git worktree, and shows their diffs side by side |
A few details behind the table:
- The terminal won in 2025 because the shell is the universal tool. An agent that can run any command can build, test, lint, query a database and call
ghwithout anyone writing a special integration. CLI agents also run headless, so the same agent works in CI, in scripts, and in cloud sandboxes. - Generation 6 wraps generation 4. Tools like Conductor and T3 Code aren't agents themselves. They drive the CLI agents you already have installed and signed into, and add a GUI, parallel sessions and diff review. T3 Code describes itself as an "agent harness control surface." It is MIT-licensed, comes from Theo Browne's company (the
pingdotggGitHub organization), and supports Claude Code, Codex, Cursor, OpenCode, Antigravity and others. Its README calls it "very very early." Conductor (from Melty Labs) is a Mac app that runs parallel Claude Code, Codex and Cursor agents in isolated workspaces. - Gas Town (Steve Yegge, January 2026) is an orchestrator for 20–30 agents with named roles: a "Mayor" coordinator, "polecat" workers, and a "Refinery" merge queue. It sits at the top of Yegge's eight-stage ladder of AI coding workflows (module 08, module 13).
This market consolidates fast, so check before you standardize on anything. The status changes as of November 2026:
- Gemini CLI is now aimed at enterprise Gemini Code Assist on Google Cloud. On June 18, 2026, free individual access and the Google AI Pro/Ultra plans moved to Google's Antigravity CLI (
agy), per the Gemini CLI README. - Cursor was acquired by SpaceX on August 14, 2026.
- Windsurf split in July 2025. Google licensed its technology and hired its leaders, and the team went on to build Antigravity. Cognition (maker of Devin) acquired the rest of the company.
- Roo Code, a popular open-source IDE agent, shut down its extension on May 15, 2026, and Continue is archived and read-only (module 13).
- Amp spun out of Sourcegraph as its own company in late 2025.
- Codex started as a CLI (April 2025) and a cloud agent (May 2025). By late 2026, OpenAI's docs list Codex across the ChatGPT desktop, web and mobile apps plus the CLI, IDE extension and cloud (learn.chatgpt.com).
Tools: how a model "does" things¶
A tool is a function the harness exposes to the model. The harness sends the model a list of tool definitions, each with a name, a plain-English description, and a JSON Schema for the inputs. When the model wants to act, it outputs a structured tool call. The harness checks permissions, runs the function, and puts the result back into the context.
{
"name": "run_tests",
"description": "Run the project's test suite. Use after editing code. Returns pass/fail and failing test output.",
"input_schema": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "Optional test file or directory" }
}
}
}
Tool design affects both behavior and context use:
- Tool descriptions are prompts. The model picks tools by their names and descriptions, so vague descriptions produce wrong choices. Anthropic's guide Writing effective tools for agents (September 2025) treats tool design as a core engineering task.
- Loaded tool definitions cost context. Unless the harness uses lazy discovery, definitions go along with every model call, and fifty tools can eat a large share of the window before you type anything. This causes "MCP bloat."
MCP: the Model Context Protocol¶
Before MCP, every harness needed custom code for every integration. Ten harnesses times a hundred services meant a thousand integrations. MCP turns that into ten clients plus a hundred servers.
MCP is an open protocol that Anthropic announced on November 25, 2024. It standardizes how an AI application discovers and calls external tools and data; Anthropic's own analogy is a USB-C port for AI applications. The pieces:
| Term | Meaning |
|---|---|
| Host | The AI application you use: Claude Code, Codex, Cursor, VS Code, ChatGPT |
| Client | The connector inside the host that talks to one server |
| Server | A program that exposes capabilities: a GitHub server, a Postgres server, a browser-automation server |
| Tools | Functions the model can call (create_issue, query, click) |
| Resources | Data the application can read (files, records, documents), addressed by URI |
| Prompts | Reusable prompt templates a server offers, often surfaced as slash commands |
| Messages | JSON-RPC 2.0 requests and responses |
| Transports | stdio (the host launches the server as a local subprocess and talks over standard input/output) or Streamable HTTP (the server runs remotely, usually with OAuth) |
flowchart LR
subgraph Host["Host app (e.g., a CLI agent)"]
M[Model] <--> H[Harness]
H <--> C1[MCP client]
H <--> C2[MCP client]
end
C1 <-->|stdio| S1[Local server:<br/>browser automation]
C2 <-->|Streamable HTTP + OAuth| S2[Remote server:<br/>GitHub]
S2 <--> API[GitHub API]An MCP server is just a small adapter. It says "here are my tools and their schemas," then executes calls and returns results. The harness turns those tools into entries in the model's tool list, so to the model an MCP tool looks like any other tool.
Most harnesses configure servers in a JSON or TOML file. In Claude Code, a project-level .mcp.json might look like this. The first server runs locally over stdio. The second is GitHub's hosted server over HTTP, with the token read from an environment variable instead of written into the file:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
},
"github": {
"type": "http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
}
}
}
Codex CLI uses TOML in ~/.codex/config.toml for the same idea:
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
With Python 3.11+ and version 2 of the official mcp Python SDK installed, this minimal server exposes one tool backed by sample data (check the SDK docs for the current API):
from mcp.server import MCPServer
mcp = MCPServer("tickets")
tickets = {"platform": ["Fix session timeout", "Add rate-limit tests"]}
@mcp.tool()
def open_tickets(team: str) -> list[str]:
"""List open ticket titles for a team. Use before planning work."""
return tickets.get(team, [])
if __name__ == "__main__":
mcp.run(transport="stdio")
MCP went from one company's spec to industry plumbing in about a year:
| When | What happened |
|---|---|
| Nov 25, 2024 | Anthropic releases MCP with SDKs and reference servers |
| Mar 2025 | The spec adds the Streamable HTTP transport, replacing the older HTTP+SSE transport |
| Mar 26, 2025 | OpenAI adds MCP to its Agents SDK and says ChatGPT desktop and the Responses API will follow |
| Apr 2025 | Google DeepMind's CEO says Gemini models and SDK will support MCP. Gemini CLI ships with MCP support in June |
| May 2025 | Microsoft announces MCP support across GitHub, Copilot Studio, and Windows at its Build conference |
| Sep 8, 2025 | The official MCP Registry launches in preview |
| Dec 9, 2025 | Anthropic donates MCP to the new Agentic AI Foundation (AAIF) under the Linux Foundation, alongside Block's goose and OpenAI's AGENTS.md |
| Jan 26, 2026 | MCP Apps ships as an official extension: tools can return interactive UI (forms, dashboards) that the host renders in a sandboxed iframe. It launched in Claude, goose and VS Code Insiders, with ChatGPT support rolling out the same week (MCP blog) |
| Jul 28, 2026 | The 2026-07-28 specification makes MCP stateless: no initialize handshake, no protocol sessions, version and capabilities sent with every request. Roots, Sampling and Logging are deprecated |
The stateless redesign matters to people who run servers. A stateless server can sit behind an ordinary load balancer, which makes hosted MCP much easier to scale. The three primitives you build with (tools, resources, prompts) are unchanged.
MCP has several costs and limitations:
- Context bloat. In harnesses without lazy discovery, connected servers' tool definitions load into context. Anthropic's advanced tool use post (November 2025) gives a typical five-server setup as "58 tools consuming approximately 55K tokens before the conversation even starts." It also reports seeing 134K tokens of tool definitions internally before optimization. Large tool lists also make tool selection less accurate.
- Security. An MCP server is code you run with your credentials. A malicious or compromised server can lie in its tool descriptions ("tool poisoning"), change behavior after you approve it, or exfiltrate data. Any server that reads untrusted content (web pages, issues, emails) is a prompt-injection channel. Hou et al. (2025) survey the threat landscape, and module 11 covers defenses.
- Quality varies. Many community servers are thin API wrappers with poor descriptions and huge outputs. The official reference servers are labeled educational examples, "not production-ready solutions" (modelcontextprotocol/servers).
- "Just use the CLI." Many engineers find that an agent with shell access does better with
gh,psqlorkubectlthan with an MCP wrapper of the same service. The model already knows those CLIs from training, and their output can be filtered withgreporjqbefore it hits context.
Two posts in late 2025 proposed the same fix for bloat: code execution with MCP, or "code mode." Cloudflare's Code Mode (September 26, 2025) converts MCP tools into a TypeScript API and has the model write code that calls it, in a sandbox. Its argument is that "LLMs are better at writing code to call MCP, than at calling MCP directly." Anthropic's Code execution with MCP (November 4, 2025) presents servers as code files on a filesystem that the agent browses on demand. In its example, token use dropped "from 150,000 tokens to 2,000 tokens," a 98.7% saving, because intermediate data stayed in the sandbox instead of passing through the model. Related harness features include tool search (load a small search tool first and fetch definitions only when needed; Anthropic reported an 85% token reduction) and programmatic tool calling.
Google also announced the Agent2Agent (A2A) protocol in April 2025 and gave it to the Linux Foundation that June (a2a-protocol.org). MCP connects an agent to tools and data. A2A connects one agent to another agent, possibly from a different vendor, so they can delegate tasks and exchange results. In coding work you'll run into MCP daily and A2A rarely.
The rest of the harness toolkit¶
By 2026 the major harnesses had converged on a shared set of features. The names differ a little between products, but the ideas are the same. The examples use Claude Code's terms because its docs are detailed; Codex, Cursor, OpenCode and others have close equivalents.
| Feature | What it is | Use it for | Watch out for |
|---|---|---|---|
Instruction files (CLAUDE.md, AGENTS.md) |
Markdown loaded into every session | Build commands, conventions, non-obvious gotchas | Bloat. Keep them short (module 07) |
| Skills | A folder with a SKILL.md (name, description, instructions) plus optional scripts. Only the name and description load up front; the body loads when relevant |
Repeatable procedures: "how we cut a release," "how to write a migration" | Skills can run code. Treat third-party skills like dependencies |
| Subagents | A separate agent with its own fresh context window, its own tools, and its own instructions, launched by the main agent | Exploring a big codebase, running a review, isolating noisy work | Extra tokens. Summaries can lose detail |
| Hooks | Your shell commands that the harness runs at fixed lifecycle events (before a tool call, after an edit, when the agent tries to stop) | Deterministic enforcement: format on save, block dangerous commands, refuse to finish while CI is red | A buggy hook can block all work. Keep them fast |
| Slash commands | Saved prompts you trigger by name (/review, /deploy-check) |
Team workflows you run often | In Claude Code these have been folded into skills |
| Plugins and marketplaces | Bundles of skills, hooks, subagents and MCP servers, installed from a git-hosted "marketplace" | Sharing a team's setup in one install | Supply-chain risk, as with any package |
| Permission modes | Presets for how much the agent may do without asking: plan-only, ask-every-time, auto-accept edits, classifier-approved "auto," or bypass | Matching autonomy to risk | "Bypass all" mode on your real machine |
| Sandboxing | OS-level limits on which files and network hosts commands can reach; or a container, VM, or cloud sandbox | Letting agents run longer without approvals | Configuration effort. Leaky allowlists |
| Git worktrees | Several working directories on one repository, each on its own branch | Running parallel agents without collisions | Disk use. Clean up finished worktrees |
| Checkpoints | Automatic snapshots of file edits (and conversation) you can rewind | Undoing a bad turn quickly | Not a replacement for git commits |
| Scheduling and loops | Re-run a prompt on an interval (/loop), until a condition holds (/goal), or on a cloud schedule |
Babysitting CI, nightly triage | Runaway token spend (module 07) |
Three of these need more explanation.
Start with skills. Anthropic introduced Agent Skills on October 16, 2025 and published the format as an open standard at agentskills.io on December 18, 2025. On October 22, 2026 it donated the standard to the AAIF, reporting that more than 70 agent platforms had integrated it, including ChatGPT, Cursor, GitHub Copilot and VS Code. The key idea is progressive disclosure. The agent sees a one-line description of every skill and reads the full instructions only when a task calls for them. That lets you keep dozens of procedures available without paying for them in every prompt.
Hooks run deterministic rules every time they're triggered. An instruction file only asks the model to follow a rule. Claude Code's docs say so directly: instruction files are treated "as context, not enforced configuration," and to block an action regardless of what the model decides, you use a hook (memory docs).
A formatter hook, adapted from the hooks guide, runs Prettier after every file edit:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -j '.tool_input.file_path, \"\\u0000\"' | xargs -0 npx prettier --write --" }
]
}
]
}
}
A Stop hook runs when the agent tries to end its turn. If the hook returns {"decision": "block", "reason": "..."}, the agent keeps working and sees the reason. This teaching example blocks once when it sees unfinished runs among the five latest runs on the branch. It lets the agent stop on the next attempt, to avoid a loop; it isn't an enforced CI gate and doesn't check whether completed runs passed:
#!/usr/bin/env bash
# .claude/hooks/ci-gate.sh: block "done" while CI is pending on this branch.
input=$(cat)
# If this hook already blocked once this turn, let the agent stop (avoids loops).
[ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ] && exit 0
branch=$(git branch --show-current)
pending=$(gh run list --branch "$branch" --limit 5 --json status \
--jq '[.[] | select(.status != "completed")] | length')
if [ "${pending:-0}" -gt 0 ]; then
echo '{"decision":"block","reason":"CI is still running. Watch it with gh run watch and report the result before finishing."}'
fi
exit 0
Then there are permission modes and auto mode. Approval prompts sound safe, but people stop reading them. Anthropic reported in March 2026 that users approve 93% of permission prompts. Its "auto mode" hands routine approvals to a classifier model and keeps hard blocks for risky actions. Anthropic was candid about the limits: the full pipeline still missed 17% of "overeager" actions in its tests, and it is "not a drop-in replacement for careful human review on high-stakes infrastructure." The safer pattern for long unattended runs is a real sandbox (container, VM, or cloud environment) with limited credentials.
In practice¶
Closed products that bundle model, harness and tools¶
Some products hide the harness entirely. The vendor picked the model, the loop, the tools and the UI, and you get one experience. They're often the fastest way to get a specific job done. Model choice, prompt visibility and workflow portability vary by product and can be limited, and the model tiers behind each one change often (module 03).
| Product | Maker, launch | What it is | Good for |
|---|---|---|---|
| Claude Code (CLI, desktop, web, IDE, Slack) | Anthropic, Feb 2025 | Anthropic's coding agent, with cloud sessions, scheduled tasks and code review | Day-to-day agentic coding |
| Claude Design | Anthropic Labs, Apr 17, 2026 (research preview) | Chat-driven design canvas for prototypes, slides and one-pagers. It can apply a team's design system and export to Canva, PDF, PPTX or HTML. A finished design can be packaged as a handoff bundle for Claude Code | Turning an idea into a clickable prototype or deck before writing production code |
| Claude Cowork | Anthropic, Jan 2026 (research preview) | Claude Code's agent loop for non-coding knowledge work on folders and tools you choose. By late 2026 Anthropic had folded it into the main Claude app (product page) | Document, spreadsheet and research chores |
| Claude in Chrome | Anthropic, Aug 2025 (preview), wider beta late 2025 | Browser extension that lets Claude click, type and navigate for you | Web workflows and testing web apps |
| Artifacts | Anthropic, 2024 | Claude renders code as live, shareable pages and apps in the chat | Quick internal tools, visual explanations |
| Codex app and automations | OpenAI, Feb 2, 2026 | Desktop command center for parallel Codex agents in worktrees, with scheduled "automations" whose results land in a review queue | Supervising several coding tasks; recurring triage |
| ChatGPT agent and Atlas | OpenAI, Jul 2025 and Oct 2025 | An agent mode in ChatGPT with its own browser and terminal, and a full web browser with an agent built in | Research and multi-step web tasks |
| Cursor with Composer | Anysphere, Composer Oct 29, 2025 | IDE plus cloud agents. Composer is Cursor's own coding model, trained with reinforcement learning inside Cursor's tools for speed | Fast in-editor agent loops |
| Google Antigravity | Google, Nov 18, 2025 | An agent-first IDE built by the former Windsurf team, with editor, terminal and browser agents. Now paired with Antigravity CLI | Teams centered on Gemini models |
| Devin, Jules, Copilot coding agent | Cognition (2024), Google (2025), GitHub (2025) | Cloud agents you assign tasks to; they return pull requests | Well-scoped backlog tickets |
Two cautions apply to all of them:
- Browser and computer-use agents are the riskiest category, because they read untrusted web content while holding your logged-in sessions. Anthropic's own Chrome launch post reported a 23.6% prompt-injection attack success rate without mitigations and 11.2% with them in its tests. Mitigations reduced the risk without eliminating it. Read module 11 before you point one at your email or bank.
- Bundled products change underneath you. The vendor can change the model, the prompts or the limits at any time. That's fine for prototypes, but for a workflow your team depends on, prefer tools whose configuration you can see and version.
How to choose a harness¶
Score harnesses against what your team needs:
| Question | Why it matters | What to look for |
|---|---|---|
| Model access | Some harnesses lock you to one vendor's models | Single-vendor (Claude Code, Codex, Antigravity) vs. bring-any-model (OpenCode, Cline, Kilo Code, Aider, Cursor) |
| Cost model | Agentic work burns many tokens | Flat subscription vs. per-token API billing vs. seat pricing (module 12) |
| Team standardization | Shared configuration only pays off if everyone uses the same tool, or the same standards | Does it read AGENTS.md? Support Agent Skills and MCP? Have managed settings for organizations? |
| Privacy and data | Code is sensitive | Data retention terms, zero-data-retention options, cloud vs. local execution, self-hosted runners, local models (module 04) |
| Extensibility | You will want to encode team knowledge | Hooks, skills, plugins, MCP, an SDK for custom agents |
| Autonomy and safety | Long runs need guardrails | Permission modes, sandboxing, worktree support, audit logs |
| Where the work happens | Fit with how people already work | Terminal, IDE, browser, GitHub issues, Slack |
| Vendor durability | Tools get acquired, pivot, or shut down | Open-source license, foundation governance, a portable configuration format |
Some places to start:
| If you are... | Start with... | Because... |
|---|---|---|
| A student learning the craft | One CLI agent plus its IDE extension, with approvals on | You see every action and learn what the agent does |
| An engineer on a team already using an IDE | That IDE's agent mode, plus one CLI agent for bigger tasks | Lowest friction; the CLI handles multi-file work |
| A team that must keep code on-premises | An open-source, model-agnostic harness with a self-hosted or local model | You control where code and prompts go |
| A lead standardizing a team | Pick one primary harness; put shared knowledge in AGENTS.md, skills and hooks |
Those formats work across most harnesses, so a later switch is cheap |
| Someone running many tasks at once | A CLI agent plus a worktree-based GUI or orchestrator | Parallelism without branch collisions (module 08) |
A sane baseline setup¶
In most harnesses, you can begin with these steps:
- Pick one primary CLI agent and learn its permission modes before you raise autonomy.
- Write a short
AGENTS.md(orCLAUDE.md) with build, test and lint commands and the few conventions an agent can't infer. Aim for well under 200 lines (module 07). - Add hooks for what must always happen: a formatter after edits, a guard against destructive commands, a check that tests pass before the agent says "done."
- Connect the one to three MCP servers you actually need. Prefer an existing CLI when the agent already knows it, and check each server's context cost with your harness's context view (in Claude Code,
/context). - Move repeated procedures into skills instead of pasting them into the instruction file.
- Set up worktrees before you run two agents on one repository.
- Turn on a sandbox before you turn off approvals.
- Commit often. Checkpoints are convenient, but git is the real safety net.
Common failure modes¶
- Too many MCP servers. Context fills with tool definitions, tool choice gets worse, and costs rise. Disconnect what you don't use this week.
- Trusting a server or skill because it's popular. Popularity isn't an audit. In early 2026, hundreds of malicious skills appeared on OpenClaw's public skill registry (module 13).
- Approval fatigue. You click "yes" on the fortieth prompt without reading it. Use allowlists and sandboxes so the prompts that remain matter.
- Blaming the model for a harness problem. Before you switch models, check the harness version, the effort setting, recent instruction-file edits, and connected servers.
- Accidental lock-in. Team knowledge stuck in one vendor's proprietary format is expensive to move, so prefer
AGENTS.md, Agent Skills and MCP. - Leaving worktrees and sandboxes behind. Parallel agents create lots of checkouts and build directories. Clean them up when a task is done.
Going deeper¶
The harness is now an engineering discipline¶
Two 2026 essays named the work of improving the harness. Mitchell Hashimoto's My AI Adoption Journey (February 5, 2026) calls it "harness engineering": whenever an agent makes a mistake, engineer a fix so it never makes that mistake again. OpenAI's Harness engineering post (February 11, 2026) describes a team that shipped an internal product of about a million lines with no hand-written code, by investing in docs, linters, structural tests and feedback loops for Codex. Module 07 places this on the larger buzzword ladder.
Anthropic's engineering posts show how much harness design matters for long tasks. Effective harnesses for long-running agents (November 2025) and Harness design for long-running application development (March 2026) describe initializer agents, progress files, and separate evaluator agents. Cursor's self-driving codebases research (February 2026) ran a planner, sub-planner and worker hierarchy for about a week to build a web browser. It found that agents follow instructions closely, including bad ones, and that infrastructure such as disk I/O became the bottleneck.
Why harness features converge¶
By late 2026 nearly every item in the feature table above shows up in every major harness. Features are cheap to copy, and the good ideas are visible in open-source projects (module 13). Aider's repository map, the Ralph loop, worktree-per-agent orchestration and skills all spread within months. So your skills transfer between tools, and no harness keeps a feature lead for long. The lasting advantages come from the model, the integration with where work already happens, and the price.
MCP vs. CLIs vs. code: an open debate¶
There are three ways to give an agent a capability:
- An MCP tool. Structured, discoverable, works in hosts with no shell (chat apps, IDEs), supports OAuth for remote services. Costs context; quality varies.
- A CLI the agent runs in a shell. Uses knowledge from training, composes with pipes, costs nothing until used. Needs a shell and a sandbox, and has no standard auth story.
- Code against an API, in a sandbox ("code mode"). Most token-efficient for multi-step data work. Needs a secure execution environment.
The trend through 2026 has been toward hybrids. Harnesses load tool definitions lazily (tool search), present MCP servers as code APIs, and let skills bundle scripts. If you're building an integration for others, MCP is the portable choice. If you're giving your own agent a capability, try the CLI first.
Permission systems are a security boundary, not a UX detail¶
The permission system is where the harness meets module 11. An agent that can read untrusted input, access private data, and communicate externally has all three parts of Simon Willison's "lethal trifecta." Permission modes, network allowlists, credential scoping and sandboxes are how you break at least one leg. Anthropic's How we contain Claude across products (May 2026) shows how one vendor layers these defenses.
Bryan's take¶
Bryan's take: My daily setup is several CLI agents running in parallel, each in its own worktree, which I manage by hand. I drive them through T3 Code, which lets me run Claude and Codex side by side, the two model families I think are best for code (module 03). That puts me at roughly stage 6–7 on Yegge's eight-stage ladder (module 08). I'm not running a fully autonomous orchestrator, because I haven't gotten reliable results from one.
A harness's cost model matters as much as its features. Bryan's view that subscriptions are what make heavy agentic use affordable is in module 12.
Try it¶
Individual exercise: build and measure a harness setup (60–90 minutes).
1. Install one CLI agent. Open a small project you know, and ask the agent to explain the architecture. Note which tools it calls.
2. Check the context breakdown (in Claude Code, /context; other harnesses have similar views). Write down how many tokens the system prompt, tool definitions and instruction files use before you type anything.
3. Connect one MCP server (Playwright or GitHub). Check the context breakdown again. How many tokens did it add?
4. Add a PostToolUse formatter hook and confirm it runs after an edit.
5. Write a Stop hook that blocks "done" until the tests pass. Give the agent a task that breaks a test and watch the hook push it back.
6. Write one paragraph: what did the harness do that the model alone couldn't?
Class or team exercise: same model, different harnesses (one session). Split into three groups. Give every group the same small, well-specified task, such as adding a feature with tests to a sample repository. Each group uses a different harness, and where possible the same model tier. Record time to a green test run, number of human interventions, tokens or cost, and diff quality as judged by another group. Then discuss which differences came from the harness and which came from the people.
Discussion questions¶
- If "agent = model + harness," which part matters more for your work today? What would change your answer?
- MCP moved from one company to a Linux Foundation project in about a year. What does neutral governance buy users? What does it not buy?
- When should a capability be an MCP server, a CLI the agent calls, or a skill with a script? Give an example of each from your own work.
- Approval prompts get approved about 93% of the time. Is a prompt you always approve a safety feature? What would you replace it with?
- Closed bundles such as Claude Design or Antigravity are convenient. What would make you trust one with production work?
- Several popular tools were acquired, pivoted or shut down in 2026. How should a team protect itself from that churn?
Sources and further reading¶
Papers - Evaluating Large Language Models Trained on Code (Chen et al., 2021): the Codex model behind the original Copilot. - ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2022): the reason–act–observe loop most agents use. - SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering (Yang et al., 2024): evidence that interface and tool design change agent performance. - Model Context Protocol (MCP): Landscape, Security Threats, and Future Research Directions (Hou et al., 2025).
Primary sources: MCP and standards - Anthropic, Introducing the Model Context Protocol (Nov 25, 2024). - MCP documentation and the 2026-07-28 specification changelog. - MCP blog, MCP Apps (Jan 26, 2026). - Linux Foundation, Formation of the Agentic AI Foundation (Dec 9, 2025). - MCP reference servers and the MCP Registry. - Cloudflare, Code Mode: the better way to use MCP (Sep 26, 2025). - Anthropic, Code execution with MCP (Nov 4, 2025) and Introducing advanced tool use (Nov 24, 2025). - A2A protocol. - Agent Skills specification; Anthropic, Equipping agents for the real world with Agent Skills (Oct 16, 2025) and Donating Agent Skills to the Agentic AI Foundation (Oct 22, 2026).
Primary sources: harnesses and products - Anthropic, Claude 3.7 Sonnet and Claude Code (Feb 24, 2025); Claude Code on the web (Oct 20, 2025); Claude for Chrome (Aug 2025); Claude Design (Apr 17, 2026); Cowork. - Claude Code docs: features overview, hooks guide, skills, subagents, permission modes, sandboxing, worktrees, checkpointing, plugins. - Anthropic engineering: Writing effective tools for agents (Sep 2025); Effective harnesses for long-running agents (Nov 2025); How we built Claude Code auto mode (Mar 2026); Harness design for long-running application development (Mar 2026); April 23 postmortem (Apr 2026); How we contain Claude across products (May 2026). - OpenAI, Codex repository and ChatGPT and Codex docs; Harness engineering (Feb 11, 2026). - GitHub, Introducing GitHub Copilot (2021) and Meet the new coding agent (May 19, 2025). - Cursor, Composer (Oct 29, 2025), Self-driving codebases (Feb 2026), Joining SpaceX (Aug 14, 2026). - Gemini CLI repository (status notice); Google Antigravity. - T3 Code; Conductor; Gas Town.
Commentary - Mitchell Hashimoto, My AI Adoption Journey (Feb 5, 2026). - InfoQ, OpenAI's harness engineering (Feb 2026).
Terms introduced¶
- Harness: the software around a model (agent loop, tools, permissions, context management, UI) that turns it into an agent.
- Agent loop: the cycle of calling the model, running the tools it requests, and feeding results back until it finishes.
- Tool / tool call: a function a harness exposes to the model with a name, description and input schema; a tool call is the model's structured request to run one.
- CLI agent: a coding agent that runs in the terminal and acts through shell commands and file edits.
- Cloud (background) agent: an agent that runs in a remote sandbox and returns its work, usually as a pull request.
- Orchestrator: software that runs and coordinates several agents at once, often one per git worktree.
- MCP (Model Context Protocol): an open JSON-RPC protocol for connecting AI applications to tools, resources and prompts provided by servers.
- MCP host / client / server: the AI app; the connector inside it for one server; the program exposing capabilities.
- stdio / Streamable HTTP: MCP's two transports, for local subprocess servers and remote servers.
- MCP Apps: an MCP extension that lets tools return interactive UI rendered by the host.
- Code mode (code execution with MCP): presenting tools as a code API the model calls from a sandbox, to save context.
- Tool search: loading tool definitions on demand instead of all at once.
- A2A (Agent2Agent): a protocol for agents to delegate to and communicate with other agents.
- Agentic AI Foundation (AAIF): the Linux Foundation body that hosts MCP, AGENTS.md, goose and Agent Skills.
- Skill: a folder with a
SKILL.mdand optional scripts that an agent loads only when relevant. - Progressive disclosure: showing an agent short descriptions first and full details only when needed.
- Subagent: a separate agent with a fresh context window launched by the main agent for a focused task.
- Hook: a user-defined command the harness runs at a lifecycle event, giving deterministic control.
- Plugin / marketplace: a bundle of skills, hooks, subagents and MCP servers; a git-hosted catalog of them.
- Permission mode: a preset for how much an agent may do without asking.
- Auto mode: a permission mode in which a classifier model approves routine actions.
- Sandbox: an environment that limits what files, network hosts and credentials an agent can reach.
- Git worktree: an additional working directory on the same repository, used to run agents in parallel.
- Checkpoint: an automatic snapshot of an agent's edits that you can rewind to.
- Approval fatigue: approving permission prompts without reading them because there are too many.