Level 8: Orchestrator — Directing Parallel Agents

When you want to implement multiple independent features simultaneously, running them in parallel is dramatically faster than implementing them one by one. With the orchestrator pattern, Claude (or a custom script) acts as a conductor, running multiple specialist agents in parallel and integrating the results.

Target audience: Anyone who is comfortable with headless automation and wants even more speed and scale.

Estimated learning time: Read 30min + Practice 50min

---

What Is the Orchestrator Pattern?

The orchestrator pattern is a structure where a “conductor (orchestrator)” manages multiple “specialists.”

Orchestrator (conductor)
    ├── Specialist A: Implement feature 1
    ├── Specialist B: Implement feature 2
    └── Specialist C: Implement feature 3

Each specialist handles an independent task and works in parallel without depending on the others. The orchestrator waits for all of them to complete, then integrates the results.

Running Tasks in Parallel with a Shell Script

Use & for background execution and wait to wait for all of them to complete.

#!/bin/bash
# A simple example of running multiple tasks in parallel

# Run task A in the background
(
  claude --print --dangerously-skip-permissions "Please execute task A" \
    > /tmp/result_a.txt 2>&1
  echo "Task A complete"
) &
PID_A=$!

# Run task B in the background
(
  claude --print --dangerously-skip-permissions "Please execute task B" \
    > /tmp/result_b.txt 2>&1
  echo "Task B complete"
) &
PID_B=$!

# Run task C in the background
(
  claude --print --dangerously-skip-permissions "Please execute task C" \
    > /tmp/result_c.txt 2>&1
  echo "Task C complete"
) &
PID_C=$!

# Wait for all processes to complete
wait $PID_A $PID_B $PID_C

echo "=== All tasks complete ==="
cat /tmp/result_a.txt
cat /tmp/result_b.txt
cat /tmp/result_c.txt

$! is a variable that holds the PID of the most recently launched background process. Passing multiple PIDs to wait causes it to block until all specified processes have finished.

The Concept of Git Worktree and How to Use It

Git worktree lets you check out multiple branches from a single repository into separate directories simultaneously.

# Check out branches into separate directories
git worktree add ../project-feature-a feature/feature-a
git worktree add ../project-feature-b feature/feature-b
git worktree add ../project-feature-c feature/feature-c

# Each directory can be worked on independently
ls ../project-feature-a  # Contents of the feature/feature-a branch
ls ../project-feature-b  # Contents of the feature/feature-b branch

# Remove worktrees when done
git worktree remove ../project-feature-a
git worktree remove ../project-feature-b
git worktree remove ../project-feature-c

With a normal branch switch (git checkout), files are overwritten because the same directory is shared. With worktree, you can check out multiple branches simultaneously and work on them in parallel.

Using Claude Itself as the Orchestrator

By directly instructing Claude to “execute the following while switching between multiple roles in parallel,” Claude itself operates as the orchestrator.

> Please execute the following 3 tasks in parallel.
>
> Task 1 (as an API design expert):
> Design and implement CRUD for a /users endpoint in Python + FastAPI.
>
> Task 2 (as a test engineer):
> Create pytest test code for the above API.
>
> Task 3 (as documentation lead):
> Write the OpenAPI specification in Markdown.
>
> Once each task is complete, compile an integration report.

Claude generates independent output for each role and integrates them at the end.

Example: Parallel Analysis of a Large Codebase

A script that simultaneously analyzes a large codebase from multiple perspectives.

#!/bin/bash
# scripts/parallel_analysis.sh
# Analyze a codebase in parallel from multiple perspectives

REPO_PATH=${1:-"."}

echo "=== Starting parallel code analysis ==="

# Security analysis
(
  find "$REPO_PATH/src" -name "*.py" | head -20 | xargs cat | \
  claude --print "Please list the security issues in this code." \
    > /tmp/analysis_security.txt 2>&1
) &

# Performance analysis
(
  find "$REPO_PATH/src" -name "*.py" | head -20 | xargs cat | \
  claude --print "Please list the performance issues in this code." \
    > /tmp/analysis_performance.txt 2>&1
) &

# Test coverage analysis
(
  find "$REPO_PATH" -name "*.py" | xargs grep -l "def test_" | head -10 | xargs cat | \
  claude --print "Evaluate test coverage and suggest missing test cases." \
    > /tmp/analysis_tests.txt 2>&1
) &

# Wait for all processes to complete
wait

echo ""
echo "=== Security Analysis Results ==="
cat /tmp/analysis_security.txt

echo ""
echo "=== Performance Analysis Results ==="
cat /tmp/analysis_performance.txt

echo ""
echo "=== Test Coverage Analysis Results ==="
cat /tmp/analysis_tests.txt

---

FAQ

Q. How do I choose which tasks to run in parallel?

If there are dependencies between tasks (A must complete before B), they cannot be parallelized. Tasks that are independent of each other, or that operate on different directories or files, are suitable for parallelization.

Q. Does working in a worktree affect the original repository?

A worktree shares the .git of the same repository, but is a separate directory on the filesystem. Removing it with git worktree remove has no effect on the original repository.

---

Hands-On Tutorial

Hands-on tutorial for this level →

Next Level

I’ve understood how to direct parallel agents and use Git worktree for parallel development. Next, I’ll learn about 24/7 always-on background jobs combining GitHub Actions and cron.

Let’s move on to Level 9: Infrastructure Operator — 24/7 Background Jobs.