The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="canonical" href="https://harness.autonomous.ai/agents">
<link rel="alternate" type="text/plain" href="https://harness.autonomous.ai/llms.txt" title="llms.txt">
<meta name="theme-color" content="#11110f">
<meta name="description" content="How a coding agent uses Harness to run Claude Code, Codex and other agents in parallel, wait for them, read their answers and close them: install, commands, exit codes and examples.">
<meta property="og:title" content="Harness for agents">
<meta property="og:description" content="Run Claude Code, Codex and other agents in parallel from your shell, wait for them and read their answers, while the person watches every one.">
<meta property="og:type" content="website">
<meta property="og:url" content="https://harness.autonomous.ai/agents">
<title>Harness for agents</title>
<link rel="icon" href="/icon.svg?v=5" type="image/svg+xml">
<style>
:root {
color-scheme: dark;
font: 400 16px/1.6 ui-monospace, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
--paper: #11110f;
--ink: #eeede8;
--muted: #a9a79f;
--line: #2e2d29;
--code: #1b1b18;
--accent: #e0ce41;
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--paper); color: var(--ink); }
main { width: min(84ch, calc(100% - 4ch)); margin: 0 auto; padding: 3rem 0 4rem; }
h1 { font-size: 1.5rem; margin: 0 0 1rem; }
h2 { font-size: 1.15rem; margin: 2.5rem 0 0.75rem; padding-top: 1rem; border-top: 1px solid var(--line); }
h3 { font-size: 1rem; margin: 1.5rem 0 0.5rem; }
p, ul, ol, table, pre { margin: 0 0 1rem; }
ul, ol { padding-left: 2ch; }
li { margin-bottom: 0.35rem; }
p, li, td { overflow-wrap: break-word; }
a { color: var(--accent); }
a:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
code { background: var(--code); padding: 0 0.3ch; border-radius: 3px; }
pre { background: var(--code); border: 1px solid var(--line); border-radius: 4px; padding: 0.75rem 1ch; overflow-x: auto; }
pre code { padding: 0; background: none; }
.table { overflow-x: auto; margin-bottom: 1rem; }
table { border-collapse: collapse; width: 100%; margin: 0; }
th, td { text-align: left; vertical-align: top; padding: 0.4rem 1ch; border-bottom: 1px solid var(--line); }
th { color: var(--muted); font-weight: 400; }
td:first-child { white-space: nowrap; }
.lead { color: var(--ink); }
.note { color: var(--muted); }
::selection { color: var(--paper); background: var(--accent); }
</style>
</head>
<body>
<main>
<h1>Harness for agents</h1>
<p class="lead">This page is for coding agents, and for the people who set them up. Harness runs coding agents
(Claude Code, Codex and others) in terminal sessions called harnesses. From its own shell, an agent can start
harnesses, wait for them, read their answers and close them. The person sees every harness in
the Harness app on their desktop, on the web and on their phone, and can watch it, answer it or stop it.</p>
<p class="note">A shorter, plain-text version is at <a href="/llms.txt">/llms.txt</a>.</p>
<h2 id="what">What Harness gives an agent</h2>
<ul>
<li><strong>Parallel harnesses.</strong> Start several agents on separate tasks, each in its own terminal, and
wait for all of them or for the first to finish.</li>
<li><strong>Another model.</strong> Claude Code can hand a task to Codex, and Codex to Claude Code.</li>
<li><strong>Another machine.</strong> Start a harness on the person's other computers, such as a Mac mini or a
GPU box, once they are signed in to Harness.</li>
<li><strong>Work that outlives the turn.</strong> A harness keeps running after your turn or your context ends,
and its conversation is kept when it is closed.</li>
<li><strong>The person's view.</strong> Everything you start appears in Harness, where the person can watch it,
answer its questions or stop it. Your own sub-agents are invisible to them.</li>
</ul>
<p>Every harness spends the person's tokens. Start one only for work that can run in parallel with yours, needs
another model's view (a review, a second opinion from Codex), takes long, or belongs in its own folder. Do quick
work yourself, and a quick parallel search or edit inside one task with your own sub-agents (Claude Code's Agent
tool, Codex sub-agents): they are cheaper and faster. Close each harness once you have its answer.</p>
<h2 id="when">Harness, or running <code>codex</code> yourself</h2>
<p>If Codex or Claude Code is installed, you can run it yourself for a one-off answer
(<code>codex exec "<task>"</code>, <code>claude -p "<task>"</code>). Use Harness instead when:</p>
<div class="table">
<table>
<thead><tr><th>The task</th><th>Why Harness</th></tr></thead>
<tbody>
<tr><td>The person should see the work, or may need to answer it</td><td>Every harness is in their Harness
app, where they can watch it, answer its questions or stop it. A process you run yourself is invisible to
them, and its questions go unanswered.</td></tr>
<tr><td>Several tasks at once</td><td><code>harness wait <name>,<name></code> waits for all of
them, or the first with <code>--any</code>.</td></tr>
<tr><td>Work that takes longer than your turn</td><td>A harness keeps running after your turn ends, and its
answer stays there to read.</td></tr>
<tr><td>Another of the person's machines</td><td><code>harness new --machine <machine></code>: no SSH,
once that machine runs Harness signed in to the person's account.</td></tr>
<tr><td>Cleaning up after yourself</td><td>Limits on how many you start, and Harness closes what you leave
behind.</td></tr>
</tbody>
</table>
</div>
<h2 id="install">Install</h2>
<pre><code>curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
harness start</code></pre>
<h3 id="install-steps">Install, step by step, for an agent</h3>
<div class="table">
<table>
<thead><tr><th>Step</th><th>Who</th><th>How</th></tr></thead>
<tbody>
<tr><td>1. Is it there already?</td><td>You</td><td><code>harness version</code>. Found: skip to step 4.</td></tr>
<tr><td>2. Ask before installing</td><td>The person</td><td>It installs software on their computer: ask
them first.</td></tr>
<tr><td>3. Install</td><td>You, once they agree</td><td><code>curl -fsSL
https://harness.autonomous.ai/cli/install.sh | bash</code>. On Linux it may need their password for
<code>apt-get</code>; without one, ask them to run <code>sudo apt-get install -y tmux curl</code> first. It
ends by saying what to run next.</td></tr>
<tr><td>4. Start Harness here</td><td>You</td><td><code>harness start</code>. No account is needed.</td></tr>
<tr><td>5. See what you may do</td><td>You</td><td><code>harness whoami</code>. It says whether you may start
harnesses, and if not, what to ask the person.</td></tr>
<tr><td>6. Sign in</td><td>The person</td><td><code>harness login</code>, in a browser. Needed for agents to
start harnesses, and for other machines.</td></tr>
<tr><td>7. Let agents start agents</td><td>The person</td><td>Settings ▸ Experimental ▸ Agents can start
other agents, or <code>harness settings agents-start-agents on</code> in their own terminal. It is their
consent: run by an agent, it is refused (exit 5).</td></tr>
<tr><td>8. Check</td><td>You</td><td><code>harness whoami</code> says <code>Can start harnesses: yes.</code></td></tr>
</tbody>
</table>
</div>
<p>macOS and Linux. <code>harness start</code> starts Harness on this computer. No account is needed for the
harnesses the person starts on this computer; <code>harness login</code> signs in, which the person needs for
their other machines, the phone app, and what they let agents do. The agents you start must be installed and
signed in to their own providers: <code>claude</code> for Claude Code, <code>codex</code> for Codex.</p>
<p>An agent starts harnesses only once the person turns on <strong>Agents can start other agents</strong>, an
experiment of their Harness account, off by default. Until then <code>harness new</code> refuses (exit 5) and
says how: tell the person, and do the work yourself. The agent commands are new: if <code>harness whoami</code>
is an unknown command, run <code>harness update</code>.</p>
<h2 id="skill">Add the skill</h2>
<p>The <code>harness</code> skill tells an agent when to use Harness and how. It comes as a plugin for Claude Code
and Codex, which also registers Harness's MCP server (<code>harness mcp</code>, over stdio).</p>
<h3>Claude Code</h3>
<pre><code>claude plugin marketplace add autonomous-ai/openharness --sparse .claude-plugin plugins
claude plugin install harness@openharness</code></pre>
<p>Inside a session, the same is <code>/plugin marketplace add autonomous-ai/openharness</code>, then
<code>/plugin install harness@openharness</code>. Without <code>--sparse</code> the whole repository is cloned,
several hundred megabytes, which takes a minute or more. Run <code>/reload-plugins</code> or start a new session
to load it. Adding a marketplace from GitHub needs git: on a Mac without Apple's developer tools, macOS first
offers to install them.</p>
<h3>Codex</h3>
<pre><code>codex plugin marketplace add autonomous-ai/openharness --sparse .claude-plugin --sparse plugins
codex plugin add harness@openharness</code></pre>
<p>Start a new Codex session to load it. Inside Codex, <code>/plugins</code> opens the plugin browser, where the
marketplace's plugins are listed once it is added.</p>
<h3>Any agent that reads SKILL.md</h3>
<pre><code>mkdir -p ~/.agents/skills/harness
curl -fsSL https://raw.githubusercontent.com/autonomous-ai/openharness/main/plugins/harness/skills/harness/SKILL.md \
-o ~/.agents/skills/harness/SKILL.md</code></pre>
<p>Codex reads skills from <code>~/.agents/skills</code>; Claude Code reads them from
<code>~/.claude/skills</code>.</p>
<h2 id="commands">The commands</h2>
<div class="table">
<table>
<thead><tr><th>Command</th><th>What it does</th></tr></thead>
<tbody>
<tr><td><code>harness whoami</code></td><td>Who you are to Harness: which agent, on which machine, inside Harness or
not; whether you may start harnesses now and, if not, who can change that; how many of yours are open. Run it
first.</td></tr>
<tr><td><code>harness ps [--all]</code></td><td>The harnesses on this machine: name, agent, state, who started it,
when it was last active, its folder and what it is about. <code>--all</code> adds the ones stopped in the
last week.</td></tr>
<tr><td><code>harness new [agent] [--machine NAME] [folder | project] --name NAME -- TASK</code></td><td>Start a harness and give
it a task. <code>agent</code> is <code>claude</code> (the default), <code>codex</code>, or another agent
installed there. The folder is the current directory when left out. For scratch or new work, give a project
name (<code>harness new codex review -- …</code>) rather than a folder of your own: Claude Code and Codex ask
the person to trust a folder Harness did not make.</td></tr>
<tr><td><code>harness wait NAME[,NAME…] [--any] [--timeout 30m]</code></td><td>Wait until each harness stops
working. <code>--any</code> returns when the first one does. The timeout takes <code>90s</code>,
<code>30m</code> or <code>2h</code> (30 minutes by default); <code>0</code> waits as long as it
takes.</td></tr>
<tr><td><code>harness show NAME [--chars N]</code></td><td>Its state, the last thing it was asked, and its answer:
the text after its last tool call, the first 4,000 characters by default.</td></tr>
<tr><td><code>harness send NAME "text"</code></td><td>A message to a teammate in your tab, while Agent Messages
are on (Settings ▸ Experimental, off by default). A harness you started is no exception. Works from inside a
harness.</td></tr>
<tr><td><code>harness close NAME [--now]</code></td><td>Save its screen and stop it. Its conversation is kept, and
the person can resume it. Refused while it is working, unless <code>--now</code>.</td></tr>
</tbody>
</table>
</div>
<p>Name every harness you start with <code>--name</code>: an unnamed one takes its session's title, which changes.
Every command also takes the start of a harness's id, takes <code>--json</code> for JSON, and prints its usage
with <code>--help</code>. Every command ends with <code>Next:</code>, the command to run next (in JSON,
<code>next</code>), and every error says what to run next. A harness waiting on a question or a permission is
shown as <code>needs the person</code>: tell the person. <code>harness help agents</code> prints the commands,
states, exit codes and rules on one screen.</p>
<p id="no-prompts">Once Harness runs on a computer, Claude Code and Codex there run these commands and Harness's MCP
tools without asking: Harness adds them to their permission rules (Claude Code's <code>settings.json</code>,
Codex's <code>rules/harness.rules</code>), and Codex runs them outside its sandbox. What an agent may do with them
is still Harness's to decide: the person's switch for agents starting agents, the limits below, and closing only
what it started. Run each command by itself, or join them with <code>&&</code>; piped into another command,
after <code>;</code>, or with a variable set in front, the rule no longer matches.</p>
<h3 id="exit-codes">Exit codes</h3>
<div class="table">
<table>
<thead><tr><th>Code</th><th>Meaning</th></tr></thead>
<tbody>
<tr><td><code>0</code></td><td>Done. For <code>wait</code>: every harness is idle; read it with <code>harness show</code>.</td></tr>
<tr><td><code>1</code></td><td>Failed. The message says what to run next.</td></tr>
<tr><td><code>2</code></td><td>The command was used wrongly; the usage follows.</td></tr>
<tr><td><code>3</code></td><td><code>wait</code>: a harness needs the person (a question or a permission). Tell
the person; only they answer it.</td></tr>
<tr><td><code>4</code></td><td><code>wait</code>: a harness stopped or is gone.</td></tr>
<tr><td><code>5</code></td><td>Refused: your limits, the person's setting, or a harness you did not start. Do not
retry it; tell the person, or do the work yourself.</td></tr>
<tr><td><code>124</code></td><td><code>wait</code>: timed out while a harness was still working. Wait again, or
read it.</td></tr>
</tbody>
</table>
</div>
<p>When several apply, <code>wait</code> exits with the first of 124, 3 and 4.</p>
<h2 id="parallel">Run Claude Code agents in parallel</h2>
<pre><code>harness new claude --name api-tests -- "Make the tests in api/ pass. Change only files in api/. Answer with what you changed and why."
harness new claude --name ui-tests -- "Make the tests in ui/ pass. Change only files in ui/. Answer with what you changed and why."
harness wait api-tests,ui-tests --timeout 45m
harness show api-tests
harness show ui-tests
harness close api-tests
harness close ui-tests</code></pre>
<p>Each harness is a full Claude Code session in its own terminal, in the folder you ran the command from. Give
harnesses that edit files separate folders or separate files (a git worktree each works well): two agents
editing the same file overwrite each other's work.</p>
<h2 id="wait">Wait for a background agent to finish</h2>
<pre><code>harness wait reviewer --timeout 30m</code></pre>
<p>Its exit code says how it ended. <code>0</code>: it is idle, read it with <code>harness show reviewer</code>. <code>3</code>: it is waiting for the
person; tell them, and do not answer it yourself. <code>4</code>: it stopped. <code>124</code>: it is still
working; wait again. With several names, <code>--any</code> returns as soon as one finishes. A harness counts as
finished when it has stopped working on two looks in a row, three seconds apart, so a short pause between tool
calls does not end the wait.</p>
<h2 id="codex">Hand a task to Codex and read its answer</h2>
<pre><code>harness new codex --name reviewer -- "Review the changes on this branch against main for bugs. Do not edit files. Answer with the findings, most serious first, each with file and line."
harness wait reviewer --timeout 20m && harness show reviewer
harness close reviewer</code></pre>
<p>Put the whole task in it: what to do, where, what done looks like, and what to answer with. A task holds 2,000
characters; for a longer one, write it to a file and name the file in the task. <code>show</code> cuts long
answers at 4,000 characters and prints how to read the rest (<code>--chars N</code>).</p>
<h2 id="background">Keep working while another agent reviews</h2>
<pre><code>harness new codex --name reviewer -- "Review commit 3f2a9c1 for bugs. Do not edit files. Answer with the findings."
# … go on with your own work; harness new returned as soon as the harness started …
harness ps # is it still working?
harness wait reviewer && harness show reviewer</code></pre>
<p>Starting a harness does not let you message it, so put everything in the task. For a follow-up, start a new
harness with the fuller task. Only in a tab you share, while Agent Messages are on, can you
ask it from inside a harness, with <code>harness send reviewer "…"</code>, then wait and show again.</p>
<h2 id="machines">Run on another machine</h2>
<pre><code>harness machines
harness new codex --machine mini ~/code/app --name train -- "Run the training script and report the final loss."</code></pre>
<p>Needs the person signed in to Harness on both computers (<code>harness login</code>). <code>harness ps</code>
lists this machine; <code>harness ps --machine mini</code>, <code>harness show --machine mini train</code> and
<code>harness wait --machine mini train</code> reach the other.</p>
<h2 id="where">Inside a harness, or outside Harness</h2>
<ul>
<li><strong>In a harness</strong> (Harness made your terminal pane): <code>harness send</code> works only to
teammates in your tab, while Agent Messages are on (Settings ▸ Experimental, off by default). A harness you started,
or the one that started you, is no exception.</li>
<li><strong>Outside Harness</strong> (Claude Code or Codex in a terminal app, an editor or the person's own tmux):
Harness tells you by your session, from what your agent sets in its shell. <code>harness whoami</code> (and the
top of <code>harness ps</code>) says "You: <agent>, outside Harness, on <machine>.", and
<code>harness ps</code> marks what this session started as <code>you</code>; the limits
below apply; each harness you start reads
<code>[from Claude Code outside Harness · <machine>, the agent that started you. It reads your answer itself.]</code>
above its task; and you may close only what this session started. Nothing can message you, and
<code>harness send</code> is not available: put everything in the task, and for a follow-up start a new
harness with the fuller task.</li>
</ul>
<h2 id="mcp">MCP tools</h2>
<p><code>harness mcp</code> serves the same commands as MCP tools over stdio, for agents that reach their tools
through MCP (the plugin above registers it). Configure it as command <code>harness</code> with arguments
<code>["mcp"]</code>.</p>
<div class="table">
<table>
<thead><tr><th>Tool</th><th>Arguments</th><th>Same as</th></tr></thead>
<tbody>
<tr><td><code>harness_whoami</code></td><td>none</td><td><code>harness whoami</code></td></tr>
<tr><td><code>harness_list</code></td><td><code>all?</code></td><td><code>harness ps</code></td></tr>
<tr><td><code>harness_start</code></td><td><code>task</code>, <code>name</code>, <code>folder?</code> or
<code>project?</code> (a new project for scratch or new work), <code>agent?</code> (<code>claude</code> or
<code>codex</code>), <code>machine?</code></td><td><code>harness new</code></td></tr>
<tr><td><code>harness_wait</code></td><td><code>names</code>, <code>any?</code>, <code>timeout_seconds?</code>
(120 by default, 600 at most; if they are still working, call it again)</td><td><code>harness wait</code></td></tr>
<tr><td><code>harness_read</code></td><td><code>name</code>, <code>chars?</code></td><td><code>harness show</code></td></tr>
<tr><td><code>harness_close</code></td><td><code>name</code>, <code>now?</code></td><td><code>harness close</code></td></tr>
<tr><td><code>harness_send</code></td><td><code>to</code>, <code>text</code>; offered only when the server runs
inside a harness, and only to teammates in its tab while Agent Messages are on</td><td><code>harness send</code></td></tr>
</tbody>
</table>
</div>
<h3 id="mcp-clients">Add it to a client</h3>
<pre><code>{"mcpServers": {"harness": {"command": "harness", "args": ["mcp"]}}}</code></pre>
<p>Or in one step, once Harness is installed:
<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=harness&config=eyJjb21tYW5kIjoiaGFybmVzcyIsImFyZ3MiOlsibWNwIl19">Add to Cursor</a>,
<a href="vscode:mcp/install?%7B%22name%22%3A%22harness%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22harness%22%2C%22args%22%3A%5B%22mcp%22%5D%7D">Add to VS Code</a>
(<a href="vscode-insiders:mcp/install?%7B%22name%22%3A%22harness%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22harness%22%2C%22args%22%3A%5B%22mcp%22%5D%7D">Insiders</a>),
<a href="lmstudio://add_mcp?name=harness&config=eyJjb21tYW5kIjoiaGFybmVzcyIsImFyZ3MiOlsibWNwIl19">Add to LM Studio</a>,
or in Claude Code <code>claude mcp add harness -- harness mcp</code>. An app opened from the Finder may not have
<code>~/.local/bin</code> on its PATH; if it cannot find <code>harness</code>, give it the full path that
<code>command -v harness</code> prints.</p>
<h2 id="rules">Rules</h2>
<ul>
<li>Give work only to harnesses you started. A harness the person started is theirs: you may read it and wait on
it, but do not send it work or close it.</li>
<li>Never answer a harness's question or permission prompt, and never type into it some other way. Tell the
person.</li>
<li>Never ask another harness to publish, deploy, delete or push. Those are the person's to ask for.</li>
<li>Close what you started once you have its answer.</li>
<li>An agent may have at most 4 live harnesses it started, and start 20 in 10 minutes. A harness another agent
started may not start harnesses itself: it does the work itself, or says in its answer what else is needed.
Each machine allows 40 live harnesses started by agents. Every limit refuses with a message; do not work around
it.</li>
<li>Harness cleans up after agents: closing a harness closes the harnesses it started, and one another agent
started is closed once it has sat idle 30 minutes after its last answer, unless the person typed into it. Its
conversation is kept, and <code>harness show</code> still reads its answer.</li>
<li>A harness you start runs in its agent's auto mode, with the agent's own checks on. <code>--mode full</code>
(checks and sandbox off) is the person's to choose: from an agent it is refused.</li>
</ul>
<h2 id="errors">When something fails</h2>
<ul>
<li><code>harness: command not found</code>: Harness is not installed; see <a href="#install">Install</a>.</li>
<li><code>Harness is not running here. Start it with `harness start`.</code></li>
<li><code>Harness is running, but a sandbox keeps this shell from reaching it.</code> Codex runs commands in a
sandbox, and <code>harness</code> talks to Harness's local daemon, which the sandbox blocks. Where Harness set
Codex up, run the command by itself (see <a href="#no-prompts">above</a>) and it runs outside the sandbox without
asking; elsewhere, run it outside the sandbox, asking for escalated permissions. Do not run
<code>harness start</code> for it.</li>
<li><code>That machine is not reachable now. `harness machines` lists which are online.</code></li>
</ul>
<h2 id="more">More</h2>
<ul>
<li><a href="https://github.com/autonomous-ai/openharness/blob/main/plugins/harness/skills/harness/SKILL.md">The harness skill</a></li>
<li><a href="https://github.com/autonomous-ai/openharness/tree/main/plugins/harness">The Claude Code and Codex plugin</a></li>
<li><a href="https://github.com/autonomous-ai/openharness/blob/main/docs/design/2026-10-11-agent-client.md">How the agent commands work, and why</a></li>
<li><a href="https://github.com/autonomous-ai/openharness">Source</a> (MIT)</li>
<li><a href="/download">Download the Harness app</a>, for the person</li>
</ul>
</main>
</body>
</html>