background
Use when the user wants to see, inspect, cancel, or prune background agents fired during prior chain runs. Read/manage `.hyperflow/background/registry.json` and the per-agent output buffers at `.hyperflow/background/<id>.md`. Standalone — never auto-invoked. Trigger with /hyperflow:background, "list background agents", "what's running in background", "cancel background agent", "show background result".
Allowed Tools
Provided by Plugin
hyperflow
Fifteen specialized slash commands turn one Claude session into a structured multi-agent engineering pipeline. Thinking models orchestrate, triage, and review; worker models execute in parallel — every step is a Worker → Reviewer pair, and every non-trivial phase fans into sub-phases with their own reviewers. Auto-routing is on by default — say 'audit the diff', 'debug this test', 'large migration', or 'run a workflow' and the orchestrator routes to the right skill without the /hyperflow:* prefix. /hyperflow:workflow uses Claude Code dynamic workflows for big tasks and a portable Codex/OpenCode adapter where native workflows are unavailable; /hyperflow:spec asks the questions a senior engineer would; /hyperflow:scope decomposes into a batched task graph; /hyperflow:dispatch fans out persona-stitched workers under tiered review; /hyperflow:amplify rewrites a rough prompt into a high-quality one before you run it. 15 composable personas, 6 adaptive flow profiles, and persistent project memory compound across sessions. Works across Codex App/CLI, Claude Code, OpenCode, and Antigravity.
Installation
This skill is included in the hyperflow plugin:
/plugin install hyperflow@claude-code-plugins-plusClick to copy
Instructions
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 |
Print one agent's output buffer (.hyperflow/background/) |
cancel |
Cancel one specific in-flight agent |
cancel --all |
Cancel every in-flight agent (use before closing a session) |
prune |
Delete completed .hyperflow/background/ 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:
## 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: No background agents. and stop.
show
Read .hyperflow/background/ and print it verbatim. If the agent is still running, print the registry entry first then Output buffer not yet written. and stop.
cancel
- 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:. - Print
Cancelled.—
If the agent already completed, print Agent
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 runinbackground: 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— file contents of.hyperflow/background/..md cancel/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 for unknown id |
List 3 closest IDs by Levenshtein distance. |
cancel for already-completed agent |
Print Agent |
| Provider cancellation API unavailable | Mark entry status: cancelled in registry; the foreground orchestrator drops the result on collection. Print Marked |
| 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.