How to run multiple Claude Code sessions in parallel

One Claude Code session feels great. Two repos with one session each is manageable. Then you add a hotfix branch, a Codex pass on another app, a scheduled automation, and suddenly you are alt-tabbing across six terminals wondering which window had the refactor and which one already merged.

Running multiple Claude Code sessions is not hard to start — it is hard to sustain. The failure modes are predictable:

• Two agents edit the same branch and produce conflicting diffs.
• You close a terminal and lose scrollback that held the plan.
• You forget which project had the agent waiting on a question.
• You want Codex on repo B but only have a Claude tab open on repo A.

This guide walks through three legitimate approaches — from zero extra tooling to a full orchestration app — so you can pick what matches your scale today.

The honest baseline is one terminal per session. Install Claude Code once (npm install -g @anthropic-ai/claude-code), run claude login, then start claude in each directory where you need an agent.

Multiple Terminal windows (macOS) or Windows Terminal tabs work fine for two projects. Name each tab after the repo so you can find it later.

tmux (macOS/Linux) or tmux inside WSL (Windows) scales better when you want many panes without losing sessions when you disconnect SSH:

# Start a named session
tmux new -s agents

# Split horizontally and vertically
Ctrl-b %    # vertical split
Ctrl-b "    # horizontal split

# In each pane, cd to a project and run claude
cd ~/code/project-a && claude
cd ~/code/project-b && claude

# Detach and reattach later
Ctrl-b d
tmux attach -t agents

Rules that keep this approach viable:

• One repo per session when possible.
• If two sessions touch the same repo, use different branches and merge manually.
• Write agent output you care about into files or commits — not just scrollback.
• Consider a simple spreadsheet or note listing "which terminal is doing what."

Terminals are free, fast, and transparent. They stop scaling when you want a cross-project dashboard, persistence after reboot, or four vendors at once — but for one or two repos they are genuinely enough.

When two Claude Code sessions must work on the same repository simultaneously, a single working tree is a bottleneck. Git worktrees give each session its own checkout linked to the same .git directory.

Example: main repo at ~/code/myapp, two agent branches.

cd ~/code/myapp

# Create branches if they do not exist yet
git branch agent/refactor
git branch agent/bugfix

# Add worktrees (sibling directories)
git worktree add ../myapp-refactor agent/refactor
git worktree add ../myapp-bugfix agent/bugfix

# Terminal 1
cd ../myapp-refactor && claude

# Terminal 2
cd ../myapp-bugfix && claude

When an agent finishes, commit inside that worktree and open a PR as usual:

cd ~/code/myapp-refactor
git status
git add -A && git commit -m "refactor: extract billing module"
git push -u origin agent/refactor

Clean up when done:

git worktree remove ../myapp-refactor
git worktree remove ../myapp-bugfix
git branch -d agent/refactor   # after merge

Worktrees are the right manual tool when agents would otherwise clobber each other. The cost is bookkeeping: you manage paths, branches, and cleanup yourself. For two parallel tasks on one repo, that is still often worth it.

Aiola is a local desktop app for macOS and Windows that orchestrates coding agents when terminal sprawl stops being acceptable. It is option three — not because options one and two are wrong, but because they do not give you parallel threads with saved state, a cross-project view, or four providers in one window.

What Aiola adds on top of raw terminals:

• Parallel threads — each thread is an independent agent session with chat, diffs, branch, terminal, and optional browser. Run several side by side in split view or on a canvas.
• Auto worktrees — enable run mode and Aiola creates an isolated git worktree per thread so agents do not collide. You skip the manual git worktree add ceremony.
• Queued turns — send the next instruction while the agent is still working; Aiola holds the queue instead of you watching scrollback.
• Restore after restart — thread history lives in local SQLite. Close the laptop, reopen Aiola, pick up where you left off.
• Multi-provider — Claude Code, Codex, Cursor, Grok CLI, and OpenCode from one app. Pick the agent per thread or per task instead of locking into one vendor.
• Cross-project view — see active threads, tasks, and recent changes across every workspace without naming tmux panes.

Agents still run on your machine on your own subscriptions. Your code is never uploaded to Aiola — it stays on your machine and goes only to the AI provider you already subscribe to. Aiola is the operations layer, not a cloud runner.

If you run one or two repos and tmux already feels fine, stay on options one or two. If you are juggling three or more projects, mixing vendors, or tired of reconstructing context after every reboot, download Aiola and treat it as the next step — not a replacement for knowing how terminals and worktrees work.

Stick with terminals if you have one or two repos, you are comfortable with branch discipline, and you do not need a portfolio-wide view.

Add manual worktrees when parallel agents touch the same repo and you are willing to manage paths and cleanup yourself.

Use Aiola when parallel sessions are daily life, you want persistence and queued turns, you run Codex or Cursor alongside Claude Code, or you need tasks and automations on top of raw chat.

Most power users start at option one, graduate to option two for collision safety, and adopt an orchestrator when coordination — not coding — becomes the bottleneck.