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:

code

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:

code

# 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

code

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

Returns current output without waiting for completion.

Retrieving Results

Wait for Completion

code

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:

code

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

code

# 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)

# Continue polishing code while they run...

# Check progress
/tasks

# Retrieve results when ready
TaskOutput(task_id="...", block=true)

Research Phase

code

# Launch all research agents
Task(subagent_type="somto-dev-toolkit:prd-codebase-researcher", run_in_background: true)
Task(subagent_type="compound-engineering:research:git-history-analyzer", run_in_background: true)
Task(subagent_type="somto-dev-toolkit:prd-external-researcher", run_in_background: true)

# Continue interview prep while research runs...

# Retrieve all results
TaskOutput(task_id="task-1", block=true)
TaskOutput(task_id="task-2", block=true)
TaskOutput(task_id="task-3", block=true)

When NOT to Background

•Complexity estimator (Phase 5.5) - Need result immediately for next phase
•Any agent whose output gates the next step - Must wait for result
•Quick agents (<10 seconds) - Overhead not worth it

Kieran Reviewers by Language

Language	Agent
TypeScript/JavaScript	`compound-engineering:review:kieran-typescript-reviewer`
Python	`compound-engineering:review:kieran-python-reviewer`
Ruby/Rails	`compound-engineering:review:kieran-rails-reviewer`

Domain-Specific Reviewers

Domain	Agent
Database/migrations	`compound-engineering:review:data-integrity-guardian`
Frontend races	`compound-engineering:review:julik-frontend-races-reviewer`