agent-harnesses

What is an agent harness?

A model answers; an agent acts. An agent harness is the runtime that turns one into the other: the model thinks, the harness decides what that thinking is allowed to touch.

Simon Willison's definition of the agent itself is the cleanest: "an LLM agent runs tools in a loop to achieve a goal." The harness is everything around that loop: which tools exist, what needs approval, what the model sees each turn, what survives a crash. Andrej Karpathy named the architecture back in 2023: the model is "the kernel process of a new Operating System", and the harness is the rest of that OS, its scheduler, permissions, and memory. The SWE-agent paper proved the stakes by coining the agent-computer interface: how tools and feedback are presented changes what a model can do, independent of the model. The field's advice has since converged on investing here rather than in framework plumbing, from Anthropic's build-simple guidance to Jerry Liu's argument that the framework era is over and the layers that matter now are skills, tools, and context quality. Those are the layers this list catalogs.

Why harnesses matter

Better models make harnesses more important: more capabilities mean more failure modes, and production needs retry logic, fallbacks, and validation. Harness quality, not just model quality, determines whether agents actually ship. This list ranks projects by relevance to harness concerns (environment, orchestration, lifecycle, guardrails) and by stars/activity.

The benchmark data now backs this up. On SWE-bench Pro, "swapping the agent harness changed pass@1 more than many model upgrades do" (AINews, Aug 8 2026, citing analysis by @joelniklaus). Same model, different harness: 23% to 52% pass@1 on GLM-5.2, and 15% to 36% on Gemma 4 26B. Harness rankings barely transfer across models (rank correlation -0.05), so a small model in the right harness can approach a much larger model in the wrong one.

That is the problem the MCP server in this repo solves. Point your agent at it and it can call recommend or pick_harness to choose a harness matched to your model and task, instead of inheriting whichever harness someone else benchmarked.

The landscape at a glance

Every project in the list, plotted by adoption surface area (the simplicity ↔ capability axis) against GitHub stars. Colors are categories; the largest projects in each tier are labeled.

The same projects placed by how much unsupervised rope they're designed to give (autonomy) and what happens when a run dies (recovery). In the tables below, ★ marks headless-ready projects and ✱ marks durable ones. Both charts regenerate from the list data on every refresh.

How to Pick a Harness

Start with the guide, then the head-to-head decision pages — grounded in the same data as the tables below:

• How to pick a harness: six questions that turn this list into a decision, plus the chart to internalize first (the harness moves scores more than the model)
• How to test-drive a harness: the two-week trial protocol, with a fair setup, tasks from your own repos, seven measurements, and the walk-away test
• OpenClaw vs Hermes — the always-on personal-agent debate: presence vs discipline, plus what the field reports actually say
• Terminal coding agents — opencode vs Codex vs Gemini CLI vs crush vs goose
• Multi-agent orchestration — OpenAI Agents SDK vs CrewAI vs AutoGen vs LangGraph
• Agent memory layers — Mem0 vs Letta vs claude-mem
• Agent sandboxing: what it is, the key concepts, and the field (E2B vs Daytona vs Modal and more)
• Agent evals (SWE-bench vs inspect_ai vs Terminal-Bench)
• Eval and observability platforms (Langfuse vs LangSmith vs Braintrust vs Phoenix)
• Browser agents (browser-use vs Stagehand vs Playwright MCP vs chrome-devtools-mcp)
• Browser infrastructure (Browserbase vs Steel vs Hyperbrowser)
• Claude Code skill packs (superpowers vs GStack vs get-shit-done vs Anthropic Skills)
• Context files for agents (AGENTS.md vs CLAUDE.md vs skills vs MCP tool search)

Pick by use case

Reader's index: pick by what you want to do, not by category. Tag chips (e.g. mcp · memory) next to each row let you cross-filter by capability — see TAGS.md for the full cross-reference.

• I want a turnkey coding agent today — opencode, Cline, Codex, Gemini CLI, OpenHands, crush · see Coding agent products (IDEs, CLIs, full suites)
• I want an always-on personal agent that lives in my chat apps — OpenClaw, Hermes, Khoj, Agent Zero, OpenHarness (HKUDS) · see Personal agent runtimes
• I want to extend Claude Code, Codex, or OpenCode with skills and slash commands — Anthropic Skills, wshobson/agents, superpowers, GStack, pmstack · see Coding harness configs and SDKs
• I want to build my own coding harness from scratch — Claude Agent SDK, Google ADK, AutoHarness, SWE-agent, RepoMaster, claw-code-agent · see Coding harness configs and SDKs
• I want a drop-in memory layer for agents — Mem0, Graphiti (Zep), claude-mem, agentlog, letta · see Plugins, MCPs, CLI tools
• I want to plug hundreds to thousands of tools without context bloat — MCP-Zero, ToolGen, ToolRAG, langgraph-bigtool · see Progressive disclosure harnesses
• I want multi-agent orchestration — openai-agents-python, crewAI, autogen, Microsoft Agent Framework, PraisonAI, agent-squad · see Multi-agent and orchestration
• I want a general LLM app framework — langgraph, langchain, llama-index, pydantic-ai, agno · see Frameworks
• I want low-code / visual workflows — langflow, Flowise, Dify, n8n · see Frameworks
• I want browser-using agents — browser-use, Stagehand, WebVoyager, puppeteer-real-browser-mcp · see Plugins, MCPs, CLI tools
• I want sandboxed code execution for agent-generated code — E2B, Agent Sandbox, Daytona, smolagents, OpenHands · see Libraries and SDKs
• I want to evaluate or benchmark agents — SWE-bench, Terminal-Bench, AgencyBench, inspect_ai, WebArena, VitaBench · see Evaluation and benchmarking harnesses
• I want a deep research / autonomous research agent — deepagents, gpt-researcher, openagents · see Research and task-specific harnesses
• I want a provider-agnostic LLM pipe (not a framework) — LiteLLM, vercel/ai · see Libraries and SDKs

For agents

This list is also published in machine-readable form, so coding agents and research agents can recommend harnesses — not just humans browsing GitHub:

• harnesses.json — every project with category, complexity tier, capability tags, stars, license signal, and a concrete example link, plus the full use-case index.
• llms.txt — the entire list in one agent-readable file. Point any agent at the raw URL.
• MCP server — recommend (one opinionated pick + alternatives + what to avoid, e.g. repos flagged for star manipulation), compare/compare_for (2–4 harnesses side by side — by id or by task — who leads on which axis incl. researched sandboxing/memory/hooks/prompt-optimization ratings, graveyard warnings, the matching decision guide), pick_harness (ranked, with complexity/autonomy/recovery filters), pick_infrastructure (picks at any level of the infra stack plus a live GitHub/Hacker News discovery pass, so answers aren't limited to this list), search_harnesses, get_harness, list_categories, plus list_comparisons/get_comparison for the decision guides. Published to PyPI and the official MCP registry as io.github.RyanAlberts/agent-harnesses. One-line install (needs uv):

claude mcp add agent-harnesses -- uvx agent-harnesses-mcp

Or hire a skeleton

Don't just read the list — agents/ ships three agent skeletons: open-source agents that run on the AI subscription you already pay for. Clone the file, customize the instructions, done. All three work against the current week's data and deliver to Slack or Notion when either is connected:

• harness-scout — describe what you're building; it picks your harness, with evidence and a graveyard check.
• stack-auditor — flags the harnesses in your codebase that died, and can trace your agent session logs to show how the harness steers your technical decisions.
• harness-radar — weekly movement briefing: climbers, arrivals, deaths, graduations.

curl -fsSL https://raw.githubusercontent.com/RyanAlberts/best-of-Agent-Harnesses/main/agents/harness-scout.md -o .claude/agents/harness-scout.md

Contents

• The landscape at a glance
• How to Pick a Harness
• Pick by use case
• For agents: harnesses.json, llms.txt, MCP server, agent templates
• FAQ
• Progressive disclosure harnesses 8 projects
• Coding agent products (IDEs, CLIs, full suites) 23 projects
• Coding harness configs and SDKs 17 projects
• Personal agent runtimes 11 projects
• Frameworks 26 projects
• Multi-agent and orchestration 12 projects
• Plugins, MCPs, CLI tools 19 projects
• Memory and state 5 projects
• Evaluation and benchmarking harnesses 19 projects
• Observability and eval-ops 4 projects
• Research and task-specific harnesses 5 projects
• Libraries and SDKs 15 projects

Guide to rankings

• ⭐ Stars — GitHub star count, captured 2026-09-09; tables sort by stars descending.
• ⚖️ Simplicity ↔ capability — adoption surface, 4 tiers: super simple (a format, one concept) → mostly simple (thin layer) → slightly complex (real SDK) → complex (product suite).
• ★ Headless-ready — designed for unattended runs, batches, and fleets (the top of the autonomy scale: step-gated → checkpoint-gated → bounded → headless).
• ✱ Durable — persisted execution state survives restarts mid-task (the top of the recovery scale: none → retry → resumable → durable).
• ✅ Open source — ✅ standard OSS license · ⚠️ source-available/restricted · ❓ no or unclear license.
• 🏷️ Tags — capability chips auto-derived from descriptions; full cross-reference in TAGS.md.
• 🎯 Examples — one concrete "show me it in action" link per project, not a docs root.

Every project's full autonomy and recovery tier is plotted in the grid above and carried in harnesses.json and llms.txt; scores are editorial, from public docs — maintainer corrections via issue/PR are merged fast.

Progressive disclosure harnesses

Formats, runtimes, and patterns that reveal context, tools, or instructions in layers—index first, details on demand—to control tokens and improve agent focus (the "map, not encyclopedia" principle).

#	Project	⭐ Stars	Description	Open source	Simplicity ↔ capability	Examples
1	Headroom	71k	Compresses tool outputs, logs, files, and RAG chunks with content-aware compressors before they reach the model—claimed 20% fewer tokens for coding agents and 60–95% fewer for JSON, same answers. Ships as a library, HTTP proxy, or MCP server, so it drops in front of whatever harness you already run. mcp · rag	✅	mostly simple (compression library/proxy/MCP server)	Project README
2	awesome-cursorrules	40.7k	Curated .cursorrules and skills that leverage Cursor's index-then-load model; the canonical collection for rules-as-progressive-disclosure in the IDE. ide	✅	super simple (content bundle)	PyTorch cursorrules
3	agents.md	24.2k	Open format for repo-scoped agent briefings; nested AGENTS.md files scope instructions per directory, so agents get a map of what exists and load only what's relevant. Read by 20+ tools including Codex, Cursor, and Copilot. ide · typescript	✅	super simple (format only)	Self-hosting AGENTS.md
4	context-mode	21.6k	Context-window optimization layer that sandboxes tool output before it reaches the model (claimed 98% reduction) and persists session memory across 17 agent platforms via MCP and hooks—progressive disclosure applied to tool results, not just instructions. mcp · memory · sandbox	⚠️ Elastic-2.0	mostly simple (output sandboxing, cross-platform)	Project README
5	langgraph-bigtool ✱	557	Build LangGraph agents with large tool sets; retrieval and on-demand tool loading so agents scale beyond context without stuffing every schema upfront. tool-discovery · python	✅	slightly complex (large tool sets)	Math-library tool agent
6	MCP-Zero	513	Active tool discovery for autonomous agents: model requests tools by requirement; hierarchical semantic routing over 308 servers / 2,797 tools with ~98% token reduction (APIBank). tool-discovery	✅	complex (3k tools, full routing)	APIBank experiment
7	ToolGen	184	ICLR 2025: unified tool retrieval and calling via generation; 47k+ tools without context stuffing—retrieval and invocation in one generative step. tool-discovery · python	❓	complex (47k+ tools)	Full eval pipeline
8	ToolRAG	33	Semantic tool retrieval for LLMs; serves only the tools the user query demands (MCP-compatible), unlimited tool sets with zero context penalty. mcp · tool-discovery	✅	mostly simple (query-driven retrieval)	MCP server retrieval

Coding agent products (IDEs, CLIs, full suites)

Turnkey coding agents you install and run: IDE extensions, terminal CLIs, Dockerized workspaces. Each entry notes which part is the harness (the agent loop, tool wiring, approval model) versus the UI shell (VS Code extension, TUI, browser client).