07f02e77db
New optional command between /ultraresearch-local and /ultraplan-local that matches brief+research against Claude Code features (hooks, subagents, skills, output-styles, MCP, plan-mode, worktrees, background-agents) and produces an architecture note with brief-anchored rationale plus explicit gaps. Added: - commands/ultra-cc-architect-local.md (--project, --fg, --quick, --no-gaps) - agents/architect-orchestrator.md (opus) — 6-phase background orchestrator - agents/feature-matcher.md (sonnet) — fallback-ranked feature proposals - agents/gap-identifier.md (sonnet) — 4 gap classes with issue-ready drafts - agents/architecture-critic.md (sonnet) — hallucination gate as BLOCKER - skills/cc-architect-catalog/ — SKILL.md + 10 seed entries (reference/pattern) Changed (non-breaking): - commands/ultraplan-local.md — auto-discovers architecture/overview.md - agents/planning-orchestrator.md — cross-references cc_features_proposed - plugin.json — 2.1.0 → 2.2.0, description, cc-architecture keyword - CHANGELOG, README, CLAUDE.md (plugin + marketplace root) Pipeline becomes brief → research → architect → plan → execute. Architect is optional; existing project dirs keep working unchanged. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
106 lines
3.6 KiB
Markdown
106 lines
3.6 KiB
Markdown
---
|
|
name: background-agents-reference
|
|
description: CC background agents — long-running subagents with run_in_background and Monitor for progress streaming.
|
|
layer: reference
|
|
cc_feature: background-agents
|
|
source: https://docs.claude.com/en/docs/claude-code/background-agents
|
|
concept: async-agents-and-monitoring
|
|
last_verified: 2026-04-18
|
|
ngram_overlap_score: null
|
|
review_status: approved
|
|
---
|
|
|
|
# Background Agents — Reference
|
|
|
|
A background agent is a subagent launched with `run_in_background:
|
|
true`. The parent does not block on its return; instead, the harness
|
|
notifies the parent when the agent completes. Useful for long-running
|
|
exploration, orchestration, and work that overlaps with user activity.
|
|
|
|
## Launching
|
|
|
|
```
|
|
Agent({
|
|
description: "...",
|
|
subagent_type: "...",
|
|
prompt: "...",
|
|
run_in_background: true
|
|
})
|
|
```
|
|
|
|
The Agent tool returns a handle (agent ID / name). The parent
|
|
continues its turn; no wait.
|
|
|
|
## Monitoring
|
|
|
|
Two complementary tools work with background agents:
|
|
|
|
- **Monitor** — streams updates from a named background process. Each
|
|
event line arrives as a notification. Used for long-running Bash
|
|
processes (and, in newer builds, some agent streaming paths).
|
|
- **Completion notifications** — the harness posts a message to the
|
|
parent when the background agent finishes. The parent sees it as a
|
|
system-reminder / notification on its next turn.
|
|
|
|
## When background is worth it
|
|
|
|
- **Overlapping work** — orchestrator runs 30+ minutes of research
|
|
while the user continues coding. Without background, the user is
|
|
blocked the whole time.
|
|
- **Parallel waves** — wave N of sessions running concurrently; the
|
|
parent collects results as they arrive.
|
|
- **Long-running processes** — an agent waiting on a build, test run,
|
|
or deployment.
|
|
|
|
## When background hurts
|
|
|
|
- **Short tasks** — agent returns in 10 seconds; making it async adds
|
|
overhead for no gain.
|
|
- **Tight coupling** — if the parent needs the result before doing
|
|
anything else, background is just foreground with extra steps.
|
|
- **Unbounded token spend** — a background agent with no budget
|
|
signaling can run until it hits limits. Cap explicitly.
|
|
|
|
## Common shapes
|
|
|
|
### Shape A: Orchestrator handoff
|
|
|
|
Parent interviews user, writes a spec, launches a background
|
|
orchestrator with the spec path. Parent exits its turn; orchestrator
|
|
takes over for the heavy phases.
|
|
|
|
Used by: `ultraplan-local`, `ultraresearch-local`.
|
|
|
|
### Shape B: Parallel waves
|
|
|
|
Parent decomposes work into N independent sessions, launches them all
|
|
in parallel with `run_in_background: true`, then synthesizes returns
|
|
as they arrive.
|
|
|
|
Used by: `ultraplan-local --decompose` execution.
|
|
|
|
### Shape C: Watcher
|
|
|
|
A background agent polls a process (build, test, deploy) and reports
|
|
status changes. Uses Monitor for streaming.
|
|
|
|
## Pitfalls
|
|
|
|
- **Lost context** — if the parent conversation ends before the
|
|
background agent completes, the result may be orphaned. Persist to
|
|
disk, not memory.
|
|
- **Notification fatigue** — too many background agents = too many
|
|
reminders interrupting the parent's flow.
|
|
- **Debugging** — background agents run out of the user's view; their
|
|
failures can be silent. Log to files, not just return messages.
|
|
|
|
## Composition
|
|
|
|
- Background + worktrees: the canonical pattern for parallel
|
|
implementation — each background agent in its own worktree, no
|
|
clashes.
|
|
- Background + subagents: an orchestrator IS a subagent; it in turn
|
|
can launch its own subagents (foreground inside the orchestrator's
|
|
context, or further background).
|
|
- Background + hooks: hooks fire inside the background agent's tool
|
|
calls, same as foreground.
|