# Choosing the coding-agent CLI your agents run Source: https://codeherder.com/docs/harnesses/ The five coding-agent CLIs CodeHerder can launch, what stays the same across all of them, and the four things that actually change when you switch. A **harness** is the coding-agent CLI CodeHerder launches to do the work — Claude Code, Codex, Cursor, OpenCode, or Pi. Every agent’s launch config names one, and CodeHerder wraps it the same way regardless of which you pick: same sandbox, same stage machine, same briefs. But the harnesses themselves aren’t identical, and a few of the differences are worth knowing before you pick one. ## Where you set it In the web app, open an agent’s detail page and set **Harness** on a launch config — the **Command** field is derived automatically from your choice, so you don’t fill it in yourself. From the CLI: ``` ch agent config edit --harness ``` The default is `claude`. Whichever harness you choose has to be installed and signed in on the device that runs the agent — see [Managing your devices](https://codeherder.com/docs/devices/) for the readiness and sign-in checks. | Harness value | CLI launched | | --- | --- | | `claude` | `claude` (default) | | `codex` | `codex` | | `cursor` | `cursor-agent` | | `opencode` | `opencode` | | `pi` | `pi` | For every flag `config edit` and `config create` accept, see **Choosing a harness** in [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/#choosing-a-harness). ## What’s the same whichever you pick - Every session runs in its own [sandbox](https://codeherder.com/docs/agent-isolation/) — an isolated git worktree and branch, so parallel tasks never collide. - Every session follows the same [stage machine](https://codeherder.com/docs/how-work-flows/) and receives the same task brief, persona, and system prompt. - Every session can recall the workspace’s [wiki](https://codeherder.com/docs/memory/). - Skills delivery works for all five, with one nuance for Pi — see [Delivering skills to your agents](https://codeherder.com/docs/skills/). - All five open a real interactive terminal, so you can run any of them yourself with `ch start` — see [Start a session in your own checkout](https://codeherder.com/docs/local-sessions/). ## What changes when you switch ### Where the work can be placed Codex, Cursor, OpenCode, and Pi each require CodeHerder to have detected that specific CLI on a device before it will place a task there. Claude is the one exception: it’s the universal default, so a Claude agent isn’t limited to specially-detected devices. A device only picks up Codex, Cursor, OpenCode, or Pi work once CodeHerder has confirmed that CLI is present — see [Managing your devices](https://codeherder.com/docs/devices/) for how a device reports what it has installed. Cursor has a second gate on top of that: the device also has to report Cursor as **signed in**, not just installed, before a Cursor task lands there. ### Whether the session’s spend is recorded Claude Code, Codex, OpenCode, and Pi sessions all report spend turn by turn, and it rolls up into your costs and spend caps the same way. **Cursor sessions don’t record spend today**, task-bound or self-started with `ch start` — see [Understanding costs](https://codeherder.com/docs/costs/) for how spend tracking works for the harnesses that do report it. ### Whether the agent continues its own conversation on rework When a stage runs again — for example, review sends a task back for changes — Claude and Pi agents pick up the same conversation they had last time, with their prior reasoning intact. Codex, Cursor, and OpenCode agents start a fresh conversation instead: they work from the task, its comments, any hand-off notes, and the code already on the branch, which covers the same ground but without the prior turn-by-turn context. ### Model choice and usage pauses Choosing a model by tier (`model:opus`, `model:sonnet`, and so on) only applies to the Claude harness — see [Which model your agents run](https://codeherder.com/docs/agent-models/). A device’s usage pause keys on its Claude credentials, but it doesn’t stop only Claude agents. Once a device runs out of Claude usage, it stops taking new work for every agent on it, whatever harness each one runs. Running low on Codex or Cursor usage doesn’t pause anything — those meters are for visibility only. See [AI usage limits](https://codeherder.com/docs/ai-usage-limits/) for the full detail on what pauses a device and how it recovers. ## Running more than one harness for an agent An agent can carry more than one launch config, each with its own harness — useful for a primary harness with a fallback, or a different harness per stage. See **Running more than one launch config** in [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/#running-more-than-one-launch-config). ## Switching an existing agent’s harness `ch agent config edit` changes only the fields whose flag you pass — everything else on the config stays as it was. `--arg`, `--env`, `--cap`, `--credential-ref`, and `--allowed-model` are the exception within that: each one replaces its whole list when you pass it at all, so a call that touches one of those needs every value in that list you want to keep, not just a new one. See **What each edit actually changes** in [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/#what-each-edit-actually-changes) for the full rule. To switch harness on its own, pass `--harness ` by itself. Args, environment, and capabilities are untouched — only the harness changes, and the command re-derives for it: ``` ch agent config edit --harness codex ``` If you’re changing the harness *and* an `--arg`, `--env`, or `--cap` value in the same call, pass every value you want each of those lists to keep, since the call replaces them: ``` ch agent config edit --harness codex --env KEY=VALUE --cap ``` You don’t need `--command` when you pass `--harness` — the command re-derives automatically. If you do pass `--command`, it has to match the harness the config ends up with — `--command codex` on a config that’s still `claude` is rejected. See the **Flag reference** in [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/#flag-reference) for the full set. ## Related guides - [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/) — creating and configuring agents, launch configs, and the full flag reference - [Understanding costs](https://codeherder.com/docs/costs/) — how spend is tracked and which sessions report it - [Spend limits](https://codeherder.com/docs/spend-limits/) — per-agent and per-task spend caps - [Managing your devices](https://codeherder.com/docs/devices/) — device readiness checks, including Harness ready and Harness auth - [Why isn’t my task moving?](https://codeherder.com/docs/task-not-moving/) — diagnosing a device stuck on a sign-in or readiness check - [Which model your agents run](https://codeherder.com/docs/agent-models/) — tier-based model routing on the Claude harness - [AI usage limits](https://codeherder.com/docs/ai-usage-limits/) — the Claude usage pause - [Delivering skills to your agents](https://codeherder.com/docs/skills/) — how skills reach each harness