What topics are covered in the tmux documentation hub?

The documentation hub covers core architecture, sessions, window & pane management, configuration, custom scripts, Ghostty & iTerm2 integrations, Claude Code workflows, and the unabridged man tmux manual.

tmux Docs — Documentation Hub

TL;DR — tmux lets you:

Run multiple terminal sessions in one window
Split the terminal into panes (horizontal or vertical)
Detach sessions that keep running in the background
Reattach to sessions from any terminal or SSH connection
Automate complex terminal layouts via scripts and plugins

What is tmux?

tmux (terminal multiplexer) is a free, open-source command-line tool for Unix-like systems that allows you to create, manage, and persist multiple terminal sessions from a single screen. It is released under the ISC license and runs on Linux, macOS, OpenBSD, FreeBSD, NetBSD, and Solaris.

tmux operates on a server-client architecture. When you run tmux, it starts a background server process that owns all sessions. Your terminal window connects to this server as a client. Because the server runs independently of any client, sessions persist after you close a terminal window or lose an SSH connection — you simply reconnect and reattach.

The three-level hierarchy is: Session → Window → Pane. A session groups one or more windows. Each window occupies the full terminal and can be split into multiple panes. Each pane runs an independent shell process.

What's New in tmux 3.5, 3.6 and 3.7

The current stable release is tmux 3.7c; 3.8 is in release-candidate testing. Check your version with tmux -V. These are the changes most people notice, taken from the official CHANGES file:

Version	Change	How to use it
3.7	Floating panes: non-modal panes that sit above the tiled layout. Early feature: move and resize them with the mouse only. Read the floating panes guide.	`Prefix *` or `tmux new-pane`
3.7	Line numbers in copy mode	`set -g copy-mode-line-numbers relative` (also `absolute`, `hybrid`)
3.7	Focus follows mouse	`set -g focus-follows-mouse on` (needs `mouse on`)
3.7	Messages can cover part of the status line; new `message-format` option	Add `fill=` to a custom `message-style` to colour the full width
3.7	Keep a finished pane open until you press a key	`set -g remain-on-exit key`
3.7	Built-in help in modes such as the tree chooser	Press `Ctrl+h` inside the mode
3.7	Applications can use synchronized output (no tearing) and OSC 9;4 progress bars	Automatic
3.6	Pane scrollbars	`set -g pane-scrollbars modal` (shown in copy mode) or `on`
3.6	Reports light/dark theme to applications (mode 2031); RGB detected from `COLORTERM`	Automatic
3.6	Borders made of spaces	`set -g pane-border-lines spaces`
3.5	Default `escape-time` lowered from 500 ms to 10 ms (no more Vim Esc lag)	Automatic
3.5	Mirrored main layouts (main pane at bottom or right)	`Prefix Alt+6` / `Alt+7`
3.5	Prefix key can time out	`set -g prefix-timeout 1000` (milliseconds)
3.5	Reworked extended keys (more key combinations reach apps such as Neovim)	`set -s extended-keys on`

Ubuntu 24.04 ships tmux 3.4 and Debian 12 ships 3.3a, so none of the features above are available there without a newer build. See the Linux install guide for options.

Installation

Platform-specific installation guides with full build-from-source instructions:

Quick Install (Most Common)

Platform quick-install

# macOS (Homebrew)

$ brew install tmux

# Ubuntu / Debian

$ sudo apt update && sudo apt install tmux

# Fedora / RHEL

$ sudo dnf install tmux

# Arch Linux

$ sudo pacman -S tmux

# Verify installation

$ tmux -V

Basic Usage Quickstart

bash — first session workflow

# Start a named session

$ tmux new -s work

# Split the window horizontally (side by side)

$ Ctrl+b %

# Split vertically (top and bottom)

$ Ctrl+b "

# Navigate between panes

$ Ctrl+b ← → ↑ ↓

# Detach (session keeps running)

$ Ctrl+b d

# List running sessions

$ tmux ls

# Reattach

$ tmux attach -t work

Understanding the Prefix Key

All tmux key bindings require a prefix key pressed first. The default prefix is Ctrl+b. Press and release the prefix, then press the command key. The prefix activates tmux's command interception and distinguishes tmux shortcuts from regular terminal input.

Many users remap the prefix to Ctrl+a (GNU Screen style) because it's easier to reach. Add to ~/.tmux.conf:

~/.tmux.conf — remap prefix

unbind C-b

set -g prefix C-a

bind C-a send-prefix

Sessions

A session is a persistent workspace that groups windows together and continues running when you detach or close your terminal. Sessions are managed by the tmux server and can be shared between users.

For the full command set and lifecycle workflows, see the dedicated tmux session management guide.

Session lifecycle commands

$ tmux new -s mysession # create and attach

$ tmux new -s mysession -d # create detached

$ tmux ls # list all sessions

$ tmux attach -t mysession # attach by name

$ tmux rename-session -t old new # rename

$ tmux kill-session -t mysession # kill session

$ tmux kill-server # kill ALL sessions

Named vs Unnamed Sessions

Named sessions (tmux new -s name) are persistent and easy to reattach by name. Unnamed sessions receive a numeric ID (0, 1, 2…). Always name sessions for important work: tmux new -s frontend.

Window Management

Windows are tabs within a session. Each window has its own set of panes. Switch between windows to work on different tasks within the same session.

Window commands

$ Prefix c # create window

$ Prefix , # rename window

$ Prefix n / p # next / previous

$ Prefix 0-9 # select by number

$ Prefix w # window chooser

$ Prefix & # kill window

$ tmux new-window -n logs

$ tmux move-window -t 3

Pane Splitting & Navigation

Panes divide a window into independent terminal areas. Each can run a different command or shell.

Pane commands

# Split

$ Prefix % # split left/right

$ Prefix " # split top/bottom

$ tmux split-window -h -l 30% # 30% width

# Navigate

$ Prefix ↑↓←→ # move focus

$ Prefix q # show pane numbers

# Resize

$ Prefix Ctrl+↑↓←→ # resize (hold)

$ tmux resize-pane -L 10

# Zoom / Kill

$ Prefix z # toggle fullscreen

$ Prefix x # kill pane

$ Prefix ! # break pane to window

Pane Synchronization

Synchronize-panes broadcasts keystrokes to all panes simultaneously — useful for running the same command on multiple servers at once.

~/.tmux.conf + command mode

# Toggle sync (from command mode: Prefix :)

setw synchronize-panes on

setw synchronize-panes off

# Bind to a key in .tmux.conf

bind e setw synchronize-panes

Pane Layouts

tmux has seven built-in layouts. Prefix Space cycles through them; Prefix Alt+1…Alt+7 jumps straight to one, and Prefix E spreads panes out evenly.

Layout	Key	Description
`even-horizontal`	`Prefix Alt+1`	All panes same width, side by side
`even-vertical`	`Prefix Alt+2`	All panes same height, stacked
`main-horizontal`	`Prefix Alt+3`	Large pane on top, the rest below
`main-vertical`	`Prefix Alt+4`	Large pane on the left, the rest on the right
`tiled`	`Prefix Alt+5`	Even grid of equal-sized panes
`main-horizontal-mirrored`	`Prefix Alt+6`	Large pane at the bottom (tmux 3.5+)
`main-vertical-mirrored`	`Prefix Alt+7`	Large pane on the right (tmux 3.5+)

Select a layout from a script: tmux select-layout main-vertical. Size the main pane with set -w main-pane-width 60%.

Copy Mode

Copy mode lets you scroll through terminal history, search text, and copy output to the paste buffer. Enter with Prefix [, exit with q.

Action	Vi mode	Emacs mode
Enter copy mode	`Prefix [`
Exit	`q`	`q` / `Esc`
Navigate	`h j k l`	`← ↓ ↑ →`
Search forward	`/`	`Ctrl+s`
Search backward	`?`	`Ctrl+r`
Start selection	`Space`	`Ctrl+Space`
Rectangle selection	`v`	`R`
Copy selection	`Enter`	`Alt+w`
Paste	`Prefix ]`
Page up / down	`Ctrl+b` / `Ctrl+f`	`Alt+v` / `Ctrl+v`
Jump to top / bottom	`g` / `G`	`Alt+<` / `Alt+>`

Enable vi keys: add setw -g mode-keys vi to ~/.tmux.conf.

System Clipboard Integration

By default, tmux uses its internal paste buffer. To integrate with the system clipboard:

~/.tmux.conf — clipboard integration

# macOS — use pbcopy

bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "pbcopy"

# Linux (X11) — use xclip

bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "xclip -in -selection clipboard"

# Linux (Wayland) — use wl-copy

bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "wl-copy"

# Windows WSL2 — use clip.exe

bind-key -T copy-mode-vi y send-keys -X copy-pipe-and-cancel "clip.exe"

# Or use the tmux-yank plugin (recommended)

set -g @plugin 'tmux-plugins/tmux-yank'

Configuration File

tmux reads its configuration from ~/.tmux.conf at startup. You can also use $XDG_CONFIG_HOME/tmux/tmux.conf or /etc/tmux.conf for system-wide settings.

Reload without restarting: tmux source-file ~/.tmux.conf (or Prefix : source-file ~/.tmux.conf).

~/.tmux.conf — sensible defaults

set -g mouse on

set -g history-limit 50000

set -g base-index 1

setw -g pane-base-index 1

set -g renumber-windows on

set -sg escape-time 10

set -g default-terminal "tmux-256color"

set -ga terminal-overrides ",*256col*:Tc"

For the full interactive config generator and all option reference, see /config/.

Key Binding Customization

~/.tmux.conf — key bindings

# Add a binding

bind r source-file ~/.tmux.conf \; display "Reloaded!"

# Remove a binding

unbind C-b

# Bind without prefix (-n flag)

bind -n M-Left select-pane -L

bind -n M-Right select-pane -R

# List all bindings

$ tmux list-keys

Status Bar Customization

~/.tmux.conf — status bar

set -g status-position top

set -g status-interval 5

set -g status-left " #[bold]#S #[nobold]| "

set -g status-right " %H:%M %d %b #H "

set -g status-style "bg=#1e1e2e,fg=#cdd6f4"

setw -g window-status-current-style "fg=#89b4fa,bold"

TPM — Tmux Plugin Manager

Install TPM

$ git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

# Add to top of ~/.tmux.conf:

set -g @plugin 'tmux-plugins/tpm'

set -g @plugin 'tmux-plugins/tmux-sensible'

# Add to VERY BOTTOM of ~/.tmux.conf:

run '~/.tmux/plugins/tpm/tpm'

# Inside tmux: install with Prefix + I

# Update: Prefix + U | Remove unused: Prefix + alt+u

Essential Plugins

Plugin	Install Snippet	Purpose
tmux-resurrect	`set -g @plugin 'tmux-plugins/tmux-resurrect'`	Save & restore sessions across reboots
tmux-continuum	`set -g @plugin 'tmux-plugins/tmux-continuum'`	Auto-save every 15 minutes
tmux-yank	`set -g @plugin 'tmux-plugins/tmux-yank'`	System clipboard in copy mode
tmux-sensible	`set -g @plugin 'tmux-plugins/tmux-sensible'`	Sane defaults for everyone
Dracula theme	`set -g @plugin 'dracula/tmux'`	Popular dark theme with status widgets

Full plugin guide: /plugins/

Scripting & Automation

tmux provides a rich scripting interface. Every tmux command can be run from outside tmux, making it easy to create reproducible development environments.

dev-session.sh — example automation

#!/bin/bash

# Create session if it doesn't exist

tmux has-session -t dev 2>/dev/null || tmux new-session -d -s dev -c ~/projects

# Set up editor pane

tmux rename-window -t dev:0 'editor'

tmux send-keys -t dev:0 'nvim .' Enter

# Create server pane (split)

tmux split-window -h -t dev:0

tmux send-keys -t dev:0 'npm run dev' Enter

# Create git window

tmux new-window -t dev -n 'git'

# Attach

tmux attach -t dev

Key Scripting Commands

tmux send-keys -t session:window.pane "command" Enter — send keystrokes to a pane
tmux has-session -t name — check if session exists (returns 0/1)
tmux if-shell "condition" "cmd" — conditional command execution
tmux run-shell "shell command" — run a shell command from tmux

Read Full Workspace Automation Guide →

Session Managers & Integrations

For complex, repeatable workspace layouts and IDE workflows:

Neovim + tmux Integration — Seamless split navigation, true color, and clipboard bridging.
Claude Code in tmux — Autonomous AI agent execution in background sessions.
tmuxinator — YAML-based session layouts, Ruby gem.
tmuxp — Python-based session manager with JSON/YAML configs.

tmux over SSH

tmux is the standard tool for remote server work. Start a tmux session on the remote server before starting long-running tasks. If your SSH connection drops, the session continues and you can reconnect.

SSH + tmux workflow

# Connect and start/attach session in one command

$ ssh -t user@server tmux new -A -s work # -t gives tmux the terminal it needs

# Or add to ~/.bashrc / ~/.bash_aliases on server:

[ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ] && tmux new -A -s default

# After reconnect, list sessions and reattach

$ ssh user@server

$ tmux ls

$ tmux attach -t work

Remote Pair Programming

Two developers can share a tmux session in real time — both see and control the same terminal. Useful for live code reviews and remote debugging.

Pair programming setup

# Host: create shared socket session

$ tmux -S /tmp/pair new -d -s pair

$ chgrp devteam /tmp/pair && chmod g+rw /tmp/pair

$ tmux -S /tmp/pair server-access -a guest # tmux 3.3+: allow read-write

$ tmux -S /tmp/pair server-access -ar observer # tmux 3.3+: allow read-only

$ tmux -S /tmp/pair attach -t pair

# Guest (same machine or SSH): attach