Parallel Claude Code Agents: Run Multiple Tasks Simultaneously
Launch parallel Claude agents by creating one git worktree per task, running 'claude --headless --print' in each directory as a background process, and waiting for all to complete with shell job control. Each agent works independently with no shared file conflicts.
The single biggest productivity unlock in Claude Code is running agents in parallel. When you have 5 independent tasks — write tests, fix types, update docs, refactor module A, refactor module B — you can run all 5 simultaneously in separate worktrees and have everything done in the time of the longest single task.
The architecture is simple: one git worktree per agent, one background Claude process per worktree. Since worktrees share the git object store but have separate working directories, agents can all read the codebase but their file writes never collide. When all agents finish, you review each branch and merge the ones that look good.
Coordination between parallel agents happens through git, not through Claude itself. Agent A writes its results to branch 'claude/add-tests', agent B to 'claude/fix-types'. You review both, merge both, done. There is no shared memory or message passing between agents — keep tasks cleanly independent.
For tasks that do need coordination (agent B depends on agent A's output), use a sequential-then-parallel structure: run agent A, merge its branch to main, create worktrees for B and C which both start from the updated main. This gives you the benefit of parallelism where it is safe and sequential ordering where it is necessary.
Examples
#!/bin/bash
# parallel-agents.sh
# Usage: ./parallel-agents.sh
REPO=$(git rev-parse --show-toplevel)
BASE=$(basename $REPO)
STAMP=$(date +%Y%m%d-%H%M%S)
LOGDIR="$HOME/.claude/parallel-$STAMP"
mkdir -p "$LOGDIR"
declare -A TASKS=(
["write-tests"]="Write comprehensive unit tests for all exported functions in src/lib/. Use vitest. Achieve at least 80% coverage."
["fix-lint"]="Fix all ESLint errors reported by 'npm run lint'. Do not disable rules — fix the actual issues."
["add-jsdoc"]="Add JSDoc comments to all exported functions in src/lib/ that are missing them. Include @param, @returns, and @example tags."
)
PIDS=()
WORKTREES=()
for NAME in "${!TASKS[@]}"; do
BRANCH="claude/${NAME}-${STAMP}"
WT="${REPO}/../${BASE}-${NAME}"
WORKTREES+=("$WT")
git worktree add "$WT" -b "$BRANCH" 2>/dev/null
cp -r node_modules "$WT/" 2>/dev/null || true # copy deps if small enough
(
cd "$WT"
claude --headless --print --max-turns 30 "${TASKS[$NAME]}" \
> "$LOGDIR/${NAME}.log" 2>&1
echo "[$(date +%H:%M:%S)] DONE: $NAME → $BRANCH"
) &
PIDS+=("$!:$NAME")
done
echo "Running ${#TASKS[@]} parallel agents..."
for ENTRY in "${PIDS[@]}"; do
PID=${ENTRY%%:*}
NAME=${ENTRY##*:}
wait $PID && echo "✓ $NAME" || echo "✗ $NAME (check $LOGDIR/${NAME}.log)"
done
echo ""
echo "Review branches:"
git branch | grep "claude/"
echo "Logs: $LOGDIR/"# Review each agent's work
for BRANCH in $(git branch | grep 'claude/'); do
echo "=== $BRANCH ==="
git log main..$BRANCH --oneline
git diff main...$BRANCH --stat
echo ""
done
# Merge the ones you want
git merge claude/write-tests
git merge claude/add-jsdoc
# Skip claude/fix-lint if it made changes you don't like
# Clean up
git worktree prune
git branch -d claude/write-tests claude/add-jsdoc claude/fix-lintTips
- →Only parallelize truly independent tasks — tasks that touch the same files will cause merge conflicts.
- →Pass '--max-turns 30' to each agent to prevent one slow task from running forever while others wait.
- →Copy node_modules into each worktree rather than reinstalling — faster for tasks that need to run npm scripts.
- →Log each agent's output to a separate file for easy debugging when something goes wrong.
- →Start with 2-3 parallel agents before scaling to 5+ — verify the workflow is solid first.
FAQ
How many parallel agents can I run at once?+
Practically, 3-8 agents is the sweet spot. More than that and you are bound by API rate limits (Anthropic's concurrent request limits) and disk I/O from multiple Claude processes reading the same large codebase. For very large teams, queue tasks rather than running all at once.
Can parallel agents communicate with each other?+
Not directly. They operate in separate processes with separate working directories. Use files in a shared temp directory (/tmp/claude-shared/) as a message bus if you absolutely need coordination, but design tasks to be independent whenever possible.
What happens if two agents try to modify the same file?+
Because each agent is on its own branch in its own worktree, they write their versions independently. When you try to merge both branches, git will flag the conflict as a normal merge conflict. You resolve it like any other conflict — there is no data loss.