Background
Read-only-by-default management interface for background agents fired by other hyperflow skills (dispatch quality gates, deploy CI watcher, scaffold analysis refresh, cache compact, scope speculative prefetch). Reads from .hyperflow/background/registry.json + per-agent output buffers.
Full doctrine: background-agents.md.
Subcommands
| Subcommand | Description |
|---|---|
list | Print the registry: in-flight · completed-uncollected · stalled · errored |
show <id> | Print one agent's output buffer (.hyperflow/background/<id>.md) |
cancel <id> | Cancel one specific in-flight agent |
cancel --all | Cancel every in-flight agent (use before closing a session) |
prune | Delete completed .hyperflow/background/<id>.md files older than 7 days |
Default subcommand when none provided: list.
Subcommand Details
list
Read .hyperflow/background/registry.json. Group entries by status and print a compact table:
markdown## In flight (N) | ID | Purpose | Fired | Timeout | Blocks | |-----------------------------------|--------------------------------------|------------|---------|---------| | `bg-1718049600-quality-gates-b2` | Layer 5 gates Batch 2 | 17:30 | 18:00 | step3 | | `bg-1718049820-ci-watcher` | GitHub Actions watch for v4.7.0 | 17:33 | 18:33 | — | ## Completed (uncollected, N) | ID | Purpose | Completed | Duration | Output | |-----------------------------------|--------------------------------------|------------|----------|--------| | `bg-1718045400-scaffold-refresh` | Refresh .hyperflow/architecture.md | 16:42 | 2m 18s | 1.4kb | ## Stalled / Errored (N) | ID | Purpose | Status | Reason | |-----------------------------------|--------------------------------------|-------------------|-------------------| | `bg-1717980000-cache-compact` | Compact learnings.md | STALLED | timeout (30m) |
Print one trailing line: <count> in flight · <count> uncollected · <count> needs attention. If registry is empty, print No background agents. and stop.
show <id>
Read .hyperflow/background/<id>.md and print it verbatim. If the agent is still running, print the registry entry first then Output buffer not yet written. and stop.
cancel <id>
- Read registry, find the entry.
- If
status: running, signal cancellation per the provider's mechanism (Claude Code: use the runtime's cancellation API for that subagent ID; if unavailable, mark the entrystatus: cancelledand leave the agent to time out on its own — the foreground orchestrator will drop the result on collection). - Update registry entry:
status: cancelled,cancelled_at: <now>. - Print
Cancelled <id> — <purpose>.
If the agent already completed, print Agent <id> already <status> — nothing to cancel.
cancel --all
For every entry with status: running, run the cancel flow. Print summary: Cancelled N agents.
prune
find .hyperflow/background/ -name "bg-*.md" -mtime +7 -delete plus remove their entries from registry.json (only entries with status: complete | error | stalled | cancelled older than 7 days are pruned). Print: Pruned N output buffers · N registry entries.
Flow
- Parse subcommand from invocation (default:
list). - Read
.hyperflow/background/registry.json(if absent, treat as empty). - Execute subcommand.
- Print result.
Overview
/hyperflow:background is the user-facing read/manage interface for background agents. The orchestrator itself maintains the registry as a side-effect of run_in_background: true Agent dispatches in other skills — this skill never fires a background agent, it only reads/manages the registry.
Prerequisites
.hyperflow/background/registry.jsonexists (created on first background dispatch by any other skill — if absent, all subcommands degrade gracefully)..hyperflow/initialized (run/hyperflow:scaffoldif missing — though this skill works even without scaffold, since the registry is created on demand).
Instructions
See Subcommands and Subcommand Details. Summary:
- Parse the subcommand (default
listwhen none given). - Read the registry from
.hyperflow/background/registry.json. - Execute the subcommand against the registry + per-agent output buffers.
- Print compact result; do not modify any source code.
Output
list— table of in-flight / completed-uncollected / stalled+errored, with one trailing summary line.show <id>— file contents of.hyperflow/background/<id>.md.cancel <id>/cancel --all— one-line confirmation per cancelled agent + total.prune— count of pruned buffers + registry entries.
Error Handling
| Failure | Behavior |
|---|---|
| Registry file missing | Treat as empty — list prints No background agents.; other subcommands print No registry — fire a background agent first. and stop. |
| Registry JSON malformed | Print Registry malformed — back up to .hyperflow/background/registry.json.bak and re-create empty. Move file, write empty registry, continue. |
show <id> for unknown id | List 3 closest IDs by Levenshtein distance. |
cancel <id> for already-completed agent | Print Agent <id> already <status> — nothing to cancel. |
| Provider cancellation API unavailable | Mark entry status: cancelled in registry; the foreground orchestrator drops the result on collection. Print Marked <id> as cancelled (provider has no live cancellation API — agent will run to completion or timeout, but result will be discarded). |
| Prune called with no eligible entries | Print Nothing to prune — no completed buffers older than 7 days. |
Examples
List in-flight + completed background agents
/hyperflow:background list ## In flight (1) | ID | Purpose | Fired | Timeout | Blocks | |-----------------------------------|--------------------------------------|-------|---------|--------| | `bg-1718049600-quality-gates-b2` | Layer 5 gates Batch 2 | 17:30 | 18:00 | step3 | ## Completed (uncollected, 1) | ID | Purpose | Completed | Duration | Output | |-----------------------------------|--------------------------------------|-----------|----------|--------| | `bg-1718045400-scaffold-refresh` | Refresh .hyperflow/architecture.md | 16:42 | 2m 18s | 1.4kb | 1 in flight · 1 uncollected · 0 needs attention
Show a completed agent's output
/hyperflow:background show bg-1718045400-scaffold-refresh # Background Result — Refresh .hyperflow/architecture.md | Field | Value | |------------|--------------------------------------| | Agent ID | `bg-1718045400-scaffold-refresh` | | Fired at | 2026-05-16T16:40:00Z | | Completed | 2026-05-16T16:42:18Z (2m 18s) | | Status | complete | | Tokens | worker 4.2k | ## Output <refreshed architecture.md content fragments + diff summary>
Cancel everything before closing the session
/hyperflow:background cancel --all Cancelled bg-1718049600-quality-gates-b2 — Layer 5 gates Batch 2 Cancelled bg-1718049820-ci-watcher — GitHub Actions watch for v4.7.0 Cancelled 2 agents.
Resources
- background-agents.md — full doctrine: when to use, hard rules, registry shape, failure modes, anti-patterns.
- DOCTRINE.md — rule 8 (background extensions), rule 9 (no AI-attributed background commits).
- output-style.md — table conventions for
listoutput.
