workflow · 8 min read · 2026-07-10

How to run multiple Claude Code sessions in parallel

One agent writing code while you watch is nice. Three agents working while you review is a different job entirely. Parallel sessions are how heavy Claude Code users actually work, and the tooling is simpler than it looks: terminals, tmux, and (when sessions share a repo) git worktrees. Here's the setup, plus the failure modes nobody mentions until they hit them.

Why run more than one session?

• Parallel tasks: one session refactors the backend while another writes tests and a third chases a flaky CI job.
• Model separation: a dedicated Opus session for hard problems and a Haiku session for chores, each keeping its own context and its own warm prompt cache. (Switching models inside one session rebuilds the cache every time; separate sessions never pay that.)
• Isolation: a long autonomous run in one session doesn't block you from interactive work in another.
• Second opinions: a Codex session next to a Claude session, reviewing each other's plans.

Level 1: terminal tabs

The zero-setup version: open more terminal tabs, run claude in each. Each session is fully independent, with its own history, context window, and cache. Launch each with an explicit model so the sessions have roles:

# tab 1: the architect
claude --model opus

# tab 2: the grunt
claude --model haiku

# tab 3: the other opinion
codex

This works until you have more than two or three tabs, at which point you lose track of which tab holds which model and which task. That bookkeeping problem is the real ceiling.

Level 2: tmux

tmux keeps every session alive in one place, survives closing your terminal app, and lets you script the whole layout:

# one named session, one window per agent
tmux new-session -d -s agents -n opus
tmux send-keys -t agents:opus 'claude --model opus' C-m

tmux new-window -t agents -n haiku
tmux send-keys -t agents:haiku 'claude --model haiku' C-m

tmux new-window -t agents -n codex
tmux send-keys -t agents:codex 'codex' C-m

tmux attach -t agents

Windows persist even if you detach, so a long autonomous run keeps going while your laptop lid stays open. Jump between agents with Ctrl-b n / Ctrl-b p or by window name. This is the pattern most parallel-agent guides converge on, from worktree-plus-tmux setups to production parallel-session workflows.

Level 3: git worktrees (when sessions share a repo)

Two agents editing the same checkout will step on each other: conflicting edits, dirty git status, one agent committing the other's half-finished work. Git worktrees give each session its own working directory on its own branch, backed by the same repo:

git worktree add ../myapp-auth feature/auth
git worktree add ../myapp-dashboard feature/dashboard

# each session gets its own copy
(cd ../myapp-auth && claude --model sonnet)
(cd ../myapp-dashboard && claude --model sonnet)

Claude Code is directory-aware: run it inside a worktree and it sees that branch's files, not main. Merge each branch back when its agent finishes. Worktrees are the standard answer for parallel sessions in one repo.

Level 4: headless runs

For fire-and-forget tasks, skip the interactive UI entirely:

claude -p "Update all deprecated API calls in src/, run the tests, fix failures" &
claude -p "Write missing JSDoc for the exported functions in lib/" &

Combine with worktrees and you have a small fleet. Check in on results, keep what's good.

The pitfalls

• Shared services aren't isolated. Worktrees isolate files, not databases, ports, or env vars. Two agents running migrations against the same local Postgres will ruin your afternoon. Give parallel sessions separate DB schemas or containers.
• Rate limits are shared. All your sessions draw from the same account quota. Three heavy sessions burn your 5-hour window three times faster. Put chores on Haiku sessions; they consume far less quota per task.
• Cognitive load is real. Most people plateau at two or three concurrently supervised sessions. Beyond that, review quality drops and agents drift. Scale the number of sessions to your attention, not your ambition.
• Session sprawl. Unlabeled tabs multiply. If you can't answer "which session is Opus and what is it doing" in one glance, you've outgrown manual management.

The managed version: gears instead of tabs

Model Shift automates levels 1 through 3 for the model-separation use case. It maintains one tmux session (the garage) with one window per gear, each gear mapped to a model: Haiku, Sonnet, Opus, Fable, GPT, your layout. The stick shift is the switcher: throw the lever and you're in that model's live session, context intact, cache warm, no window-name archaeology. It runs Claude Code and Codex side by side, so the "second opinion" workflow is built in.

Further reading: A cache-safe multi-model workflow · The /model command, completely explained