Skip to content

SomtoUgeh/somto-dev-toolkit / skills/background-agents

background-agents

Verified

This skill should be used when the user asks about "parallel agents", "background tasks", "run_in_background", "non-blocking agents", "check agent progress", "TaskOutput", "retrieve agent results", or discusses running multiple agents concurrently. Covers patterns for launching agents in background, monitoring progress, and retrieving results.

FileKindSize
SKILL.mdskill md3.8 KB
---
name: background-agents
description: |
  This skill should be used when the user asks about "parallel agents", "background
  tasks", "run_in_background", "non-blocking agents", "check agent progress",
  "TaskOutput", "retrieve agent results", or discusses running multiple agents
  concurrently. Covers patterns for launching agents in background, monitoring
  progress, and retrieving results.
version: 1.0.0
---

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

# Continue polishing code while they run...

# Check progress
/tasks

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

### Research Phase

```
# 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` |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall