run

Run Skill

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

Explicit flags are definitive; otherwise the mode is inferred from prompt presence:

• --interactive (-i) → always interactive, even with a prompt (the prompt is forwarded as the first message).
• --headless → always headless, even with no prompt (the prompt is read from stdin).
• Neither flag, prompt provided → headless. Pipes stdout, no TTY, exits when the agent finishes.
• Neither flag, prompt omitted → interactive. Launches the agent's TUI with full stdio inheritance.

--interactive and --headless are mutually exclusive — passing both errors out.

# Interactive (TUI)
agents run claude

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

Modes

Permission mode controls what the agent can do.

agents run claude "fix lint errors in src/" --mode edit
agents run claude "/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, 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 no native smart-classifier mode, so agents run codex --mode auto resolves to sandboxed edit and can still prompt. agents run codex --mode skip instead bypasses approvals and removes the sandbox. Harnesses without a native bypass flag reject direct-exec skip.

Headless runs need a non-plan mode to act. The default plan is read-only, so an action command (e.g. /code:commit) run headless would otherwise stall forever at ExitPlanMode with no TTY to approve the plan. Running a slash command headless without an explicit --mode is rejected up front with a fix; pick --mode auto (recommended), edit, or skip. Pass --mode plan explicitly only when you genuinely want a read-only run.

Agents without a read-only mode (antigravity, cursor, kiro, …) cannot honor plan. agents run degrades unsupported plan to the agent's safest native mode (usually edit) and prints a warning — same idea as auto → edit on agents without a classifier. Prefer an explicit --mode edit to silence the warning. skip still hard-fails when the agent has no skip-permissions flag.

Note: auto and skip cannot be scoped to a directory — they are per-run modes, not per-repo. To restrict no-prompt behavior to one repository, use that repo's .claude/settings.json permissions.allow/deny rules (file rules are path-anchored; deny always wins) rather than a blanket mode.

Reasoning effort and model

# Reasoning effort (claude and codex only)
agents run claude "..." --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 claude "deploy the api" --secrets prod
agents run claude "..." --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 claude "..." --strategy balanced
agents run claude "..." -b                  # shortcut for --strategy balanced

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,gemini
agents run claude "..." --fallback [email protected],gemini

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          # kimi is a built-in preset (host + endpoint + model baked in)
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

A workflow's tools: and mcpServers: frontmatter now scope the run (Claude): tools: [Read, Grep] runs with --tools Read Grep, which restricts the available tool set — Write/Bash/Edit are unavailable in the session — and mcpServers: connects only the named registry servers via an ephemeral --mcp-config paired with --strict-mcp-config. Declarations on an agent without the allowlist capability warn rather than silently run unscoped.

See the workflows skill for authoring workflows.

Pin version

agents run [email protected] "..."

Resume a previous session (Claude only)

agents run claude --session-id <id>

Output and observability

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

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

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

Offload to another machine

agents run --host <name> runs the agent on a registered host over SSH instead of locally (see the devices skill). It follows live by default; --no-follow detaches and returns immediately.

agents run claude "profile this build" --host gpu-box   # follows live
agents run claude "..." --host gpu-box --no-follow       # detach

agents hosts ps          # list dispatched runs
agents hosts stop <id>   # terminate a hung/detached run (alias: kill)
agents logs --host gpu-box   # pick one and view its log
agents logs <id> -f          # re-attach to a running one and follow

Run options follow a strict forwarding contract on --host runs — nothing silently drops at the SSH boundary:

• Forwarded (same behavior remote as local): --mode --model --name --effort --env --add-dir --timeout --strategy/--balanced/--fallback, the --loop family, --json --verbose --yes --acp, --resume <id>, and -- <passthrough>.
• Rejected loud (exit non-zero before dispatch): --secrets/--secrets-keys/ --allow-expired (Keychain values never cross SSH implicitly — provision with agents secrets export --host instead), bare --resume (the picker can't cross a detached dispatch — pass a concrete id), --resume-checkpoint.
• Local-only (consumed by the dispatching side): --quiet --no-follow --cwd/--project/--remote-cwd --host/--device/--any --lease.

Hosts are also a task backend (agents cloud run "…" --host <name> — see the cloud skill) and a routines placement target (agents routines add … --run-on <name> — see the routines skill).

agents logs [id] is the unified viewer over both host-dispatch runs and local session transcripts; agents hosts logs <id> is the host-only equivalent. agents hosts stop <id> (alias kill) terminates the remote process group from this machine without deleting the remote log.

Working directory on the host

--cwd sets the directory the agent runs in on the host too — a home-anchored path (~/…, $HOME/…, or a local-home absolute your shell already expanded like /Users/me/…) is re-rooted at the remote $HOME, so it resolves across machines with different home paths (/Users/me → /home/me):

agents run claude "..." --host gpu-box --cwd ~/src/github.com/me/app
#   → runs on gpu-box in $HOME/src/github.com/me/app

-P, --project <slug>[@worktree] is a shorthand: it resolves <slug> against your projects root (auto-inferred from the repo you launch inside and cached in agents.yaml, e.g. ~/src/github.com/<user>), and @worktree targets a git worktree under .agents/worktrees/:

agents run claude "..." --host gpu-box --project app          # → $HOME/…/app
agents run claude "..." --host gpu-box --project app@fix-bug  # → app/.agents/worktrees/fix-bug
agents defaults project-root ~/src/github.com/<user>          # set/show the root

--remote-cwd <dir> is the explicit escape hatch — a literal remote path, used verbatim (not re-rooted). Precedence: --remote-cwd > --project/--cwd.

Bounded runs

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

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

Autonomous loop (--loop) + checkpoint/resume

--loop re-injects the prompt each iteration until a stop condition. The driver is deterministic; the agent inside stays free to spawn subagents. Every guard runs OUTSIDE the agent — the agent cannot vote past a kill-switch.

# Re-inject up to 5 turns, stop early on the agent's signal, 100k-token hard cap.
agents run claude "drive the migration to green" \
  --loop --until signal --max-iterations 5 --budget 100000 --interval 0 --mode skip

Each iteration pins its own fresh --session-id (--session-id creates a session — re-passing one errors Session ID already in use). To carry memory forward, iteration 2+ prepends /continue <prior session id> to the re-injected prompt so the agent recalls the prior turn first. Continuity is claude-only; other agents loop as independent fresh conversations (the driver warns). The driver hands the entrypoint AGENTS_LOOP_SIGNAL (path to write its {continue, reason} vote), AGENTS_RUN_DIR, and AGENTS_LOOP_ITERATION.

Checkpoint/resume. A checkpoint.json is written under ~/.agents/.history/runs/<runId>/ after every iteration (and on SIGINT/SIGTERM). Resume a killed run:

agents run claude --resume-checkpoint ~/.agents/.history/runs/<runId>/checkpoint.json --max-iterations 10

Resume continues from the last completed iteration with the same runId, prompt, and carried token count; the first resumed iteration /continues from the checkpoint's recorded session id (the last completed iteration's). CLI loop flags on a resume RAISE the checkpoint's bounds (e.g. a higher --max-iterations), so "continue, run more" is one command.

Budget guardrails (pre-flight estimate + hard kill)

When a budget: block is configured in agents.yaml (project > user), every run is gated:

• Pre-flight estimate. Before spawn, agents run prints [budget] est. $X for this <agent> run and, under on_exceed: block, refuses to launch if the run would breach any cap (per_run / per_day / per_agent / per_project). A block exits non-zero (code 2) — CI/headless inherit it.
• -y / --yes skips the interactive require_confirm_over confirm prompt for scripts. It does NOT skip a hard block — a cap breach blocks regardless.
• Live kill-switch. Local non-interactive (-p / headless) runs hard-stop the moment accumulated spend crosses a cap (SIGTERM → SIGKILL), resolving with a distinct exit code (7) — attached whether or not output is piped. Interactive REPL sessions rely on the pre-flight gate, not live kill. (agents teams teammates and agents cloud dispatch are gated pre-flight only in v1 — no live mid-run kill there yet.)

# Tiny per_run cap blocks before the agent ever starts:
$ agents run claude "huge refactor" --model claude-opus-4
[budget] est. $2.48 for this claude run (claude-opus-4, prompt size)
[budget] BLOCKED: estimated $2.48 exceeds per_run cap $0.01
$ echo $?   # 2

# Skip the confirm prompt in a script (still blocks on a hard cap):
agents run claude "..." --yes

Caps are cross-vendor: one per_project / per_day cap spans Claude, Codex, Gemini, and every other agent the CLI dispatches. View and set them with agents budget. Full reference: docs/06-observability.md.

Grant access to extra directories (Claude only)

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

Working directory

agents run claude "..." --cwd /path/to/repo
agents run claude "..." --project app          # shorthand: <root>/app

--cwd sets the working directory locally, and on the host for --host runs (see Working directory on the host). -P, --project <slug>[@worktree] resolves a project name against your cached projects root; set it with agents defaults project-root <path>.

ACP routing

Route through the Agent Client Protocol (Zed integration).

agents run gemini "..." --acp
agents run claude "..." --acp           # via @zed-industries/claude-code-acp adapter

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

Quick reference

For everything else, run agents run --help.