Claude Code lives in the terminal, so it pairs well with tmux, the tool for splitting a terminal and keeping it alive.
This guide covers why to run Claude Code inside tmux, how to run several sessions side by side, how to give each one its own git worktree, and the .tmux.conf lines that save you from the common annoyances.
Claude Code's behavior and settings here follow the official docs (Configure your terminal and Run parallel sessions with worktrees), and were checked locally with Claude Code 2.1.303 and tmux 3.7c.
What tmux adds
Running Claude Code inside tmux gives you three things:
- It keeps running. Claude Code runs inside the tmux server. Close the terminal or lose your SSH connection, and the work goes on
- Side by side. Split the screen into panes and run two or three Claude Code sessions at once, each in view
- You notice when it needs you. While you work in another window, the status line marks the window where Claude Code is waiting
If you'd like to learn tmux itself first (sessions, windows and panes), the keys and commands cheat sheet in tmux Introduction is a good companion.
Start one session that survives disconnects
If you hand Claude Code a long task on a server or a remote dev box, create a tmux session before you start it.
Create a named session
tmux new -s shopshop is the session name. Naming it after the project makes it easy to find later.
Start Claude Code inside it
claudeFrom here, use Claude Code as usual.
Detach, and come back later
Press Ctrl+b, then d, to detach from tmux and return to your original shell.
Claude Code keeps working.
To get back to it:
tmux attach -t shopThe same goes for a dropped SSH connection.
Reconnect, run tmux attach -t shop, and the screen is exactly where you left it.
Run sessions side by side in panes
Press Ctrl+b, then % to split left and right, or " to split top and bottom.
Start claude in each pane and two tasks move forward at the same time.
Keys you'll use once the panes are up:
| Keys | What it does |
|---|---|
Ctrl+b → ← → ↑ ↓ | Move to the neighboring pane |
Ctrl+b → z | Zoom the current pane to fill the screen (again to restore) |
Ctrl+b → c | Create a new window (a tab) |
Ctrl+b → w | Pick a window or pane from a list |
Panes work well for two sessions you want to watch together. For three or more, give each task its own window so nothing gets too cramped.
Don't share a folder: split with git worktrees
Splitting panes doesn't split files. Two Claude Code sessions in the same folder will overwrite the same files, and one session's tests can fail on the other's half-finished changes.
Git worktrees solve this.
A worktree is an extra working folder checked out from the same repository on its own branch.
The history (.git) is shared, but each folder has its own files.
Start Claude Code with claude -w
Claude Code can create a worktree and start inside it:
claude --worktree auth # or the short form: claude -w auth- The folder is
.claude/worktrees/auth/, on a new branch namedworktree-auth - By default, the branch starts from the remote's default branch (usually
main) - Leave out the name and Claude Code picks one, such as
bright-running-fox - If you've never run Claude Code in the repository, it exits with an error instead of asking whether you trust the folder. Run
claudethere once and answer the trust prompt first
Add .claude/worktrees/ to .gitignore.
Otherwise the worktrees show up as untracked files in your main checkout's git status.
echo '.claude/worktrees/' >> .gitignoreA worktree is a fresh checkout, so files Git doesn't track, such as .env, aren't there.
List them in a .worktreeinclude file at the repository root, using .gitignore syntax, and Claude Code copies them into every new worktree.
.env
.env.localWhen you exit, Claude Code removes the worktree and its branch if there are no changes or commits in it.
If there's work in it, Claude Code asks whether to keep it. To return to a worktree you kept, run the claude --worktree <name> --resume command it prints on exit.
Combine it with tmux
A simple layout is one window per task, with claude -w in each:
tmux new -s shop
claude -w auth
# press Ctrl+b c for a new window, then
claude -w fix-headerRename a window with Ctrl+b → ,. Use the worktree name, and the status line tells you which window is which task.
Create the worktree yourself
To work on a branch that already exists, or to put the folder outside the repository, create the worktree with git and then start claude in it:
git worktree add ../shop-fix -b fix-header # on a new branch
cd ../shop-fix
claude
git worktree list # list worktrees
git worktree remove ../shop-fix # remove it when you're doneNotice approval prompts: the bell and the status line
While you work in another window, you won't see Claude Code waiting for approval.
Add this to ~/.claude/settings.json and Claude Code rings the terminal bell when it needs you (when it waits for approval, or sits waiting for input after replying):
{
"preferredNotifChannel": "terminal_bell"
}tmux marks any window that rings the bell with a ! in the status line.
Press Ctrl+b and then the window number to jump there.
In a local test without this setting, Claude Code inside tmux didn't ring the bell, and no ! appeared. (Ghostty, Kitty and iTerm2 show desktop notifications by default, but inside tmux those need the allow-passthrough setting below.)
What to put in .tmux.conf
The three things that most often trip people up with Claude Code in tmux are Shift+Enter, notifications, and mouse scrolling.
Add these lines to ~/.tmux.conf:
# Let Shift+Enter insert a newline (tmux passes it on as a distinct key)
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
# Let Claude Code's notifications and progress updates reach the outer terminal
set -g allow-passthrough on
# Scroll the Claude Code conversation with the mouse wheel
set -g mouse onApply them to the running tmux server with:
tmux source-file ~/.tmux.confIn any terminal, Ctrl+J or a \ followed by Enter also inserts a newline. /terminal-setup, which enables Shift+Enter in terminals like VS Code, writes to the terminal's own configuration, so run it outside tmux.
Scrolling and searching
Recent versions of Claude Code may draw with fullscreen rendering, taking over the whole screen the way vim does. If the input box stays fixed at the bottom of the screen, that's the mode you're in. In this mode the conversation isn't in tmux's history, so a few things work differently:
| To do this | In fullscreen rendering |
|---|---|
| Scroll back | Mouse wheel (needs set -g mouse on), or PgUp / PgDn |
| Search the conversation | Ctrl+o for transcript mode, then / |
| Use tmux copy mode | Ctrl+o, then [ to write the conversation into the terminal's scrollback, then Ctrl+b → [ |
With the classic renderer, where the input box scrolls along with the output, the conversation stays in tmux's history, and Ctrl+b → [ copy mode works as usual.
tmux 3.6 and earlier don't support synchronized output, so Claude Code may flicker more inside them. If it bothers you, upgrade tmux.
Watch agent team members in tmux panes
Agent teams let one Claude Code session act as a lead that hands work to other Claude Code sessions, its teammates.
As of October 2026 the feature is experimental. Turn it on with the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
By default, teammates run inside the lead's screen. Add this to ~/.claude/settings.json and, when you start Claude Code inside tmux, each teammate gets its own tmux pane:
{
"teammateMode": "auto"
}"auto" splits into panes only when you start inside tmux (or in iTerm2 with the it2 CLI installed), and otherwise keeps everyone in one screen.
If a tmux session lingers after the team is done, find it with tmux ls and close it with tmux kill-session -t <name>.
FAQ
Why doesn't Shift+Enter insert a newline in Claude Code inside tmux?
By default, tmux sends Shift+Enter as a plain Enter. Add set -s extended-keys on and set -as terminal-features 'xterm*:extkeys' to ~/.tmux.conf, then reload it with tmux source-file ~/.tmux.conf. Without any setup, Ctrl+J or a \ followed by Enter also inserts a newline in every terminal.
Why can't I scroll Claude Code with the mouse wheel inside tmux?
When Claude Code uses fullscreen rendering, the mouse wheel needs tmux's mouse mode. Add set -g mouse on to ~/.tmux.conf and reload it. PgUp and PgDn work without it.
Can I run two Claude Code sessions in the same repository?
Not in the same working folder, or the sessions will overwrite each other's files. Start each one with claude --worktree <name> (or claude -w <name>). Claude Code creates a separate folder at .claude/worktrees/<name>/ on a new branch named worktree-<name>.
How do I keep Claude Code running after SSH disconnects?
On the server, run tmux new -s <name> first and start claude inside it. Claude Code runs inside the tmux server, so it keeps working when the connection drops. After you reconnect, run tmux attach -t <name> to get back to it.
How do I notice an approval prompt while I'm in another tmux window?
Add "preferredNotifChannel": "terminal_bell" to ~/.claude/settings.json. Claude Code then rings the terminal bell when it needs you, and tmux marks that window with a ! in the status line.
Practice tmux in your browser
Every tmux move in this guide (creating a session, detaching and reattaching, splitting panes and windows, copy mode) is in tmux Introduction, where you drive a faithful tmux right in your browser. Nothing to install. It plays like a game, one step at a time, until the keys are in your fingers.
tmux isn't the only tool for running AI agents side by side. Herdr shows every agent's state (working, waiting for approval, done) at a glance, and you can practice it the same way in Herdr Introduction.