Parallel Pipeline

The parallel tool lets the agent run multiple tasks at the same time. Independent tasks execute concurrently, and dependent tasks wait for their prerequisites to finish before starting. The agent decides the structure automatically based on your request.

How it works

When you ask for something that involves multiple independent subtasks, the agent can split the work into a pipeline:

"Refactor the auth module, write tests for the new code, and update the API docs"

The agent recognizes:

• Refactoring and docs are independent (can run in parallel)
• Tests depend on the refactored code (must wait)

It calls the parallel tool with a task graph:

⚡ Pipeline
[✓ refactor auth] ──▶ [● write tests]
[✓ update docs]

Task dependencies

Each task can declare which other tasks it depends on using depends_on. Tasks with no dependencies start immediately. Tasks with dependencies wait until all prerequisites complete.

When a dependent task starts, it receives the output of all its prerequisites as context:

[Context from completed task "refactor auth" (14s)]
Refactored auth module. Key changes:
- Replaced session tokens with JWT
- New middleware at internal/auth/jwt.go

[Your task]
Write comprehensive tests for the auth module...

Pipeline topologies

The agent can build any directed acyclic graph:

Linear chain (A then B then C):

⚡ Pipeline
[✓ read code] ──▶ [✓ write fix] ──▶ [● run tests]

Fan out (A first, then B and C in parallel):

⚡ Pipeline (3 tasks)
  ✓ analyze codebase (8s)
  ● refactor auth
  ● update API docs ← analyze codebase

Diamond (A and B in parallel, C waits for both):

⚡ Pipeline (3 tasks)
  ✓ refactor auth (12s)
  ✓ update schema (9s)
  ● write integration tests ← refactor auth, update schema

Limits

Fail fast

If any task fails, the entire pipeline stops. Running tasks are cancelled, and tasks that have not started are marked as skipped:

⚡ Pipeline (3 tasks)
  ✓ read code (3s)
  ✗ run tests (15s)
  ⊘ deploy (skipped)

The agent sees which tasks succeeded and which failed, and can report the results or retry.

When to use it

The agent decides when to use parallel on its own. You do not need to ask for it explicitly. The agent will use it when it recognizes that your request involves multiple subtasks that can benefit from concurrent execution.

Good use cases:

• "Refactor module A and write tests for module B" (independent work)
• "Read all the config files, then update each one" (fan out after analysis)
• "Fix the bug, write a test for it, and update the changelog" (test depends on fix, changelog is independent)

The agent will NOT use parallel when tasks are tightly coupled and need to share state within a single conversation.

Sub agent restrictions

Each task in the pipeline runs as a sub agent with the same model and tools as the parent, except:

• parallel is not available (no nested pipelines)
• task is not available (no nested sub agents)
• consult is not available
• tool_create / tool_register / tool_list_custom are not available
• ask_user is disabled (sub agents cannot pause for input)

Status icons