Skip to content
BSWEN
Blog

How to Run Multiple Claude Code Sessions in Parallel: A Complete Guide

Cowrie
Cowrie
Dev @ Bswen

The Problem

I wanted to run multiple AI agents simultaneously. One agent could research documentation while another wrote code. One could plan the architecture while another implemented features.

But when I tried the Claude Code desktop app, I hit a wall:

Desktop App Limitation:
- Only ONE session visible at a time
- No way to view multiple agents simultaneously
- No agent-to-agent communication
- No persistent sessions across restarts

I found a Reddit thread where developers were asking the same question:

“How do I run multiple Claude Code sessions in parallel? I want one agent working on planning, another on implementation, and a third on code review—all at the same time.”

The thread had 166 upvotes and 116 comments. The consensus was clear: use tmux.

The Solution

tmux is a terminal multiplexer. It lets you split your terminal into multiple panes, each running its own Claude Code session. You can see all sessions at once and switch between them instantly.

Here’s what my workflow looks like now:

tmux layout for Claude Code
┌─────────────────────┬─────────────────────┐
│                     │                     │
│   Planner Agent     │   Coder Agent       │
│   (planning branch) │   (feature branch)  │
│                     │                     │
├─────────────────────┴─────────────────────┤
│                                           │
│           Reviewer Agent                  │
│           (main branch)                   │
│                                           │
└───────────────────────────────────────────┘

Each pane is a fully independent Claude Code session. I can see what each agent is doing in real-time.

Basic tmux Setup for Claude Code

I started with the fundamentals:

Basic tmux commands
# Create a new tmux session named 'claude-dev'
tmux new -s claude-dev


# Split window horizontally (top/bottom)
Ctrl-b "


# Split current pane vertically (left/right)
Ctrl-b %


# Navigate between panes
Ctrl-b <arrow key>


# Start Claude Code in each pane
claude


# Detach from session (keeps running in background)
Ctrl-b d


# List all sessions
tmux ls


# Reattach to session
tmux attach -t claude-dev


# Kill a session
tmux kill-session -t claude-dev

The key insight: each pane is independent. Claude Code in one pane doesn’t know about Claude Code in another pane. This isolation is exactly what I needed for parallel work.

Why Terminal Beats Desktop for Parallel Sessions

The Reddit discussion revealed several critical differences:

Terminal vs Desktop comparison
Desktop App:
├── Single session view only
├── No split-screen capability
├── No agent communication
├── No scripting support
└── No persistence (if app closes, session lost)


Terminal + tmux:
├── Multiple simultaneous sessions
├── Split-screen layouts
├── Scriptable automation
├── Session persistence (survives disconnects)
└── Agent-to-agent file-based communication

One comment that stuck with me:

“Terminal sessions are persistent and can communicate with each other. This enables multi-agent architectures that the desktop app simply cannot replicate.”

Scripted Multi-Session Setup

Manually creating panes got tedious. I wrote a script to automate the setup:

setup-claude-sessions.sh
#!/bin/bash
SESSION_NAME="claude-project"


# Create session with first window
tmux new-session -d -s $SESSION_NAME -n "planner"


# Create additional windows
tmux new-window -t $SESSION_NAME -n "coder"
tmux new-window -t $SESSION_NAME -n "reviewer"


# Send commands to each window
tmux send-keys -t $SESSION_NAME:planner "claude" C-m
tmux send-keys -t $SESSION_NAME:coder "claude" C-m
tmux send-keys -t $SESSION_NAME:reviewer "claude" C-m


# Attach to session
tmux attach -t $SESSION_NAME

When I run this:

Running the setup script
$ ./setup-claude-sessions.sh


# Result: Three Claude Code sessions ready in separate windows
# planner  - for architecture and planning
# coder    - for implementation
# reviewer - for code review

The Worktree Problem

I made a critical mistake at first. I ran multiple Claude Code sessions on the same branch:

WRONG: Multiple sessions on same branch
# Pane 1: claude on main branch
# Pane 2: claude on main branch
# Pane 3: claude on main branch


# Result: Git conflicts everywhere

Each agent tried to edit the same files. Chaos ensued.

The solution: git worktrees.

Correct approach: Parallel worktrees
# Create worktrees for parallel development
git worktree add ../project-feature-auth -b feature/auth
git worktree add ../project-bugfix-api -b bugfix/api-crash


# In tmux, navigate to each worktree and start Claude
# Pane 1: cd ../project-feature-auth && claude
# Pane 2: cd ../project-bugfix-api && claude

Now each session works on its own isolated branch:

Worktree isolation
┌─────────────────────┬─────────────────────┐
│                     │                     │
│   Feature Auth      │   Bugfix API        │
│   ../project-auth/  │   ../project-api/   │
│   feature/auth      │   bugfix/api-crash  │
│                     │                     │
└─────────────────────┴─────────────────────┘
         ↓                       ↓
    No conflicts            No conflicts

Agent-to-Agent Communication

Desktop app has zero agent-to-agent communication. But terminal sessions can share context through files.

Here’s my pattern:

Agent communication via files
# Agent 1 (Planner) writes architecture decisions
echo "Use PostgreSQL for user data, Redis for sessions" > .claude/context/decisions.md


# Agent 2 (Coder) reads those decisions
# Claude reads .claude/context/decisions.md and follows the architecture


# Agent 3 (Reviewer) validates against decisions
# Claude checks if implementation matches the planned architecture

This simple file-based approach enables sophisticated multi-agent workflows:

Multi-agent workflow
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Planner    │────▶│    Coder     │────▶│   Reviewer   │
│              │     │              │     │              │
│ Writes:      │     │ Reads:       │     │ Validates:   │
│ - plan.md    │     │ - plan.md    │     │ - plan.md    │
│ - decisions/ │     │ - decisions/ │     │ - decisions/ │
│              │     │              │     │ - code/      │
└──────────────┘     └──────────────┘     └──────────────┘

tmux Configuration Optimized for Claude Code

I added this to my ~/.tmux.conf for a better experience:

~/.tmux.conf
# Enable mouse support (click to switch panes, scroll)
set -g mouse on


# Increase history limit (Claude output can be long)
set -g history-limit 50000


# Start window numbering at 1 (easier keyboard reach)
set -g base-index 1


# Enable 256 colors (Claude syntax highlighting)
set -g default-terminal "screen-256color"


# Split panes more intuitively
bind | split-window -h
bind - split-window -v


# Quick reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded!"


# Status bar with session info
set -g status-right '#[fg=white]#S:#I.#P'

After reloading:

Applying tmux config
$ tmux source-file ~/.tmux.conf
# Now: mouse works, history is long, splits are intuitive

Common Mistakes I Made

Mistake 1: Running sessions on the same branch

WRONG approach
# Both sessions on main branch
Session 1: git checkout main && claude
Session 2: git checkout main && claude
# Result: Git conflicts when both try to edit same files

Mistake 2: Not naming sessions descriptively

WRONG: Generic names
tmux new -s session1
tmux new -s session2
# Result: Can't remember which session does what

Correct approach:

RIGHT: Descriptive names
tmux new -s feature-auth-agent
tmux new -s bugfix-api-session
tmux new -s review-code-session
# Result: Clear purpose for each session

Mistake 3: Not persisting important outputs

Risky: Relying only on terminal history
# Claude outputs important decisions
# Terminal crashes or buffer overflows
# Decisions lost

Correct approach:

Safe: Persist to files
# Ask Claude to write decisions to files
claude> "Write the architecture decisions to .claude/decisions.md"
# Now decisions survive any crash

Mistake 4: Too many sessions without monitoring API usage

Problem: Unmonitored parallel sessions
# 5 Claude Code sessions running
# Each making API calls
# Suddenly: quota exceeded

Correct approach:

Solution: Monitor usage across sessions
# Check usage dashboard
# Or limit sessions to 2-3 at a time
# Stagger heavy operations

Alternative: WaveTerminal

The Reddit thread mentioned WaveTerminal as a user-friendly alternative to tmux:

  • Visual session management
  • Easier learning curve
  • Built-in session tracking
  • Graphical interface for power users

I haven’t tried it personally, but it’s worth considering if tmux feels too terminal-heavy.

Why This Matters for Productivity

Before parallel sessions:

Sequential workflow (old)
1. Plan feature architecture (30 min)
2. Wait for planning to finish
3. Implement feature (2 hours)
4. Wait for implementation to finish
5. Review code (30 min)
Total: 3+ hours with idle time between phases

After parallel sessions:

Parallel workflow (new)
1. Start planner agent → writes architecture
2. Start coder agent → begins implementation (uses partial plan)
3. Start reviewer agent → monitors code as it's written
Total: 2 hours, all phases overlap

The productivity gain isn’t just time saved. It’s about flow. When one agent finishes research, another is already coding. When code is written, review happens immediately.

Summary

In this post, I showed how to run multiple Claude Code sessions in parallel using tmux. The key points are:

  1. Terminal multiplexers like tmux enable parallel AI agents - Something the desktop app fundamentally cannot do
  2. Use git worktrees to avoid conflicts - Each session needs its own branch
  3. File-based communication between agents - Simple but effective for sharing context
  4. Script your setup - Don’t manually create panes every time
  5. Persist important outputs - Terminal history can be lost

The combination of Claude Code + tmux + worktrees creates a development environment where specialized agents can collaborate, parallel tasks proceed independently, and no context is lost to session limits.

Next steps:

  1. Learn basic tmux commands (30-minute investment)
  2. Create your own setup script
  3. Start with 2-3 sessions before scaling complexity
  4. Add session naming conventions to your workflow

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: