background-agents

# Background Agents - Non-Blocking Parallel Execution

Background agents let you continue working while long-running tasks execute.
Use `run_in_background: true` to launch agents that run without blocking.

## When to Use Background Agents

- Research phases with multiple independent agents
- Pre-commit reviews (code-simplifier + kieran reviewer)
- Any Task that takes >30 seconds and doesn't gate your immediate next step

## Launching Background Agents

Add `run_in_background: true` to Task calls:

```
Task(
  subagent_type="compound-engineering:review:kieran-typescript-reviewer",
  prompt="Review the changes in this PR",
  max_turns: 20,
  run_in_background: true
)
```

### Parallel Launch Pattern

Launch multiple agents in ONE message for true parallelism:

```
# Single message with multiple Task calls
Task 1: subagent_type="pr-review-toolkit:code-simplifier" (max_turns: 15, run_in_background: true)
Task 2: subagent_type="compound-engineering:review:kieran-typescript-reviewer" (max_turns: 20, run_in_background: true)
```

## Monitoring Progress

### Check All Tasks

- `/tasks` - List all background tasks with status
- `Ctrl+T` - Toggle task list view in terminal

### Check Specific Task

```
TaskOutput(task_id="task-abc123", block=false)
```

Returns current output without waiting for completion.

## Retrieving Results

### Wait for Completion

```
TaskOutput(task_id="task-abc123", block=true)
```

Blocks until agent completes, returns full output.

### Read Output File

Background agents write to output files. The path is returned when you launch:

```
Task returned: { task_id: "abc123", output_file: "/path/to/output.txt" }
```

Use `Read` tool on output_file path to check progress or results.

## Common Patterns

### Pre-Commit Reviews

```
# Launch both reviewers in parallel
Task(subagent_type="pr-review-toolkit:code-simplifier", run_in_background: true)
Task(subagent_type="compound-engineering:review:kieran-typescript-reviewer", run_in_background: true)

# Con