| name | runs |
| description | Observe and CONTROL the engine's in-flight jobs: list every top-level run in the order the Stop hook
will advance them (the queue), pause/resume a single job, pause/resume the WHOLE engine, delete a run,
set a job's priority, and garbage-collect finished runs so `.agentflow/` doesn't grow forever.
USE this skill when the user wants to ACT on runs (not just look):
- "pause everything", "stop the engine", "freeze the runs", "resume" → global pause/resume;
- "pause/stop this run", "hold <id>", "resume <id>" → single-job pause/resume;
- "which run goes first", "what's the queue/order", "bump <id> up" → ordering / priority;
- "delete this run", "remove <id>", "clean up old/finished runs", "the runs folder is huge" → rm / clean.
DON'T use this for a read-only overview with suggestions (→ /agentflow:board) or to inspect one run in
depth (→ /agentflow:inspect show|tree <id>). `runs` is the *control panel*; board/inspect are read-only.
|
| allowed-tools | Bash, Read |
| argument-hint | [list|stop|resume|pause|rm|clean|priority] [<run-id>] [flags] |
| disable-model-invocation | false |
/agentflow:runs — the run control panel
A job is a run launched directly (a workflow/pipe, a do, or a standalone primitive). A pipe's
sub-runs (its stages) belong to their parent and are managed with it — runs lists and controls jobs,
not internal sub-runs. All commands go through one CLI:
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" <subcommand> [args]
See what's running and in what order
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" list
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" list --all
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" list --json
The POS column is the scheduling order the Stop hook follows each turn: higher priority first, then
oldest job first (FIFO). One run-step advances per turn; the oldest job runs to completion before the
next one starts (round-robin fairness is intentionally not implemented yet).
Two independent pause levels
| Scope | Pause | Resume | What it does |
|---|
| Whole engine | runs pause | runs resume | Creates/removes .agentflow/PAUSED. The Stop hook stops auto-resuming anything. The global "stop button". |
| One job | runs stop <id> | runs resume <id> | Sets a paused flag on that job (and its subtree). Other jobs keep advancing. |
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" pause
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" resume
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" stop my-run
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" resume my-run
Pausing is non-destructive — state is preserved; the run resumes exactly where it left off. Prefer
stop/pause over rm whenever the user just wants something to stop happening.
Reorder the queue
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" priority my-run 10
Delete and garbage-collect (destructive — confirm first)
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" rm my-run
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" clean
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" clean --failed
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" clean --all
node "${CLAUDE_PLUGIN_ROOT}/dist/runs.js" clean --older-than 7d --dry-run
rm refuses to delete a still-active job, or a child of a running pipe, unless --force — those
are the cases that would break an in-flight pipeline.clean only ever touches finished top-level jobs (and their subtrees), so it can never remove a
running job's children. Always offer --dry-run first when the user is unsure.
Rules
- Destructive ops need explicit intent.
rm and clean delete state on disk and cannot be undone.
Confirm the target with the user (show runs list --all or a --dry-run) before deleting. Never rm
an active run with --force unless the user explicitly asked to discard it.
- Reach for pause, not delete, when the goal is "stop it for now".
- Read-only siblings:
/agentflow:board for the session-start dashboard with suggestions;
/agentflow:inspect tree <id> to see a job's full child tree before removing it.
- Resolve an ambiguous id (same id under two primitives) with
<cmd>/<id>, e.g. pipe/my-run.
