CodeHerderSearch⌘KRequest access →

Choosing the coding-agent CLI your agents run

The six coding-agent CLIs CodeHerder can launch. See what stays the same and what changes when you switch, and how to sign each one in.

A harness is the coding-agent CLI CodeHerder launches to do the work — Claude Code, Codex, Cursor, OpenCode, Pi, or mini-swe-agent. 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 (derived) field is read-only. It updates when you change the harness, so you don’t fill it in yourself. From the CLI:

ch agent config edit <agent-id> --harness <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 for the readiness and sign-in checks.

Harness value CLI launched
claude claude (default)
codex codex
cursor cursor-agent
opencode opencode
pi pi
mini mini (mini-swe-agent)

For every flag config edit and config create accept, see Choosing a harness in Agents and the CLI.

What’s the same whichever you pick

  • Every session runs in its own sandbox — an isolated git worktree and branch, so parallel tasks never collide.
  • Every session follows the same stage machine and receives the same task brief and persona.
  • Every session can recall the workspace’s wiki.
  • Skills delivery works for all six, with a nuance for Pi and mini-swe-agent — see Delivering skills to your agents.
  • Five of the six open a real interactive terminal, so you can run them yourself with ch start: Claude Code, Codex, Cursor, OpenCode and Pi. mini-swe-agent runs only in task sessions. See Start a session in your own checkout.

What changes when you switch

Where the work can be placed

Codex, Cursor, OpenCode, Pi, and mini-swe-agent each require CodeHerder to have detected that specific CLI on a device before it will place a task there. Claude is the one exception for task work: it’s the universal default, so a Claude agent isn’t limited to specially-detected devices. A device only picks up Codex, Cursor, OpenCode, Pi, or mini-swe-agent work once CodeHerder has confirmed that CLI is present — see Managing your 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. ch start is different: it needs the harness installed on your machine, Claude included. It does not offer mini-swe-agent.

Whether the session’s spend is recorded

Claude Code, Codex, OpenCode, Pi, and mini-swe-agent 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 for how spend tracking works for the harnesses that do report it.

Whether the agent continues its own conversation on rework

When a stage that can change code, such as code, comes back with rework feedback, the agent picks up the same conversation it had last time, with its prior reasoning intact. This works on Claude Code, Codex, Cursor, OpenCode, Pi, and mini-swe-agent. The feedback arrives as a new message. A paused or interrupted session that restarts on the same device also continues where it stopped.

A conversation does not carry over in three cases:

  • A review or verify stage that runs again starts fresh, so it judges the code as it is now.
  • The rework runs on a different device from the first attempt.
  • The harness can’t find or won’t reopen the earlier conversation.

A fresh agent works from the task, its comments, any hand-off notes, and the code already on the branch. That covers the same ground, but without the prior turn-by-turn context.

Model choice

A model:<tier> capability (model:opus, model:sonnet, and so on) picks the model on every harness, but the way it works differs. Claude Code needs only the tier. Codex, Cursor, OpenCode, Pi, and mini-swe-agent need a model to name, so CodeHerder uses the first model on the config’s allowed-model list that belongs to the tier. Only Claude models belong to a tier. So the tier is useful on Cursor, OpenCode, Pi, and mini-swe-agent when the allowed list holds Claude models. A Codex config, whose models are GPT models, runs on Codex’s default model. The same happens on any harness when no allowed model matches. See Which model your agents run for the full rule.

Usage pauses

Each harness pauses on its own usage. When a device runs out of Claude usage, Claude agents on it stop taking new work. Agents on other harnesses keep running. The same holds the other way round.

  • Claude Code, Codex, and Cursor report usage from the device. An agent on one of them waits only when that harness’s usage on the device is used up. A Codex or Cursor meter counts once the device reports it.
  • OpenCode, Pi, and mini-swe-agent have no usage meter. After one of their runs ends with a quota error from the AI provider, CodeHerder holds new messages for that agent on that device for about 30 minutes.
  • If you add Codex credentials to a device, the device also stops taking Codex work when every one of them is disabled.

See AI credentials on a device for adding credentials, and AI usage limits for what pauses a device and how it recovers.

Approval prompts

Task sessions on all six harnesses run without waiting for you to approve tool calls, because no one is at the terminal. Cursor still refuses a command that its own settings deny. For a session you start yourself, --skip-permissions skips the prompts on Claude Code, Codex and Cursor. OpenCode and Pi refuse it. See Skipping permission prompts.

Signing the CLI in on a device

Each harness signs in its own way. Run the step on the device that runs the agent:

Harness How to sign in
Claude Code claude login
Codex codex login
Cursor cursor-agent login, or set CURSOR_API_KEY
OpenCode opencode auth login
Pi Pi has no login command. Set a provider API key, such as ANTHROPIC_API_KEY, in the device’s environment. Or use a credential file that is already signed in on another device.
mini-swe-agent mini has no login command. Put a provider key in a file and point the device at it. See Signing in mini-swe-agent.

The device’s Harness auth check shows whether the sign-in worked for all six harnesses. For mini-swe-agent it passes when the key file holds at least one provider key. See Why isn’t my task moving? if a device is stuck on it.

Signing in mini-swe-agent

  1. Create a file on the device. Put one KEY=VALUE line in it for each provider key you use. mini reads ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY and OPENROUTER_API_KEY.
  2. Set CH_MINI_API_KEY_FILE on the device to the path of that file.

CodeHerder reads the file again each time it starts a mini-swe-agent session, so you can change a key without restarting anything. It does not use keys from the device’s own environment. If an agent’s launch config sets the same key through its own environment or credential, that value wins.

To send requests through an OpenAI-compatible gateway, set CH_MINI_API_BASE on the device to the gateway’s https address.

What mini-swe-agent does differently

  • Task sessions only. ch start and a dev session refuse mini-swe-agent with “mini-swe-agent runs only with a task; use ch task create”. The web app’s new-session picker leaves it out. A task session can run it, and messages sent to that session still reach it.
  • Install. CodeHerder supplies its own build of mini to Linux devices, so there is nothing to install there. CodeHerder supplies no macOS build, and an upstream mini install fails the device’s health check. Use a Linux device for mini-swe-agent.
  • Skills. mini has no skills folder. CodeHerder lists each skill’s name, description and location in the agent’s prompt, and the agent reads the skill file when it needs it. See Delivering skills to your agents.
  • Project files. The agent’s prompt includes AGENTS.md and then CLAUDE.md from the session folder when they exist. A mini.yaml or .env in the repo is never loaded.
  • Approvals. mini runs commands without asking for each one. It has one tool, the shell.
  • Guardrails. Guardrails apply as on every other harness.

Seeded agents and Evaluations

  • The agents CodeHerder seeds into a new workspace carry a mini-swe-agent launch config, listed last. It pins a Claude model that matches the agent’s model tier. A workspace you created earlier keeps the configs it has. Add one with ch agent config create --harness mini.
  • To use a device pool for mini-swe-agent keys in Evaluations, add a file of KEY=VALUE provider keys with ch device credential create <label> --from-file <file> --harness mini. See AI credentials on a device.
  • An Evaluation setup that pins a mini-swe-agent model names it with a provider prefix: anthropic/, openai/ or gemini/. A CH_MINI_API_BASE gateway does not work inside an Evaluation attempt.

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.

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 for the full rule.

To switch harness on its own, pass --harness <harness> by itself. Args, environment, and capabilities are untouched — only the harness changes, and the command re-derives for it:

ch agent config edit <agent-id> --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 <agent-id> --harness codex --env KEY=VALUE --cap <capability>

ch agent config edit edits only the agent’s top launch config, the first one. To switch the harness on another config, use the Launch configs panel on the agent’s detail page. See Running more than one launch config.

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 for the full set.

Guardrails

Guardrails work the same on every harness. A command guardrail runs through a CodeHerder shim on the agent’s PATH, so every harness that runs the command reaches it. A report guardrail runs on the server when the agent advances the task. If you change a stage’s harness, the same guardrails apply, with the same messages and evidence.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close