---
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.