tmux — Getting Started & Cheatsheet
Prefix =
C-a · Solarized hand-rolled status bar · vim-style pane nav
C-a · Solarized hand-rolled status bar · vim-style pane nav
| Prefix | C-a (screen-style) |
Why not C-Space | conflicts with macOS input-source switching |
| Pane nav | C-a + h/j/k/l |
| Splits | C-a + | / - (cwd inherited) |
| Indexing | windows + panes start at 1, auto-renumber |
| Mouse | on (URLs: ⇧⌘ click) |
| History | 50,000 lines |
| Bells | silenced (bell-action/visual-bell/monitor-bell off) |
| TPM plugins | tpm, tmux-sensible, tmux-resurrect, tmux-continuum, tmux-sessionx |
tmux | start a new session |
tmux new -s <name> | named session |
tmux a / tmux a -t <name> | attach to last / named session |
tmux ls | list sessions |
| C-a d | detach (session keeps running) |
| C-a r | reload ~/.config/tmux/tmux.conf |
| C-a t | tmux-sessionx picker popup (tmux / tmuxinator) — live pane preview for the highlighted session |
s [<project>] [<name>] | create-or-attach worktree+session — inside tmux 1 arg = worktree name in current project, outside tmux 1 arg = project, 0 args = fzf picker |
| C-a T | clock-mode (swapped from default t) |
| C-a P | open current branch's PR in browser via gh pr view --web (silent when no PR — counterpart to the orange status-bar PR pin) |
| ⇧⌘ click | Claude Code file links → routes via macOS file-type defaults (OSC 8 passthrough enabled in tmux.conf via terminal-features hyperlinks) |
| C-a ? | list all keybindings |
| C-a : | command prompt |
C-a, not C-Space.bind -n M-* — Alt is reserved for Polish diacritics.preexec sets @last_cmd). allow-rename off stays so OSC titles can't override.git rev-parse --git-dir vs --git-common-dir. Don't replace with git worktree list parsing.| C-a d | detach |
| C-a s | session picker (tree) |
| C-a $ | rename current session |
| C-a ( / ) | prev / next session |
| C-a L | switch to last session |
Closing the last pane of a session (exit, Ctrl-D) switches to the most-recently-used other session via detach-on-destroy off. Detaches only when no other session exists.
tmux new -s work | create "work" |
tmux a -t work | attach to "work" |
tmux kill-session -t work | kill "work" |
tmux kill-server | kill all sessions |
tmux-resurrect + tmux-continuum auto-save sessions every 15 min and auto-restore on a fresh server. See the "Persistence" card below for bindings.
C-at opens
tmux-sessionx,
a TPM-loaded session picker. Sources: existing tmux sessions plus
tmuxinator projects (@sessionx-tmuxinator-mode 'on').
Zoxide is intentionally not a picker source
(@sessionx-zoxide-mode 'off'). The current session is
hidden from the list (@sessionx-filter-current 'true').
Highlighting an entry shows live pane content in the preview pane
(tmux capture-pane -ep on the session's active pane).
The plugin claims the binding via @sessionx-bind 't' —
no manual bind-key exists for this picker. Geometry is
pinned at 70% × 70% (@sessionx-window-width /
@sessionx-window-height), the shared anchor with the URL
and file pickers.
Sesh stays installed for bin/s (the worktree+session
command), which still reads sesh list -c -j as its
project registry. The shared .config/sesh/sesh.toml +
machine-local ~/.config/sesh/sesh.local.toml split is
unchanged. _ZO_EXCLUDE_DIRS excludes (~/,
~/Downloads/*, ~/.config/*,
~/Library/*) remain for z-cd hygiene.
| C-a C-s | save snapshot now (manual) |
| C-a C-r | restore latest snapshot (manual) |
| auto-save | every 15 min (continuum default) |
| auto-restore | on fresh tmux server start (@continuum-restore 'on') |
| snapshots in | ~/.local/share/tmux/resurrect/ |
Defaults only: no @resurrect-processes (panes get fresh shells in cwd; nvim/ssh are NOT relaunched), no @resurrect-capture-pane-contents (scrollback is not saved). Auto-restore only fires on a brand-new server with zero sessions, so attaching to an already-running server (sesh's normal flow) is unaffected.
dashboard '<pattern>' [--cols N] from the shell.
Spawns or rebuilds a dashboard-<derived> session
tiling live capture-pane output for every tmux session
whose name matches the glob. One tile per match; default layout is
tmux's tiled auto-shape. --cols N forces
an N-column grid.
| C-a J | page rows down (no-op outside dashboard-*) |
| C-a K | page rows up |
dashboard --rebuild | re-discover sources, refresh tiles (run inside the dashboard) |
Re-running dashboard '<pattern>' is idempotent —
kills only stale tiles and adds tiles for new matches. Outside tmux
the script attaches; inside tmux it
switch-clients to the dashboard.
| C-a c | create window — opens at session root (@session_root, set by s) when present, else inherits pane cwd |
| C-a , | rename window |
| C-a & | kill window (confirm) |
| C-a w | window picker (tree) |
| C-a . | move window (renumber) |
| C-a n / p | next / prev window |
| C-a 1…9 | window 1–9 by number |
| C-a l | last window (but l is also pane-right here — see "Quirks") |
| C-a f | find by name (search) |
Quirk: we rebind C-al to pane-right (vim style). To go to the previous window, use C-an/p or the picker.
Window name follows the active pane's last typed command, set by zsh preexec via @last_cmd. Env-var assignments are stripped first; the first two whitespace-separated tokens are used.
vim foo.rb → window name: vim foo.rbFOO=bar bundle exec rspec → bundle execpane_current_command (usually zsh)claude[<session-name>] (overrides last-typed-command label until Claude exits)allow-rename off stays — OSC titles from apps (e.g. Claude Code) cannot override.
| C-a h / j / k / l | left / down / up / right |
| C-a ; | last (most-recent) pane |
| C-a x | kill pane (confirm) |
| C-a q | show pane numbers (then number to jump) |
| C-a z | zoom toggle (full-screen pane) |
| C-a ! | break pane → its own window |
| C-a { / } | swap pane left / right in layout |
| C-a H / J / K / L | resize 5 cells (when bound by tmux-sensible) |
| C-a Space | cycle preset layouts |
| C-a M-1 … M-5 | specific layouts (M = Alt; avoid here) |
:resize-pane -D 5 | resize from prompt (D/U/L/R) |
:select-layout main-vertical | force a layout by name |
| C-a | | vertical split (right) — keeps cwd |
| C-a - | horizontal split (below) — keeps cwd |
Defaults " and % are unbound — use |/-.
| C-a [ | enter copy mode |
| q / Esc | exit copy mode |
| C-a ] | paste tmux buffer |
| C-a = | choose buffer to paste |
| h j k l | move cursor |
| w / b | word forward / back |
| 0 / $ | line start / end |
| g / G | top / bottom |
| / / ? | search forward / back |
| n / N | next / prev match |
| Space | begin selection |
| Enter | copy selection (to tmux buffer) |
| v / V | char / line selection (vi-mode) |
Mouse drag also selects. macOS clipboard is wired through tmux's default OSC 52 path; if your terminal supports it (Ghostty does) Enter reaches the system clipboard.
Bottom bar, bg=base02 / fg=base0. Three segments:
nf-fa-globe) when any attached tmux client is SSH-rooted (drives tmux-ssh-indicator).base01 on base02; active = green-on-base3 chip with rounded powerline caps.tmux-status-right → tmux-pr-detect + tmux-git-status.Selection / message style uses cyan-on-base03; pane border switches base01 → blue when active.
~/.config/tmux/bin/tmux-status-right | orchestrator for the right-side status segment — composes PR pin (when present) + git chip flush-right |
~/.config/tmux/bin/tmux-pr-detect | stale-while-revalidate file cache around gh pr view (TTL 60s) — echoes PR number for current branch or empty |
~/.config/tmux/bin/tmux-git-status | git/worktree status segment, colors as args |
~/.config/tmux/bin/claude-tmux-window-name | sets/clears @claude_session_name from Claude Code hooks (drives claude[<name>] window title) |
~/.config/tmux/bin/tmux-ssh-indicator | walks each attached client's ps ancestry; prints sshd/sshd-session — prepended inside the session chip |
scripts/test-helpers.sh | smoke-tests for the helpers |
scripts/test-tmux-pr-status.sh | smoke tests for tmux-pr-detect + tmux-status-right (uses a PATH-shimmed gh) |
Worktree detection uses git rev-parse --git-dir vs --git-common-dir so it works for .claude/worktrees/*, worktrunk paths, and sibling worktrees alike.
:new-window -c "#{pane_current_path}" | new window in same dir |
:swap-window -t :+1 | move window right |
:movew -r | renumber windows now |
:setw synchronize-panes | type to all panes (toggle) |
:clear-history | clear scrollback |
:source-file ~/.config/tmux/tmux.conf | reload (also C-ar) |
:show -g | grep … | inspect global options |
:list-keys | all bindings |
tmux send-keys -t mywin "ls" Enter | type into a target pane |
tmux display-message -p '#S' | print current session name |
tmux info | grep … | debug runtime state |
tmux show -p @last_cmd | read this pane's last command |
~/.config/tmux/tmux.conf# Prefix set -g prefix C-a # C-Space conflicts with macOS input-source switching # Terminal — truecolor set -as terminal-features ",xterm-ghostty:RGB" set -as terminal-features ",xterm-256color:RGB" # Sane defaults set -g mouse on set -g base-index 1 set -g renumber-windows on set -g history-limit 50000 set -g escape-time 10 # vim-friendly set -g focus-events on # Bells silenced everywhere set -g bell-action none set -g visual-bell off set -g monitor-bell off # Window naming: @claude_session_name (Claude hooks) overrides # @last_cmd (zsh preexec) overrides pane_current_command (fallback) set -g allow-rename off set -g automatic-rename on set -g automatic-rename-format '#{?#{!=:#{@claude_session_name},},claude[#{@claude_session_name}],#{?#{==:#{@last_cmd},},#{pane_current_command},#{@last_cmd}}}'
| C-ar | reload config inside running tmux |
scripts/test-helpers.sh | smoke-tests for status helpers |
scripts/test-tmux-window-label.zsh | window-label extraction tests (mirror of _tmux_window_label in .zshrc) |
scripts/test-claude-tmux-window-name.zsh | tests for the claude[<name>] window-title helper |
scripts/test-tmux-ssh-indicator.sh | SSH-indicator tests (mocks tmux+ps via PATH shim, asserts globe glyph emission) |