Agent Run

Agent Run

Use this skill when another agent needs a small command-line surface for invoking an agent-worker runtime. The default experience should feel like agent-browser: one executable, one short command, direct output, local sessions, no daemon ceremony.

Read references/runtime-wrapper.md when changing the CLI or adding a backend.

This skill is the lightweight CLI side of agent-worker's headless-first product shape. Use it for shell-capable agents that need an immediate invocation surface or a small set of local background sessions. Use the daemon or MCP surface only when the caller needs shared harness state, durable task ledgers, multi-agent coordination, or typed scheduling.

CLI First

skills/agent-run/scripts/agent-run codex "Investigate this failure and report the smallest fix."
skills/agent-run/scripts/agent-run cursor "Review the current diff and report risks."
skills/agent-run/scripts/agent-run ai-sdk "Summarize this repository state."
skills/agent-run/scripts/agent-run codex "Implement this bounded envelope" --worker-rule attention-driven
skills/agent-run/scripts/agent-run codex send "Fix the bug" --wait 5m
skills/agent-run/scripts/agent-run codex send "Explore auth failure" --session auth-failure --no-wait
skills/agent-run/scripts/agent-run sessions
skills/agent-run/scripts/agent-run sessions clean --older-than 7d
skills/agent-run/scripts/agent-run codex wait --wait 2m
skills/agent-run/scripts/agent-run codex peek --session auth-failure
skills/agent-run/scripts/agent-run codex status

Use --json when another agent or script will parse the result.

Use --skill <name> to load a project skill and prepend it to the agent's message (searches skills/<name>/SKILL.md in the local project, then ~/.hermes/skills/).

Use --worker-rule <name> for delegated worker prompts. It loads only skills/<name>/references/worker.md, not the full SKILL.md.

Use --timeout <duration> (default 300s) to cap one-shot invocations.

Interaction Model

The CLI mirrors the project interaction model:

Options:

• --model <model>: override backend model. For ai-sdk, use provider:model; agent-run checks the API key for that provider. If omitted, it scans local API key env vars and picks the first usable default, with DEEPSEEK_API_KEY first.
• --skill <name>: load a skill from skills/<name>/SKILL.md and prepend it to the task. Searches project-local skills/ first, then ~/.hermes/skills/.
• --worker-rule <name>: load skills/<name>/references/worker.md and prepend it to the task. Use this for bounded delegated workers, especially --worker-rule attention-driven.
• --timeout <duration>: cap one-shot invocations (default 300s). Use 30s, 5m, 1h.
• --wait <duration>: wait duration such as 30s, 5m, 1h.
• --session <name>: label a background run so parallel work can be tracked separately.
• --no-wait: send only.
• --older-than <duration>: for sessions clean, remove sessions older than this (default 7d).

Main Rule

Prefer the highest existing layer that fits the caller:

Do not force daemon startup for one-shot or local session paths. Use direct runtime access there. Do not recreate harness/task-ledger features inside agent-run; those remain daemon/MCP responsibilities.

Skill Loading Boundary

Direct runtime loops do not automatically load this repo's skills/ directory. Use --skill <name> to explicitly load a skill — agent-run reads the SKILL.md file and prepends it to the agent's message. Searches project-local skills/<name>/SKILL.md first, then ~/.hermes/skills/.

Do not use --skill attention-driven for a worker. attention-driven/SKILL.md is Main-Agent-only. Use --worker-rule attention-driven so the worker receives only references/worker.md plus the bounded task envelope.

Backend Shape

Supported direct backends are codex, cursor, claude-code / claude, and ai-sdk / ai. claude-code is wired for parity, but do not use it in this workspace while the Claude Code subscription is paused.

For parallel work, start each task with a session label:

skills/agent-run/scripts/agent-run codex send "Audit auth flow" --session auth-audit --no-wait
skills/agent-run/scripts/agent-run cursor send "Check build failure" --session build-fail --no-wait
skills/agent-run/scripts/agent-run sessions
skills/agent-run/scripts/agent-run codex wait --session auth-audit --wait 5m
skills/agent-run/scripts/agent-run codex peek --session build-fail

This borrows the useful part of Claude Code's agent view interaction: keep a compact list of background sessions and jump back only when one needs attention or has output.

ACP remains a useful mental model for the user-facing contract:

For ordinary use, stay at the CLI. Read references/runtime-wrapper.md only when extending or debugging the implementation.