tmux is a terminal multiplexer that lets you run multiple terminal sessions inside a single window. You can create, manage, and switch between sessions, split your terminal into panes, and detach/reattach sessions — keeping processes running in the background.

How do I install tmux?

On macOS: brew install tmux. On Ubuntu/Debian: sudo apt install tmux. On Fedora/RHEL: sudo dnf install tmux. Verify with: tmux -V.

How do I create a new tmux session?

Run tmux new-session -s session-name (or tmux new -s name for short). This creates a named session you can detach from and reattach to later.

How do I split the terminal in tmux?

Press Ctrl+b then % to split vertically (left/right), or Ctrl+b then " to split horizontally (top/bottom). Navigate between panes with Ctrl+b followed by an arrow key.

How do I detach from a tmux session?

Press Ctrl+b then d to detach. The session keeps running in the background. Reattach with tmux attach -t session-name.

How do I use tmux to run multiple AI agents in parallel?

Create separate tmux sessions for each AI agent (e.g., tmux new -s agent1 -d, tmux new -s agent2 -d). Use git worktrees to give each agent an isolated working directory. Switch between sessions with tmux attach -t name, or use tmux windows within a single session for a unified view.

What is the tmux prefix key?

The default prefix key is Ctrl+b. You press it before any tmux keyboard shortcut. For example, Ctrl+b then c creates a new window. You can remap it in ~/.tmux.conf if you prefer a different key like Ctrl+a.

How do I scroll up in tmux?

Press Ctrl+b then [ to enter copy mode, then use arrow keys, Page Up/Down, or mouse wheel (if mouse mode is enabled with set -g mouse on in .tmux.conf) to scroll. Press q or Escape to exit copy mode.

tmux Cheat Sheet

A quick reference to tmux — the terminal multiplexer that lets you run multiple terminal sessions in a single window. Detach, reattach, split panes, and manage sessions like a pro.

Beginner friendly

AI agent workflows

Copy-ready commands

Core Concepts

Session

A collection of windows. Sessions persist in the background when you detach — your work keeps running.

Window

A full-screen terminal tab within a session. Switch between windows like browser tabs.

Pane

A split within a window. See multiple terminals side by side in a single view.

Prefix key: All tmux shortcuts start with Ctrl+b (the prefix), then the action key. For example, Ctrl+b then c creates a new window.

tmux for AI Agent Workflows

Run multiple AI coding agents (Claude Code, Cursor, Aider, etc.) in parallel using tmux sessions. Each agent gets its own isolated terminal, and you can monitor them all from a single screen.

Why tmux + AI agents?

✓ Run 2-8 agents in parallel without losing track
✓ Detach and reattach — agents keep working while you're away
✓ Named sessions make it easy to identify what each agent is doing
✓ Send commands to agents without switching context

Recommended setup

1. One tmux session per project, one window per agent
2. Use git worktrees for isolated working directories
3. Keep a dedicated window for review and testing
4. Start with 2 agents, scale up as you get comfortable

Quick start: parallel agents

bootstrap-agents.sh

#!/bin/bash
# bootstrap-agents.sh — Spin up parallel AI agent sessions

SESSION="agents"
REPO="${1:-.}"

# Create the main session
tmux new-session -s "$SESSION" -d -x 200 -y 50

# Window 0: Coordination / status overview
tmux rename-window -t "$SESSION:0" "status"

# Window 1: Agent 1
tmux new-window -t "$SESSION" -n "agent1"

# Window 2: Agent 2
tmux new-window -t "$SESSION" -n "agent2"

# Window 3: Review & testing
tmux new-window -t "$SESSION" -n "review" -c "$REPO"

# Attach to the session
tmux attach-session -t "$SESSION"

With git worktrees (isolated directories)

worktree-agents.sh

#!/bin/bash
# worktree-agents.sh — Isolated agents with git worktrees

REPO="${1:-.}"
SESSION="dev-agents"

# Create isolated worktrees for each agent
git worktree add "$REPO/wt-agent1" -b agent1-work
git worktree add "$REPO/wt-agent2" -b agent2-work

# Create tmux session with a window per agent
tmux new-session -s "$SESSION" -d -c "$REPO/wt-agent1" -n "agent1"
tmux new-window -t "$SESSION" -n "agent2" -c "$REPO/wt-agent2"
tmux new-window -t "$SESSION" -n "main" -c "$REPO"

# Start Claude Code in each agent window
tmux send-keys -t "$SESSION:agent1" "claude" Enter
tmux send-keys -t "$SESSION:agent2" "claude" Enter

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

Monitor agents without switching

# Monitor all running agent sessions
tmux list-sessions
# agents: 4 windows (created ...)

# Check what's happening in agent1 without switching
tmux capture-pane -t agents:agent1 -p | tail -5

# Send a command to all agent windows
for win in agent1 agent2; do
  tmux send-keys -t "agents:$win" "git status" Enter
done

Installation

brew install tmux

Install tmux on macOS via Homebrew

sudo apt install tmux

Install tmux on Ubuntu / Debian

sudo dnf install tmux

Install tmux on Fedora / RHEL

tmux -V

Check installed tmux version

Session Management

tmux

Start a new unnamed session

tmux new -s name

Create a new named session

tmux new -s name -d

Create a new named session in the background (detached)

Ctrl+b d

Detach from current session (it keeps running in the background)

tmux ls

List all active sessions

tmux attach -t name

Attach to a named session

tmux kill-session -t name

Kill (terminate) a specific session

tmux kill-server

Kill the tmux server and all sessions

tmux rename-session -t old new

Rename a session

Ctrl+b $

Rename the current session

Ctrl+b s

Show session picker (interactive list of all sessions)

Ctrl+b (/)

Switch to the previous / next session

tmux send-keys -t session "cmd" Enter

Send a command to a session without attaching to it

Window Management

Ctrl+b c

Create a new window

Ctrl+b ,

Rename the current window

Ctrl+b n

Move to the next window

Ctrl+b p

Move to the previous window

Ctrl+b 0-9

Jump to window by number (0 through 9)

Ctrl+b w

Show window picker (interactive list)

Ctrl+b l

Toggle between the last two active windows

Ctrl+b &

Close the current window (with confirmation)

tmux new-window -t session -n name

Create a named window in a specific session

Pane Management

Ctrl+b %

Split the current pane vertically (left / right)

Ctrl+b "

Split the current pane horizontally (top / bottom)

Ctrl+b Arrow

Move focus to the pane in that direction

Ctrl+b ;

Toggle between the current and previous pane

Ctrl+b o

Cycle to the next pane (clockwise)

Ctrl+b z

Toggle zoom — expand a pane to full window, or restore it

Ctrl+b Ctrl+Arrow

Resize the current pane (5 cells at a time)

Ctrl+b Alt+Arrow

Resize the current pane (1 cell at a time, fine-tune)

Ctrl+b {

Swap the current pane with the previous one

Ctrl+b }

Swap the current pane with the next one

Ctrl+b x

Close the current pane (with confirmation)

Ctrl+b !

Break the current pane out into a new window

Ctrl+b Space

Cycle through preset pane layouts (even-horizontal, even-vertical, etc.)

Copy Mode & Scrollback

Ctrl+b [

Enter copy mode — scroll through output history

q/Escape

Exit copy mode

Arrow/PgUp/PgDn

Navigate in copy mode (scroll up/down/left/right)

Space

Start selecting text (in copy mode)

Enter

Copy the selected text and exit copy mode

Ctrl+b ]

Paste the last copied text

/ or ?

Search forward (/) or backward (?) in copy mode

Configuration

Customize tmux by editing ~/.tmux.conf. After saving, reload with tmux source-file ~/.tmux.conf.

~/.tmux.conf

The tmux configuration file — edit this to customize tmux

tmux source-file ~/.tmux.conf

Reload your configuration without restarting tmux

Ctrl +b :

Open the tmux command prompt (run commands live)

Ctrl +b ?

List all key bindings

~/.tmux.conf — Recommended starter config

# ~/.tmux.conf — Recommended starter config

# Increase scrollback buffer
set -g history-limit 10000

# Enable mouse support (scroll, click, resize)
set -g mouse on

# Reduce escape key delay (important for Vim users)
set -sg escape-time 0

# Renumber windows when one is closed
set -g renumber-windows on

# Start window numbering at 1 (not 0)
set -g base-index 1
setw -g pane-base-index 1

# Better colors
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:RGB"

# Vi-style copy mode
setw -g mode-keys vi

Custom key bindings

# Easier pane splitting
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Vi-style pane navigation
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Quick reload config
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

Status bar

# Status bar styling
set -g status-position top
set -g status-style bg=default,fg=white
set -g window-status-current-style bg=blue,fg=white,bold
set -g status-left "#[fg=green,bold] #S "
set -g status-right "#[fg=white] %H:%M "

Quick Reference

Action	Keys / Command
New session	`tmux new -s name`
Detach	`Ctrl`+`b` `d`
Reattach	`tmux attach -t name`
List sessions	`tmux ls`
New window	`Ctrl`+`b` `c`
Next window	`Ctrl`+`b` `n`
Split vertical	`Ctrl`+`b` `%`
Split horizontal	`Ctrl`+`b` `"`
Move between panes	`Ctrl`+`b` `Arrow`
Zoom pane	`Ctrl`+`b` `z`
Scroll / copy mode	`Ctrl`+`b` `[`
Paste	`Ctrl`+`b` `]`