Sessions

Introduction

tmux is a terminal multiplexer: sessions keep running after you disconnect, and one terminal splits into windows and panes.

This sheet covers the default C-b prefix and the commands for scripting.

Start and attach

tmux                      # Start an unnamed session
tmux new -s work          # Start a session named work
tmux ls                   # List sessions
tmux a                    # Attach to the most recent session
tmux a -t work            # Attach to a named session

tmux a is short for attach-session; tmux new is new-session.

See: new-session

Detach and switch

C-b d               # Detach; the session keeps running
C-b s               # Choose another session
C-b (  C-b )        # Previous / next session
C-b $               # Rename the current session

Detaching leaves every program running; tmux a returns to it.

See: attach-session

Kill

tmux kill-session -t work       # Kill one session
tmux kill-session -a -t work    # Kill all except work
tmux kill-server                # Kill every session and the server

C-b :kill-session kills the session you are in.

See: kill-session

Prefix

Everyday chords

ChordAction
C-b ?List all key bindings
C-b :Open the command prompt
C-b dDetach from the session
C-b [Enter copy mode
C-b ]Paste the top buffer
C-b wPick a window
C-b sPick a session
C-b qShow pane numbers
C-b zZoom the current pane
C-b tShow a clock

C-b is the default prefix; every chord on this page starts with it.

See: Key bindings

Command prompt

C-b :new-window
C-b :split-window -h
C-b :rename-session work
C-b :set -g mouse on

The prompt accepts any tmux command, including settings. Tab completes command names.

See: Commands

Windows

Create and switch

C-b c               # New window
C-b 1               # Jump to window 1 (through 9)
C-b n  C-b p        # Next / previous window
C-b l               # Last active window
C-b w               # Choose a window from a list
C-b f               # Find by name or visible text

The status bar lists windows; * marks the active one.

See: Windows and panes

Rename and close

C-b ,               # Rename the window
C-b &               # Kill the window (asks first)
C-b .               # Move it to another index

Closing the last pane in a window closes the window.

See: kill-window

Panes

Split

C-b %               # Split left and right
C-b "               # Split top and bottom
C-b :split-window -h -l 30   # Split 30 columns wide

Each split runs its own shell, inside the same window.

See: split-window

C-b ← ↑ ↓ →         # Move to the pane in that direction
C-b o               # Next pane
C-b q               # Show pane numbers; press one to jump
C-b C-← C-→         # Resize by one cell
C-b M-← M-→         # Resize by five cells
C-b z               # Zoom the pane to fill the window
C-b Space           # Cycle through the preset layouts

With set -g mouse on, click a pane to focus it.

See: select-pane

Close and rearrange

C-b x               # Kill the pane (asks first)
C-b !               # Break the pane into its own window
C-b {  C-b }        # Swap with the previous / next pane
C-b C-o             # Rotate the panes

C-b z is the fastest way to give one pane the whole terminal.

See: break-pane

Copy mode

Select and copy

C-b [               # Enter copy mode
C-Space             # Start selection (emacs keys)
M-w                 # Copy the selection and exit
C-b ]               # Paste it

set -g mode-keys vi switches to Space to select and Enter to copy.

See: copy-mode

Search and scroll

C-b [               # Enter copy mode
C-s                 # Search forward
C-r                 # Search backward
n  N                # Next / previous match
Escape              # Exit copy mode

Scrolling with the wheel works in copy mode when mouse support is on. set -g mode-keys vi swaps in /, ?, and q.

See: copy-mode

Config

Settings

set -g mouse on
set -g base-index 1
setw -g pane-base-index 1
set -g history-limit 50000
set -g renumber-windows on
set -sg escape-time 10

tmux reads ~/.tmux.conf when the server starts, not on every attach.

See: Options

Reload

From a key

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

From the shell

tmux source-file ~/.tmux.conf

The first line adds C-b r; the second reloads on demand.

See: source-file

Change the prefix

set -g prefix C-a
unbind C-b
bind C-a send-prefix

Keep the send-prefix line so an application can still receive a literal C-a.

See: bind-key

Scripting

Detached sessions

tmux new-session -d -s work
tmux new -d -s build 'npm run build'
tmux has-session -t work 2>/dev/null || tmux new -d -s work

-d starts in the background; the last line creates the session if missing.

See: new-session

send-keys

tmux send-keys -t work:0 'git pull' C-m
tmux send-keys -t work:0.1 'ls -l' Enter

C-m is Enter. A target is session:window.pane.

See: send-keys

Reading output

tmux capture-pane -p -t work:0
tmux capture-pane -p -S -100 -t work:0   # Last 100 lines

capture-pane prints the visible screen; -S reaches into the scrollback.

See: capture-pane

Remote and nested

SSH

ssh host -t tmux a -t work
ssh host -t 'tmux new -A -s main'

-t forces a TTY; new -A attaches to the session or creates it.

See: tmux wiki

Nested sessions

C-b C-b             # Send C-b through to the inner tmux
C-b : send-prefix   # The same, as a command

Sessions belong to a server; tmux -L inner starts a second server on its own socket. $TMUX is set inside a session.

See: ENVIRONMENT

Status bar

Format strings

FormatShows
#SSession name
#IWindow index
#WWindow name
#FWindow flags
#PPane index
#TPane title
#HHostname
#(cmd)Output of a shell command
#{?condition,a,b}Conditional

status-left and status-right take the same strings as window-status-format.

See: Formats

Styles

#[fg=yellow,bold]
#[fg=colour240]
#[bg=default]
#[default]

Colours are names, colour0 to colour255, or #rrggbb. #[default] resets.

See: Styles

0 Comments for this cheatsheet. Write yours!