tmux
Complete tmux management for terminal multiplexing.
Core Concepts
┌─────────────────────────────────────────────────────────────┐
│ SERVER (one per socket) │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ SESSION ($0, $1, ...) │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ WINDOW (@0) │ │ WINDOW (@1) │ ... │ │
│ │ │ ┌────┬────┐ │ │ ┌────────────┐ │ │ │
│ │ │ │PANE│PANE│ │ │ │ PANE │ │ │ │
│ │ │ │ %0 │ %1 │ │ │ │ %2 │ │ │ │
│ │ │ └────┴────┘ │ │ └────────────┘ │ │ │
│ │ └─────────────────┘ └─────────────────┘ │ │
│ └───────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
- Server: Background process managing all state
- Session (
$id): Named container of windows, persists after detach - Window (
@id): Tab-like container of panes within a session - Pane (
%id): Individual terminal within a window - Client: Terminal attached to a session
Router
| User says | Load reference | Do |
|---|
| list sessions / status | references/session-management.md | inspect sessions |
| new session / create session | references/session-management.md | create session |
| attach / detach | references/session-management.md | attach/detach |
| kill session | references/session-management.md | terminate session |
| new window / create window | references/window-management.md | create window |
| rename window | references/window-management.md | rename window |
| kill window / close window | references/window-management.md | close window |
| switch window | references/window-management.md | navigate windows |
| split / new pane | references/pane-management.md | split pane |
| resize pane | references/pane-management.md | resize pane |
| move pane / swap pane | references/pane-management.md | rearrange panes |
| kill pane / close pane | references/pane-management.md | close pane |
| layout | references/layouts.md | apply/manage layouts |
| copy / paste / buffer | references/copy-mode.md | copy mode operations |
| config / tmux.conf / settings | references/configuration.md | configure tmux |
| keybind / bind / unbind | references/keybindings.md | key bindings |
| script / automate / send-keys | references/scripting.md | scripting/automation |
| capture / log / output | references/scripting.md | capture pane content |
| help / keys / cheatsheet | inline | show key reference |
Default Key Bindings (Prefix: C-b)
Session
| Key | Action |
|---|
d | Detach from session |
s | List/switch sessions |
$ | Rename session |
( / ) | Previous/next session |
Window
| Key | Action |
|---|
c | Create window |
& | Kill window (confirm) |
, | Rename window |
0-9 | Switch to window N |
n / p | Next/previous window |
l | Last window |
w | List windows |
f | Find window |
Pane
| Key | Action |
|---|
% | Split horizontally (left/right) |
" | Split vertically (top/bottom) |
x | Kill pane (confirm) |
o | Cycle panes |
q | Show pane numbers |
z | Toggle zoom |
{ / } | Swap pane left/right |
! | Break pane to window |
| Arrows | Navigate panes |
Space | Cycle layouts |
C-o | Rotate panes |
Copy Mode
| Key | Action |
|---|
[ | Enter copy mode |
] | Paste buffer |
= | Choose paste buffer |
# | List buffers |
Quick Reference
# Session
tmux new -s name # Create named session
tmux attach -t name # Attach to session
tmux ls # List sessions
tmux kill-session -t name # Kill session
# Window
tmux new-window -n name # Create named window
tmux select-window -t :N # Go to window N
tmux rename-window name # Rename current window
# Pane
tmux split-window -h # Split horizontal
tmux split-window -v # Split vertical
tmux select-pane -t :.N # Go to pane N
tmux resize-pane -D 5 # Resize down 5 lines
# Info
tmux list-keys # All key bindings
tmux info # Server info
Safety Rules
- Confirm before kill: Always confirm before
kill-session, kill-window, kill-pane - Check attachments: Before killing, check if session has active clients
- Preserve work: Warn if panes have running processes
- Config backup: Before editing
~/.tmux.conf, suggest backup
Confirmation Policy
Read-only (always OK):
tmux ls, list-sessions, list-windows, list-panestmux info, show-options, display-messagetmux list-keys, list-buffers
Requires confirmation:
kill-session, kill-window, kill-panekill-server- Editing
~/.tmux.conf send-keys to panes (can affect running processes)
Environment Variables
| Variable | Description |
|---|
TMUX | Socket path (set inside tmux) |
TMUX_PANE | Current pane ID |
Check if inside tmux: [-n "$TMUX"]
Troubleshooting
| Issue | Solution |
|---|
| "no server running" | Start with tmux or tmux new |
| "sessions should be nested" | Unset $TMUX or use tmux -u |
| Detached session lost | Check tmux ls, attach with tmux attach |
| Colors not working | Set TERM=xterm-256color or set -g default-terminal "tmux-256color" |
| Mouse not working | set -g mouse on in config |
