tmux

name	tmux
description	Complete tmux terminal multiplexer management: sessions, windows, panes, layouts, scripting, and configuration. Auto-activates on: "tmux", "session", "window", "pane", "split", "attach", "detach", "multiplexer".
license	MIT
compatibility	Requires tmux (3.0+). Works on Linux/macOS/WSL.
metadata	{"version":"1.0"}
allowed-tools	Bash Read Edit Write Glob Grep

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-panes
• tmux info, show-options, display-message
• tmux list-keys, list-buffers

Requires confirmation:

• kill-session, kill-window, kill-pane
• kill-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