tmux + Claude Code: a layout for parallel agent sessions

Claude Code is designed to run one session at a time in one directory. In practice, you often want two or three sessions running in parallel: one fixing a bug on a feature branch, one reviewing a PR, one exploring an unfamiliar codebase. tmux is the right substrate for this. This guide shows you a layout that works, a worktree-per-pane convention that keeps sessions from interfering with each other, and the clean division of responsibility between the tmux status bar and the Claude Code statusline.

The core principle: one window per task

A Claude Code task has a lifecycle: it starts, runs for minutes to hours, and completes. A tmux window maps naturally to that lifecycle. You create a window when a task starts, work in it, and either close it or keep it as reference when the task finishes.

# create a window for a specific task
tmux new-window -t main -n "auth-refactor"
tmux new-window -t main -n "api-review"
tmux new-window -t main -n "docs-update"

Name the window after the task, not after a tool or a directory. The window list in the tmux status bar becomes your task board: you can see at a glance what is in progress, and switching contexts is prefix N away.

Git worktrees: one per Claude Code session

If each Claude Code session works in the same directory on different branches, they will conflict. Switching branches mid-session breaks the other session's working state. Git worktrees solve this: each worktree is a separate checkout of the same repo at a different path, checked out to its own branch.

# create a worktree for a feature branch
git worktree add ~/worktrees/auth-refactor feature/auth-refactor

# create a worktree for a hotfix
git worktree add ~/worktrees/hotfix-login hotfix/login-redirect

Now open each Claude Code session in its worktree directory:

# in the auth-refactor window
cd ~/worktrees/auth-refactor
claude

# in the hotfix window
cd ~/worktrees/hotfix-login
claude

Each Claude Code instance sees its own branch, its own unstaged changes, and its own git state. They do not interfere.

A two-pane layout per window

For a Claude Code window, a useful default layout is two panes: Claude Code on the left (wider), a shell on the right for running tests, inspecting files, or tailing logs.

# split the current window vertically (left/right)
# open Claude Code in the left pane (already running)
# open a shell in the right pane
bind | split-window -h -c "#{pane_current_path}"

With the split at 70/30 or 65/35, Claude Code has room to display diffs and code, and the shell pane is wide enough to read short command output. You can resize panes by holding prefix and pressing the arrow keys, or by dragging the divider with the mouse if you have mouse on.

The statusline vs the status bar: division of labor

This is the most important design decision in a tmux + Claude Code setup. The two information layers serve different purposes and should not duplicate each other.

Put Claude-specific state in the statusline. Put system/session state in the tmux bar. If you show the git branch in both, you are wasting pixels and creating potential for confusion (the two may show different branches if your shell's working directory differs from the Claude Code session's root).

For designing a statusline that shows branch, worktree, and parallel-session state, see the statuslines for git worktrees and parallel sessions guide. To build a statusline from scratch or install one from the visual builder, see Terminal Pro.

Navigating between parallel sessions

With multiple Claude Code sessions across multiple windows, fast navigation matters. These bindings help:

# switch windows
prefix 1   # window 1
prefix 2   # window 2
prefix n   # next window
prefix p   # previous window
prefix l   # last (most recently used) window

# switch sessions (if you use multiple named sessions)
prefix $   # rename session
prefix s   # list and select session (interactive)

prefix l (last window) is the fastest way to toggle between two active tasks. Learn it.

Keeping context visible at narrow widths

When you split a pane, each pane gets less horizontal space. A Claude Code statusline that looks good at 220 columns may wrap or truncate at 80. The statusline should handle narrow widths gracefully — dropping optional segments when the terminal is tight.

A practical width budget for a two-pane layout at 1920px terminal width:

• Left (Claude Code + statusline): ~130 columns
• Right (shell): ~70 columns

Design your statusline to be readable at 130 columns. Show branch and context window at a minimum; drop rate limits and cost at narrow widths.

A session layout script

If you run the same multi-window layout frequently, encode it in a script rather than recreating it manually each time:

#!/usr/bin/env bash
# setup-dev-session.sh
SESSION="dev"
REPO="$HOME/promenow"

# create or attach to session
tmux new-session -d -s "$SESSION" -c "$REPO" 2>/dev/null || true

# window 1: main shell
tmux rename-window -t "$SESSION:1" "shell"

# window 2: claude code in main repo
tmux new-window -t "$SESSION" -n "claude-main" -c "$REPO"
tmux send-keys -t "$SESSION:claude-main" "claude" Enter

# window 3: worktree slot (ready for the next task)
tmux new-window -t "$SESSION" -n "worktree" -c "$HOME/worktrees"

# focus window 1
tmux select-window -t "$SESSION:shell"

# attach
tmux attach-session -t "$SESSION"

Run this once to set up the session. After that, tmux-continuum saves and restores the layout automatically. You only need the script again if you intentionally start fresh.

Cleaning up worktrees

Worktrees accumulate. When a task is done and the branch is merged, prune the worktree:

# remove the worktree directory and git tracking
git worktree remove ~/worktrees/auth-refactor

# or force-remove if there are uncommitted changes you want to discard
git worktree remove --force ~/worktrees/auth-refactor

# list all worktrees
git worktree list

Close the corresponding tmux window at the same time. A closed window with a pruned worktree is a clean slate; an open window pointing to a deleted directory is just confusion waiting to happen.

The full picture

Put this together and you have: a server running 24/7 with a boot-created tmux session (from the persistent sessions guide), named windows for each active task, git worktrees keeping branches isolated, a Claude Code statusline showing session-specific state, and a minimal tmux status bar showing system context. Each layer does its job; nothing overlaps.