Run

Run Skill

Harness names in these examples are anchors, not prescriptions — substitute from the harnesses installed on this machine (agents view). Spreading runs across installed harnesses is the default; the teams-roster-guard enforces it for team rosters.

Dispatch a single agent for a one-off task. agents run is the fundamental command for interactive sessions and headless automation across Claude, Codex, Gemini, Cursor, OpenCode, and OpenClaw.

Headless vs interactive

• Prompt provided → headless. Pipes stdout, no TTY, exits when the agent finishes.
• Prompt omitted → interactive. Launches the agent's TUI with full stdio inheritance.

# Interactive (TUI)
agents run claude

# Headless one-shot
agents run grok "summarize recent git commits"

Modes

Permission mode controls what the agent can do.

agents run kimi "fix lint errors in src/" --mode edit
agents run codex "/code:commit" --mode auto          # run a command unattended, safely

Treat skip as a last resort. In direct-exec runs (without --acp), agents-cli forwards the harness's native bypass flag; it does not add another safety layer. Prefer auto where it adds a safer automatic policy (smart classifier on Claude/Copilot, never-prompt over a retained sandbox on Codex, native high-auto mode on Droid, or interactive Kimi), or edit everywhere else. For headless Kimi, edit, auto, and skip all use the same already-auto-approved -p behavior, so prefer edit rather than signaling a blanket bypass.

With --acp, these native flags are not used. agents-cli instead grants skip permission requests at the ACP protocol layer: it selects allow_always when offered, otherwise the first permission option offered by the server. The same last-resort warning applies.

Codex has three managed permission profiles rather than a smart classifier. edit and auto share one sandbox — workspace plus common build caches, network enabled — and differ only in approvals: edit requests them on demand, while auto is approval_policy=never, so it never prompts and a sandbox-denied command fails instead of raising a dialog. Use --mode auto for anything unattended; a prompt nobody answers is an agent that has stopped. When no configured run default exists, omitting --mode for Codex uses edit. Explicit --mode plan remains filesystem-read-only while retaining network access. agents run codex --mode skip instead bypasses approvals and removes the sandbox. Harnesses without a native bypass flag reject direct-exec skip.

plan is not universally read-only. Agents without a native read-only mode (including Antigravity, Cursor, and Kiro) warn and degrade plan to their safest native mode, which is usually writable edit. Headless Kimi has no read-only equivalent and rejects plan instead of silently running writable.

Reasoning effort and model

# Reasoning effort (claude and codex only)
agents run codex "..." --effort high

# Override the model directly
agents run claude "..." --model claude-opus-4-7

--effort accepts low | medium | high | xhigh | max | auto.

Secrets injection

Inject keychain-backed bundles as env vars at run time. Repeatable.

agents run kimi "deploy the api" --secrets prod
agents run droid "..." --secrets prod --secrets stripe

Bundles resolve from macOS Keychain (no plaintext on disk). See the secrets skill for bundle management.

For workflows with a frontmatter secrets: field, declared bundles auto-inject. Pass --no-auto-secrets to skip.

Pass env vars directly

agents run claude "..." --env DEBUG=1 --env API_KEY=xyz

Run strategy

Controls which installed version/account gets the work.

agents run opencode "..." --strategy balanced
agents run codex "..." -b                  # shortcut for --strategy balanced

# Select any named provider or native account
agents run claude "..." --account work

# Attach the account used when --account is omitted
agents accounts attach work claude

Strategy is ignored when @version is pinned, a profile is used, or --fallback is set.

Fallback chains

Retry on rate-limit by handing off to another agent via /continue.

agents run claude "..." --fallback codex,antigravity
agents run claude "..." --fallback codex@0.116.0,antigravity

Primary runs first; on rate-limit error, the next agent picks up.

Profile dispatch

Run any OpenAI-compatible model (Kimi, DeepSeek, Qwen, etc.) through a host CLI by passing a profile name in the agent slot.

agents profiles add kimi --host claude --endpoint https://api.moonshot.ai/anthropic --model kimi-k2-thinking
agents run kimi "..."

The profile bundles host CLI + endpoint + model + auth. See agents profiles --help.

Workflow dispatch

Pass a workflow name in the agent slot. agents-cli resolves the workflow directory (project > user > system), launches the host agent, and prepends WORKFLOW.md to the prompt as system instructions.

agents run code-review "review PR #42 on acme/api" --mode edit

See the workflows skill for authoring workflows.

Pin version

agents run claude@2.1.143 "..."

Resume a previous session (Claude only)

agents run claude --session-id <id>

Output and observability

# Stream ndjson events for parsing
agents run kimi "..." --json --quiet | jq

# Verbose execution logs
agents run claude "..." --verbose

--quiet drops the rotation banner and "Running:" preamble.

Bounded runs

Kill the agent after a duration. Useful in CI and scheduled jobs.

agents run droid "generate sales report" --timeout 30m
agents run opencode "..." --timeout 2h30m

Grant access to extra directories (Claude only)

agents run claude "refactor shared utils" --add-dir ../shared --add-dir ../other-pkg

Working directory

agents run codex "..." --cwd /path/to/repo

ACP routing

Route through the Agent Client Protocol (Zed integration).

agents run grok "..." --acp           # ACP-capable harness (see acp/harnesses registry)

Emits a unified event stream; ndjson when combined with --json.

Run in the cloud instead

agents run executes on this machine. To offload work to a remote backend — Rush Cloud (GitHub repo + branch, auto-opens a PR), Codex Cloud (pre-built env), or Factory pods — use agents cloud run:

agents cloud run "fix the flaky test" --provider rush --repo owner/repo
agents cloud run "add auth tests" --provider codex --env <env_id>

Scale past local capacity, dispatch async with --no-follow, and manage tasks with agents cloud list|status|logs|cancel. See the cloud skill.

Run on another machine (SSH)

A different axis from cloud: agents run --device <name> runs the agent on one of your own registered machines over SSH (no daemon). It follows live by default; --no-follow detaches.

agents run claude "profile this build" --device gpu-box   # run there, follow live
agents run kimi "..." --device gpu-box --no-follow        # detach

agents devices ps              # list dispatched runs
agents logs --device gpu-box   # pick a run on that host and view its log
agents logs <id> -f          # re-attach to a running one and follow

agents logs [id] is the unified viewer over device-dispatch runs and local session transcripts; scope it to one machine with --host <name>. See agents devices --help.

--remote-cwd <dir> — the working directory on the host, used verbatim. It is an agents run flag only: agents teams add rejects it with a hard error (a teammate's directory is --worktree <role> or --cwd <dir> instead — see the teams skill). Resolve the path on the remote: a bare ~/$HOME expands on your local box (/Users/you) and silently targets a path that doesn't exist on the remote (/home/you), so pass a valid remote absolute path or single-quote so $HOME expands there. For codex, point it at a real git repo on the target box (it refuses to start outside a trusted git dir).

Automatic fleet placement

--device auto lets the CLI choose a reachable machine from its automatic-placement pool. For a named harness, placement prefers a device with a healthy signed-in account, then the device with lower live load. An interactive trailing-@ picker launch also admits installed devices with a selectable signed-out or revoked-account login target, while still ranking a ready signed-in device first; a device whose picker would contain only throttled accounts stays excluded. If no machine is eligible, the command fails loud; it never silently degrades to the local machine.

agents run droid "fix the flaky test" --device auto
agents run claude "summarize logs" --device auto --no-follow

Use this as the default for "send this to the fleet" unless the task must land on a specific box. Mark worker machines with agents devices role <name> worker; once any worker is marked, automatic placement uses only marked workers. Mark the user's machine personal to exclude it. agents config set auto.pool all widens the pool past worker marks while still excluding personal devices.

Quick reference

For everything else, run agents run --help.

--account <name> selects any named provider or native account and overrides an agents accounts attach binding. Provider accounts are independent of agent versions and may be used by multiple compatible harnesses; the execution device resolves their secret locally and fails before spawn when it is absent. Native accounts retain their declared version or device scope and validate the harness-owned login before spawn without injecting a secret. Copy a provider bundle explicitly with agents accounts sync <name> <device>. Harness-native signed-in identities may be named with agents accounts name <agent@version> <name> and bound with agents accounts attach <name> <target>; their auth material remains in the harness home and is never copied. Accounts do not apply to cloud or lease placement.