How to Run Claude Code with tmux

tmux is the standard persistence layer for remote coding sessions with Claude Code. It keeps sessions running after terminal close, lets you run multiple agents in parallel, and makes reconnecting to a running session a one-command operation. Here's the complete workflow.

TL;DR

• tmux new -s name before every Claude Code session — name by project
• Detach: Ctrl+B D — reattach: tmux attach -t name
• Multiple agents: separate named sessions, or multiple windows in one session with Ctrl+B C
• Session recovery after reboot or crash: claude --continue
• Optional: add grass start in a second window for phone access without staying in tmux

Install tmux

macOS:

brew install tmux

Ubuntu/Debian:

sudo apt install tmux

Verify: tmux -V should return tmux 3.x.

The basic Claude Code + tmux workflow

# 1. Start a named session
tmux new -s project-name

# 2. Navigate to project and start Claude Code
cd ~/projects/myapp
claude

# 3. Detach (session keeps running)
# Ctrl+B D

# 4. Reattach later
tmux attach -t project-name

# 5. List all running sessions
tmux ls

# 6. Kill session when done
tmux kill-session -t project-name

Name sessions by project, not by number. tmux ls showing frontend, api, infra is useful; tmux ls showing 0, 1, 2 is not.

Resuming a Claude Code session after reattaching

After reattaching to tmux, Claude Code may have exited (task complete, hit an error, or naturally concluded). Resume with:

claude --continue

This restores the full conversation from the .jsonl transcript at ~/.claude/projects/<cwd>/. The Claude Code CLI reference also documents claude --resume <session-id> for resuming a specific past session by ID.

Running multiple Claude Code agents in parallel

This is where tmux becomes particularly useful. Three options, in increasing order of organization:

Option A — Multiple separate sessions (simplest)

tmux new -s project-a
# Run claude in project-a
# Ctrl+B D to detach

tmux new -s project-b
# Run claude in project-b
# Ctrl+B D to detach

tmux ls
# project-a: 1 windows
# project-b: 1 windows

tmux attach -t project-a

Each agent is completely isolated. Switch between them by detaching from one and attaching to the other.

Option B — Multiple windows in one session (more organized)

A single tmux session can contain multiple windows, each running a different Claude Code instance:

tmux new -s agents

# Window 1 is created automatically
cd ~/projects/frontend && claude

# Create a second window
# Ctrl+B C
cd ~/projects/api && claude

# List all windows
# Ctrl+B W  (arrow keys to select)

# Move between windows
# Ctrl+B N  (next window)
# Ctrl+B P  (previous window)

# Rename a window for clarity
# Ctrl+B ,  then type the project name

All your agents are inside one tmux session. tmux attach -t agents lands you wherever you left off.

Option C — Split panes (side-by-side monitoring)

# Vertical split (two panes side by side)
# Ctrl+B %

# Horizontal split (two panes stacked)
# Ctrl+B "

# Move between panes
# Ctrl+B arrow keys

Useful for watching two agents run simultaneously — output visible in both panes at once. Gets unwieldy with more than two agents; use windows for three or more.

See the Claude Code running tasks documentation for guidance on parallel session management from the Claude Code side.

Useful tmux configuration

Add to ~/.tmux.conf:

set -g mouse on               # scroll through output with mouse wheel
set -g history-limit 50000    # keep more scrollback — Claude Code sessions produce a lot
set -g status-right "#{session_name} | %H:%M"  # session name + time in status bar
set -g base-index 1           # start window numbering at 1

Reload without restarting tmux:

tmux source-file ~/.tmux.conf

Session recovery after machine reboot

A machine reboot kills the tmux server and all sessions inside it. AI coding agents in those sessions exit immediately.

Recovery:

1. Start a new tmux session
2. Navigate to the project directory
3. Run claude --continue — restores the conversation from the .jsonl transcript
4. Re-describe the task if the agent was mid-task when the reboot happened

Claude Code writes transcripts continuously, so you lose nothing from the conversation history — only the running state of any in-progress task.

For machines you can't always keep running, use a VPS or Daytona workspace instead — the session survives even if your local machine reboots.

Can I use screen instead of tmux?

Yes. GNU screen provides the same basic functionality:

screen -S project-name   # start named session
# Run claude inside
# Ctrl+A D to detach
screen -r project-name   # reattach
screen -ls               # list sessions

For new setups, tmux is the better choice — better documentation, more active development, cleaner multi-window handling. screen still works if it's already part of your workflow.

Going further: phone access without staying in tmux

tmux keeps your sessions running and organized. One optional addition: if you want to monitor output, get notified on agent approval gates, and send prompts from your phone without opening a terminal, install Grass and run it in a separate tmux window:

# In a new window (Ctrl+B C) or a second session:
npm install -g @grass-ai/ide
grass start

Scan the QR code from the Grass iOS or Android app. tmux handles persistence; Grass handles mobile coding agent access without SSH.

For remote access outside the local network: grass start --network tailscale (requires Tailscale on both machine and phone).

Frequently asked questions

How do I start Claude Code inside tmux?

Run tmux new -s session-name to create a session, then navigate to your project and run claude. All Claude Code output stays inside the tmux session. Detach with Ctrl+B D when you want to step away.

How do I detach from a Claude Code tmux session without stopping it?

Press Ctrl+B then D (hold Ctrl, press B, release both, then press D). The tmux session and Claude Code keep running in the background. Your terminal returns to the shell.

How do I run multiple Claude Code sessions in parallel with tmux?

Either create multiple separate tmux sessions (tmux new -s project-a, tmux new -s project-b) or use multiple windows in a single session (Ctrl+B C to create a new window). tmux ls shows all running sessions; tmux attach -t name connects to any of them.

How do I reattach to a Claude Code tmux session?

tmux attach -t session-name. If you don't remember the session name: tmux ls lists all active sessions.

What is the difference between tmux windows and panes for Claude Code?

Windows are separate terminal views within a session — like browser tabs. Panes are splits within a single window — like a split-pane editor. For monitoring multiple agents, windows are cleaner: each agent gets its own window and you switch between them with Ctrl+B W. Panes are useful for viewing two agents simultaneously.

Can I use screen instead of tmux for Claude Code?

Yes. screen works identically for the basic use case. Start with screen -S name, detach with Ctrl+A D, reattach with screen -r name. tmux has better tooling if you're starting fresh.

How do I name tmux sessions for different projects?

tmux new -s name creates a named session. Use project names: tmux new -s frontend, tmux new -s api. Rename an existing session: tmux rename-session -t old-name new-name. Rename a window: Ctrl+B , then type the new name.