| name | agent-run |
| description | Run agents through a lightweight `agent-browser`-style CLI. Use when another agent needs `agent-run codex|cursor|claude-code|ai-sdk ...` as an immediate direct call, or local send/peek/wait sessions without depending on the daemon. |
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:
| Command | Meaning |
|---|
agent-run <agent> "message" | direct one-shot invocation, daemonless |
agent-run <agent> "message" --skill <name> | one-shot with a project skill inlined |
agent-run <agent> "message" --worker-rule <name> | one-shot with only worker-facing rules inlined |
agent-run <agent> send "message" | direct send, optionally starting a local session |
agent-run <agent> wait | wait on a local session |
agent-run <agent> peek | inspect local session output |
agent-run <agent> status | direct runtime preflight |
agent-run sessions | list tracked background sessions |
agent-run sessions clean | remove completed/failed sessions older than 7d |
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:
| Caller need | Use |
|---|
| Another agent wants a simple immediate command | skills/agent-run/scripts/agent-run <agent> "..." |
| Another agent wants local background / waitable work | skills/agent-run/scripts/agent-run <agent> send ... --session ... --no-wait |
| Another harness/agent wants durable task delegation | task_create + task_dispatch(worker: "<agent>"), or aw task new + aw task dispatch --to <agent> |
| Repo code needs a runtime directly | AgentLoop implementations from @agent-worker/loop |
| Runtime selection comes from harness config | packages/agent-worker/src/loop-factory.ts |
| You need to inspect protocol drift | backend-specific wrapper, such as internals/loop/src/loops/codex.ts |
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:
| ACP idea | agent-run / agent-worker surface |
|---|
| one-shot prompt | agent-run <agent> "..." |
| session prompt | agent-run <agent> send ... |
| session update | agent-run <agent> wait ... |
| session history | agent-run <agent> peek ... |
| initialization/readiness | agent-run <agent> status |
| runtime implementation | AgentLoop / backend wrapper |
For ordinary use, stay at the CLI. Read references/runtime-wrapper.md only when extending or debugging the implementation.
