tmux with
Claude Code

tmux Fundamentals

• What tmux is and why it matters
• Installation and first session
• The prefix key concept
• Sessions, windows, and panes

Terminal Multiplexer

tmux lets you run multiple terminal sessions inside a single terminal window. Sessions persist in the background even when you disconnect — your work keeps running.

Linux

# Debian / Ubuntu
sudo apt install tmux

# Fedora / RHEL
sudo dnf install tmux

# Arch
sudo pacman -S tmux

Your First Session

# Start a new session
$ tmux

# Start a named session
$ tmux new -s myproject

# You're now inside tmux!
# Notice the green status bar
# at the bottom of the terminal

How tmux Commands Work

Every tmux keybinding starts with a prefix key, followed by the actual command key. The default prefix is:

Ctrl + b

Press Ctrl+b, release both keys, then press the command key.

Creating Sessions

# New session (auto-named 0, 1, 2...)
tmux new

# Named session
tmux new -s project-alpha

# New session starting in a directory
tmux new -s api -c ~/code/api

What Are Windows?

Windows are tabs within a session. Each window occupies the full terminal and can contain one or more panes. The status bar at the bottom shows your window list.

Splitting

# Horizontal split (top / bottom)
Prefix "

# Vertical split (left / right)
Prefix %

Splits always divide the currently focused pane.

Zoom & Layouts

# Zoom: toggle pane fullscreen
Prefix z
# Press again to un-zoom

# Cycle through built-in layouts
Prefix Space

# Preset layouts
Prefix M-1  → even-horizontal
Prefix M-2  → even-vertical
Prefix M-3  → main-horizontal
Prefix M-4  → main-vertical
Prefix M-5  → tiled

Entering Copy Mode

# Enter copy mode
Prefix [

# You can now scroll up/down
# with arrow keys or Page Up/Down

# Exit copy mode
q  or  Escape

Copy mode is how you scroll back through terminal output in tmux. Without it, scrolling doesn't work as expected.

Starter Configuration

# ~/.tmux.conf

# Remap prefix to Ctrl+a
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Enable mouse support
set -g mouse on

# Start windows and panes at 1
set -g base-index 1
setw -g pane-base-index 1

# Vi copy mode
setw -g mode-keys vi

# Large scrollback
set -g history-limit 50000

# Faster key repetition
set -sg escape-time 0

# True colour support
set -g default-terminal "tmux-256color"
set -ag terminal-overrides \
  ",xterm-256color:RGB"

Status Bar Anatomy

The bar at the bottom of every tmux session has three sections:

• Left — session name
• Centre — window list
• Right — system info (time, host, etc.)

Enable Mouse Support

# ~/.tmux.conf
set -g mouse on

With mouse on, you can:

• Click to select a pane
• Drag pane borders to resize
• Scroll to enter copy mode and browse history
• Click on window names in the status bar

The Killer Feature

tmux sessions persist independently of your terminal connection. If your SSH drops, your laptop goes to sleep, or you accidentally close a tab — everything keeps running.

Why tmux + Claude Code?

• Persistence — Claude Code can work for hours; tmux keeps it alive if your connection drops
• Multitasking — run Claude in one pane while you test, review, or code in another
• Monitoring — watch Claude's output alongside build logs, test results, or git status
• Parallel agents — run multiple Claude Code instances on different tasks

Non-Interactive Mode

Claude Code supports a headless (non-interactive) mode via the -p flag — perfect for fire-and-forget tasks in tmux:

# Send a prompt non-interactively
claude -p "Refactor the auth module \
  to use JWT tokens"

# With auto-accept for tool use
claude -p "Add unit tests for utils.ts" \
  --allowedTools Edit,Write,Bash

One Session per Project

# Create sessions for each project
tmux new -s api -c ~/code/api -d
tmux new -s frontend -c ~/code/app -d
tmux new -s infra -c ~/code/terraform -d

# The -d flag creates without attaching

# Now switch between them:
Prefix s   → session picker
Prefix (   → previous session
Prefix )   → next session

Each session starts in its own directory, with its own windows and panes.

Sessions

Session Groups

# Share a session across terminals
# (each can view different windows)
tmux new -s main
# In another terminal:
tmux new -t main -s viewer

# Both see the same session,
# but can look at different windows

Colours Look Wrong

# Add to .tmux.conf:
set -g default-terminal "tmux-256color"
set -ag terminal-overrides \
  ",xterm-256color:RGB"

# Make sure your terminal emulator
# supports true colour (most do)

Kill a Frozen Pane

# If a pane is unresponsive:
Prefix x   → kill-pane (confirm)

# Nuclear option:
tmux kill-pane -t 2

Recommended Configuration

# ~/.tmux.conf — opinionated starter

# ── Prefix ──
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# ── General ──
set -g mouse on
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -sg escape-time 0
set -g history-limit 50000
setw -g mode-keys vi

# ── Terminal ──
set -g default-terminal "tmux-256color"
set -ag terminal-overrides \
  ",xterm-256color:RGB"

# ── Splits ──
bind | split-window -h \
  -c "#{pane_current_path}"
bind - split-window -v \
  -c "#{pane_current_path}"
unbind '"'
unbind %

What We Covered

• tmux fundamentals — server, sessions, windows, panes
• The prefix key and core keybindings
• Session management and persistence
• Copy mode, scrollback, and searching
• Configuration and status bar theming
• Running Claude Code effectively in tmux
• Headless mode and parallel agent workflows
• Multi-project workspace automation