Run

One command, every CLI. agents run <agent> "..." resolves the version, syncs the merged config, and launches the agent.

The shape

agents run claude "refactor the queue worker"
agents run codex  "fix the failing test in src/payments/"
agents run kimi   "draft a release note for v1.20"

Same flags work for every CLI. A prompt runs headless; omit it to drop into an interactive session under the resolved version.

Modes

--mode (-m) sets how much the agent may do without asking. Not every agent supports every mode — check agents.yaml capabilities.

plan — read-only investigation; no writes, no shell side-effects. The default.
edit — may edit files; prompts for shell and risky operations.
auto — a classifier auto-approves safe ops and prompts for risky ones (claude, copilot).
skip — bypass every permission prompt. Legacy full is silently rewritten to skip.

agents run claude "ship the migration" --mode edit
agents run claude "investigate the flaky test" --mode plan
agents run codex  "fix CI, no questions" --mode skip

Each mode translates to the harness's native permission flags. skip is the harness's own full-bypass flag: --dangerously-skip-permissions on claude, --dangerously-bypass-approvals-and-sandbox (the long form of --yolo) on codex, --yolo on gemini and kimi. The other modes never carry a bypass flag: on codex, plan runs --sandbox read-only and edit runs --sandbox workspace-write with network enabled.

Headless vs interactive

Passing a prompt auto-enables headless mode; omitting it opens the interactive TUI. Force either explicitly:

agents run claude "..." --headless       # stay headless, read prompt from stdin
agents run claude "..." --interactive    # open the TUI even with a prompt

Pipe headless output as JSON lines with --json; pair it with --quiet to drop the preamble (rotation banner, "Running:" line) so a parser sees only events:

agents run claude "..." --json --quiet | jq

Version and account selection

--strategy picks which installed version and signed-in account handle the run. It defaults to run.<agent>.strategy in agents.yaml, then balanced.

pinned — use the workspace/global pinned version.
available — use the pinned version if it can run right now; otherwise switch to another signed-in version.
balanced — spread load across healthy accounts by remaining capacity, skipping any that are rate-limited. -b / --balanced is shorthand. (Legacy rotate is accepted as an alias.)

agents run claude "run the full suite" --balanced
agents run claude@2.1.113 "..."            # pin overrides --balanced

See rotate accounts for the load-spreading model and agents usage.

Secrets

--secrets <bundle> injects a Keychain-backed credential bundle into the child process only — repeatable, and resolved at run time.

agents run claude "deploy the worker" --secrets prod --mode edit
agents run codex "..." --secrets stripe --secrets db   # multiple bundles

Narrow to a subset with --secrets-keys KEY1,KEY2, or override the pre-run expiry abort with --allow-expired. See secrets.

Naming and resolution

--name <slug> seeds the session label so the run shows up as <name> in agents sessions and resolves by it instead of an opaque id. An agent-generated title refines the label later.

agents run claude "cut the release" --name release-cut

Remote runs

The same command runs on another machine with one flag. --host (alias --device) offloads the run over SSH.

agents run claude "run the full suite" --device mac-mini
agents run claude "..." --host studio --no-follow   # dispatch detached

Remote runs →

Transport flags

--acp — route through the Agent Client Protocol instead of direct exec (gemini, claude). Emits ndjson with --json.
--no-tmux (alias --disable-tmux, --raw) — spawn the agent directly instead of wrapping it in the shared tmux session. Use this to see full startup output when a launch is failing.
--timeout <duration> — kill the agent after e.g. 30m, 2h30m.
--fallback <agents> — comma-separated agents to try on a rate-limit failure; the next picks up via a /continue handoff.

Native flag passthrough

Everything after a -- separator is forwarded verbatim to the underlying agent CLI. Use it for flags agents run does not model.

agents run kimi -- --plan --some-native-flag value
agents run claude "fix the bug" -- --custom-flag