# Agent Run > 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. - Skill: `lidessen/agent-run` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add lidessen/agent-run` - Raw SKILL.md: https://api.skillmd.com/api/skills/lidessen/agent-run/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: lidessen (https://skillmd.com/u/lidessen) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lidessen/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 ```bash 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 ` to load a project skill and prepend it to the agent's message (searches `skills//SKILL.md` in the local project, then `~/.hermes/skills/`). Use `--worker-rule ` for delegated worker prompts. It loads only `skills//references/worker.md`, not the full `SKILL.md`. Use `--timeout ` (default `300s`) to cap one-shot invocations. ## Interaction Model The CLI mirrors the project interaction model: | Command | Meaning | |---|---| | `agent-run "message"` | direct one-shot invocation, daemonless | | `agent-run "message" --skill ` | one-shot with a project skill inlined | | `agent-run "message" --worker-rule ` | one-shot with only worker-facing rules inlined | | `agent-run send "message"` | direct send, optionally starting a local session | | `agent-run wait` | wait on a local session | | `agent-run peek` | inspect local session output | | `agent-run status` | direct runtime preflight | | `agent-run sessions` | list tracked background sessions | | `agent-run sessions clean` | remove completed/failed sessions older than 7d | Options: - `--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 `: load a skill from `skills//SKILL.md` and prepend it to the task. Searches project-local `skills/` first, then `~/.hermes/skills/`. - `--worker-rule `: load `skills//references/worker.md` and prepend it to the task. Use this for bounded delegated workers, especially `--worker-rule attention-driven`. - `--timeout `: cap one-shot invocations (default `300s`). Use `30s`, `5m`, `1h`. - `--wait `: wait duration such as `30s`, `5m`, `1h`. - `--session `: label a background run so parallel work can be tracked separately. - `--no-wait`: send only. - `--older-than `: 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 "..."` | | Another agent wants local background / waitable work | `skills/agent-run/scripts/agent-run send ... --session ... --no-wait` | | Another harness/agent wants durable task delegation | `task_create` + `task_dispatch(worker: "")`, or `aw task new` + `aw task dispatch --to ` | | 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 ` to explicitly load a skill — `agent-run` reads the `SKILL.md` file and prepends it to the agent's message. Searches project-local `skills//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: ```bash 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 "..."` | | session prompt | `agent-run send ...` | | session update | `agent-run wait ...` | | session history | `agent-run peek ...` | | initialization/readiness | `agent-run 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.