tmux for Claude Code Users: Run Multiple Sessions Without Losing Your Mind

tmux (terminal multiplexer) splits one terminal into multiple independent sessions that keep running in the background. For Claude Code users, this means running 3-4 Claude sessions in parallel, each on a different project, and switching between them in under a second. Sessions persist when detached, so Claude keeps working while you check other sessions. Key commands: tmux new -s name to create, Ctrl+B, D to detach, tmux attach -t name to reconnect, Ctrl+B, S to switch between sessions interactively.

If you’re using Claude Code seriously, you’ve probably hit this wall: you want Claude working on Project A while you handle something on Project B, but you only have one terminal window and switching between them is slow and annoying. Every time you leave a session, you lose context. Every new tab is a fresh start.

tmux fixes this. Once you understand how it works, you’ll wonder how you managed without it.

What tmux actually is

tmux stands for terminal multiplexer. A multiplexer takes one thing and splits it into many. In this case, it takes your terminal and splits it into multiple independent sessions, windows, and panes, all running at the same time in the same terminal window.

Here’s the key thing to understand: tmux sessions keep running even when you’re not looking at them. You can “detach” from a session (step away from it), do something else, then “attach” back to it and everything is exactly where you left it. The process running inside, like a Claude Code session, kept going the whole time you were gone.

That’s different from a regular terminal tab. Close a tab, everything in it dies. Detach from a tmux session, it lives on in the background.

Why Claude Code users specifically need this

Claude Code runs as a persistent process. It works through files, runs commands, makes edits. The longer it runs on a problem, the more context it builds up. Interrupting it to switch to a different project means starting over.

With tmux, you can have:

Session 1: Claude working through a bug fix on your backend
Session 2: Claude doing a refactor on your frontend
Session 3: Your own terminal for running tests, checking git status, pushing commits
Session 4: Claude writing documentation while you do the actual work elsewhere

All four are running simultaneously. You switch between them in under a second. Nothing stops, nothing resets.

Installing tmux

On Mac (using Homebrew):

brew install tmux

On Ubuntu/Debian Linux:

sudo apt install tmux

On other Linux distros, use your package manager (dnf, pacman, yum, etc.). On most systems, tmux is either already installed or one command away.

After installing, confirm it worked:

tmux -V

That prints the version. If you see something like tmux 3.4, you’re good.

The three things tmux is made of

Before getting into commands, it helps to have a mental model.

Sessions are the top-level containers. Each session is an independent workspace. You give sessions names. You can have five sessions running and switch between them. If you close your terminal entirely and come back, your named sessions are still there (as long as the computer didn’t restart).

Windows live inside sessions. They’re like tabs in a browser. Each session can have multiple windows. You switch between them with a keyboard shortcut.

Panes live inside windows. Panes are the actual split views you see. You can split a window horizontally or vertically into two, three, or more panes, each running a separate terminal process.

For Claude Code work, sessions are the main unit. One session per project, one Claude instance per session.

Starting your first tmux session

Open your terminal and type:

tmux new -s project-a

The -s flag gives the session a name. Name it something meaningful. You’re now inside a tmux session. You can tell because there’s a green status bar at the bottom of your terminal.

Start Claude Code normally:

claude

Claude is now running inside a named tmux session.

Detaching and reattaching

This is the whole trick.

To detach from a session without killing it, press:

Ctrl+B, then D

That’s the “prefix key” (Ctrl+B) followed by d for detach. You’ll be dropped back to your regular terminal. The tmux session, and the Claude Code process running inside it, keeps going.

To list all your running sessions:

tmux ls

You’ll see something like:

project-a: 1 windows (created Sat Mar 14 09:00:00 2026)
project-b: 1 windows (created Sat Mar 14 09:05:00 2026)

To reattach to a session:

tmux attach -t project-a

You’re back. Claude is still mid-thought. Nothing was lost. For auto-naming sessions based on what they’re working on, see Claude Code Hooks.

The prefix key

Almost every tmux command starts with the prefix key. The default is Ctrl+B. You press it, release it, then press the command key. It’s not a chord, it’s a sequence.

Ctrl+B, D = detach
Ctrl+B, $ = rename current session
Ctrl+B, S = show all sessions (interactive switcher)
Ctrl+B, N = next window
Ctrl+B, P = previous window
Ctrl+B, C = create new window
Ctrl+B, % = split pane vertically (side by side)
Ctrl+B, " = split pane horizontally (top and bottom)
Ctrl+B, arrow key = move between panes
Ctrl+B, Z = zoom a pane to full screen (press again to unzoom)

The Ctrl+B, S switcher is especially useful once you have multiple sessions running. It shows all your sessions in a list you can navigate with arrow keys.

Running multiple Claude Code sessions in parallel

Here’s the actual workflow.

Open your terminal and create a session for each project you want Claude working on. You can also combine this with a keyboard shortcut that launches Claude Code.

tmux new -s backend

Start Claude Code inside it:

claude

Detach:

Ctrl+B, D

Create the next session:

tmux new -s frontend

Start Claude Code:

claude

Detach again:

Ctrl+B, D

Repeat for as many projects as you’re juggling. Now switch between them with:

tmux attach -t backend

Or use the interactive switcher from inside any tmux session:

Ctrl+B, S

Navigate with arrow keys, hit Enter to switch.

Each Claude instance has been running on its own problem the whole time. You just check in, give it new direction if needed, detach, and move to the next one.

If you want Claude to handle session-spawning for you, see How to Spawn a New Claude Session.

Splitting panes for a monitoring view

Sometimes you want to see multiple things at once. For example, watching Claude’s output in one pane while running tests in another.

Inside a tmux window, split the screen vertically:

Ctrl+B, %

You now have two panes side by side. Move between them with:

Ctrl+B, arrow key

Split horizontally instead:

Ctrl+B, "

Zoom into one pane to see it full screen:

Ctrl+B, Z

Press Ctrl+B, Z again to zoom back out.

For Claude Code work, a common setup is Claude running in the left pane and a shell in the right pane where you check file changes, run git diff, or test commands.

Basic tmux customization

tmux reads from ~/.tmux.conf on startup. This file doesn’t exist by default, you create it.

Here’s a minimal config worth having:

# ~/.tmux.conf

# Change prefix from Ctrl+B to Ctrl+A (easier to reach)
unbind C-b
set-option -g prefix C-a
bind-key C-a send-prefix

# Enable mouse support (click to switch panes, scroll)
set -g mouse on

# Start window numbering at 1 instead of 0
set -g base-index 1

# Increase scrollback buffer
set -g history-limit 10000

# Status bar: show session name, window list, time
set -g status-left "[#S] "
set -g status-right "%H:%M"

After editing the file, reload it without restarting tmux:

Ctrl+B, :source-file ~/.tmux.conf

The prefix key change is worth thinking about. Ctrl+B requires your left hand to stretch. Ctrl+A is closer. Some people remap it to the backtick key. Pick whatever feels fast to you.

Killing sessions you don’t need

When you’re done with a project session:

tmux kill-session -t project-a

Or, from inside a session, just exit all panes (type exit in the shell or Ctrl+D). When the last pane in a session closes, the session ends.

If your computer restarts

Regular tmux sessions don’t survive a reboot. If you need persistence across restarts, look into tmux-resurrect, a plugin that saves and restores sessions. That’s more advanced and probably not necessary when you’re starting out.

For most Claude Code workflows, the sessions you care about are short-lived anyway. You start a session for a task, work through it, close it when done.

Common Questions

What is tmux and why do Claude Code users need it?

tmux is a terminal multiplexer that lets you run multiple terminal sessions simultaneously. Claude Code builds context over time, so interrupting a session to switch projects means starting over. tmux lets you detach from one session, start another, and return to the first with everything intact.

How do I run multiple Claude Code sessions at once?

Create named tmux sessions with tmux new -s project-name, start Claude Code inside each, then detach with Ctrl+B, D. Switch between sessions with tmux attach -t name or use Ctrl+B, S for an interactive switcher. Each Claude instance continues working independently.

Do tmux sessions survive closing the terminal?

Yes, tmux sessions run in the background after detaching. They persist until explicitly killed or until the computer restarts. The tmux-resurrect plugin can save and restore sessions across reboots, but most Claude Code work sessions are short-lived enough that this isn’t needed.

What is the tmux prefix key?

The prefix key (default Ctrl+B) is pressed and released before every tmux command. It’s a sequence, not a chord. Common sequences: Ctrl+B, D (detach), Ctrl+B, S (session list), Ctrl+B, % (split vertically). You can remap it to Ctrl+A in ~/.tmux.conf.

A note from Alex: hi i’m alex - i run code for creatives. i’m a writer so i feel that it is important to say - i had claude write this piece based on my ideas and ramblings, voice notes, and teachings. the concepts were mine but the words themselves aren’t. i want to say that because its important for me to distinguish, as a writer, what is written ‘by me’ and what’s not. maybe that idea will seem insane and antiquated in a year, i’m not sure, but for now it helps me feel okay about putting stuff out there like this that a) i know is helpful and b) is not MY voice but exists within the umbrella of my business and work. If you have any thoughts or musings on this, i’d genuinely love to hear them - its an open question, all of this stuff, and my guess is as good as yours.