Managing Multiple Claude Code Sessions

One Claude Code session is powerful. Multiple sessions running in parallel across different projects, features, and tasks is a force multiplier that most developers have not explored. But running multiple sessions without a system leads to confusion -- you lose track of which session is working on what, prompts go to the wrong terminal, and context bleeds between tasks.

This guide covers the terminal setup, naming conventions, and workflow patterns that make multi-session Claude Code development practical and organized.

Key Takeaways

• Each Claude Code session should map to exactly one task -- mixing tasks in a single session degrades context quality
• tmux or iTerm2 named sessions let you label and switch between Claude Code instances without confusing which session handles which task
• Git worktrees pair naturally with multiple sessions -- each worktree gets its own Claude Code session in its own directory
• The --resume flag is critical for multi-session workflows because you will constantly be switching away and returning to sessions
• Four simultaneous sessions is the practical maximum before cognitive overhead of managing them exceeds the productivity benefit

Why Multiple Sessions?

A single Claude Code session holds context for one task. When you switch tasks within the same session -- say, from building a feature to fixing an unrelated bug -- the context from the first task dilutes. Claude's suggestions for the bug fix may reference the feature context, leading to confused output.

Multiple sessions solve this by giving each task its own isolated context. Session A works on the new search feature. Session B debugs the authentication issue. Session C writes documentation. Each session holds only the context relevant to its task.

The second benefit is parallelism. While Claude is generating a long response in Session A, you can prompt Session B. While Session B runs tests, you review output in Session C. You are not waiting on any single session -- there is always productive work available.

Terminal Setup: tmux

tmux is the standard tool for managing multiple terminal sessions. Here is a configuration optimized for multi-session Claude Code work.

# ~/.tmux.conf additions for Claude Code multi-session

# Easy session switching
bind -n M-1 select-window -t 1
bind -n M-2 select-window -t 2
bind -n M-3 select-window -t 3
bind -n M-4 select-window -t 4

# Status bar shows session names clearly
set -g status-left-length 40
set -g status-left '#[fg=green]#S #[fg=white]| '
set -g status-right '#[fg=yellow]%H:%M'

# Window names persist (don't auto-rename)
set -g allow-rename off

Creating Named Sessions

# Create a session for each task
tmux new-session -d -s feature-search
tmux new-session -d -s bugfix-auth
tmux new-session -d -s docs-api

# In each session, navigate to the relevant directory and start Claude
tmux send-keys -t feature-search "cd ~/projects/worktrees/feature-search && claude" Enter
tmux send-keys -t bugfix-auth "cd ~/projects/main && claude" Enter
tmux send-keys -t docs-api "cd ~/projects/main && claude" Enter

# Attach to the session you want to work on
tmux attach -t feature-search

Switching Between Sessions

# Switch sessions with prefix + s (shows session list)
# Or use the Alt+number bindings from the config above

# List all sessions
tmux list-sessions
# Output:
# bugfix-auth: 1 windows (created ...)
# docs-api: 1 windows (created ...)
# feature-search: 1 windows (created ...)

Terminal Setup: iTerm2

If you prefer iTerm2 on macOS, use profiles and tab naming for organization.

Creating Profiles

Create a Claude Code profile for each common task type:

1. Open iTerm2 Preferences > Profiles
2. Create profiles: "Claude-Feature", "Claude-Bugfix", "Claude-Docs"
3. Set different tab colors for each profile (helps with visual identification)
4. Optionally set a different badge text for each

Tab Naming Script

# Name the current iTerm2 tab
function ct() {
  echo -ne "\033]0;$1\007"
}

# Usage: open a new tab, name it, start Claude
ct "Feature: Search" && cd ~/projects/worktrees/feature-search && claude
ct "Bugfix: Auth" && cd ~/projects/main && claude
ct "Docs: API" && cd ~/projects/main && claude

Pairing Sessions With Worktrees

The most effective multi-session pattern pairs each Claude Code session with a git worktree. Each worktree is a separate checkout of your repository with its own working directory, so there is zero risk of file conflicts between sessions.

# Create worktrees for parallel tasks
git worktree add ../worktrees/feature-search -b feature/search
git worktree add ../worktrees/bugfix-auth -b bugfix/auth-timeout

# Start Claude Code in each worktree
# Session 1
cd ../worktrees/feature-search && claude

# Session 2 (different terminal/tab)
cd ../worktrees/bugfix-auth && claude

When both features are complete, merge them independently:

# From the main directory
git merge feature/search
git merge bugfix/auth

# Clean up worktrees
git worktree remove ../worktrees/feature-search
git worktree remove ../worktrees/bugfix-auth

This pattern is covered in more depth in the AI dev workflow guide.

Session Naming Conventions

Clear naming prevents confusion. Adopt a convention and stick to it.

Pattern: {type}-{brief-description}

feature-search-filters
bugfix-auth-timeout
refactor-database-queries
docs-api-reference
spike-websocket-performance

Rules:

• Always start with the task type (feature, bugfix, refactor, docs, spike)
• Keep the description to 2-3 words
• Match the session name to the git branch name when using worktrees
• Never reuse session names for different tasks

The Four-Session Maximum

In theory, you could run unlimited sessions. In practice, four is the maximum before the overhead of managing sessions exceeds the benefit.

Session 1: Primary feature work. This is your main task. You spend 60% of your attention here.

Session 2: Secondary task. A smaller task that you work on while waiting for Session 1 to generate long responses. 25% of your attention.

Session 3: Quick fixes. Bug fixes, small refactors, documentation updates that take 5-10 minutes each. 10% of your attention.

Session 4: Background/monitoring. Running tests, watching builds, monitoring deployment. 5% of your attention.

If you try to run five or six sessions, you spend more time remembering what each session is doing than you spend doing productive work. The context switching between sessions becomes the bottleneck instead of the solution.

Resuming Sessions

Claude Code's --resume flag is essential for multi-session workflows. When you switch away from a session, you do not need to restart from scratch.

# Resume the most recent conversation in this directory
claude --resume

# Resume a specific conversation by ID
claude --resume abc123

Best practice: At the end of each session interaction, leave a brief note about what you were working on and what the next step is. This helps you (and Claude) pick up where you left off.

"We just finished implementing the search filters. Next step is to add tests for the 
edge case where the filter value contains special characters."

When you resume, Claude has the full context of the previous conversation plus your note about next steps.

Handling Session Conflicts

Occasionally, two sessions will modify the same file. This happens most often when you have a shared utility file that multiple features depend on.

Prevention: Use worktrees so each session operates on its own file tree. Conflicts only surface at merge time, where git's conflict resolution handles them.

When worktrees are not practical: If two sessions must work in the same directory, establish a rule: only one session modifies shared files at a time. Use a simple convention like creating a lock file:

# Before modifying shared files
touch .claude-lock-session-1

# After finishing
rm .claude-lock-session-1

This is not enforced by tooling -- it is a discipline. But it prevents the confusion of two sessions making conflicting changes to the same file.

Monitoring Session Health

When running multiple sessions, keep a mental model of each session's state.

# Quick check: which Claude sessions are running?
ps aux | grep claude | grep -v grep

# Check which directories have active sessions
# (each session runs in its own directory)

Create a dashboard alias that shows all active sessions:

alias claude-status='echo "=== Active Claude Sessions ===" && tmux list-sessions 2>/dev/null && echo "=== Git Worktrees ===" && git worktree list'

For more on setting up a productive Claude Code environment, see the CLI commands reference.

FAQ

Does running multiple sessions cost more?

Each session consumes tokens independently. Four sessions each using 25% of your limit is the same cost as one session using 100%. The total token consumption depends on your total work, not the number of sessions.

Can I share context between sessions?

Not directly. Each session has its own conversation history. If Session A discovers something relevant to Session B, you need to manually share it by pasting information or using shared files. This isolation is intentional -- it keeps contexts clean.

What about Claude Code's session limits?

Each concurrent session counts against your rate limit separately. If you run four sessions and prompt them simultaneously, you hit rate limits 4x faster. Stagger your prompts across sessions to avoid this.

Is tmux better than iTerm2 for multi-session work?

tmux is more portable (works on any Unix system), scriptable, and persistent across SSH disconnections. iTerm2 is more visual and comfortable for macOS users. Both work. Use whichever you are more comfortable with.

Can I automate session creation for recurring workflows?

Yes. Create a shell script that sets up your standard session layout:

#!/bin/bash
# start-dev-sessions.sh
tmux new-session -d -s main -c ~/project/main
tmux new-session -d -s feature -c ~/project/worktrees/current-feature  
tmux new-session -d -s tests -c ~/project/main
tmux attach -t main

Run this script at the start of each dev day to get your standard layout immediately.

Explore production-ready AI skills at aiskill.market/browse or submit your own skill to the marketplace.

Sources

• tmux Documentation - Terminal multiplexer configuration reference
• Claude Code CLI Documentation - Session management and resume features
• Git Worktrees - Parallel development with worktrees