Tmux Keybindings

Cheat sheet for tmux, a terminal multiplexer.

Starting tmux

Start new session:

tmux new -s \<session name>

Attach a session

tmux attach -t \<session name>

List sessions

tmux ls

Emacs Style - Standard

Keys

Prefix key

Ctrl + b

Modifier Keys

Can be combined

1. Basic Session Management

Use these commands from your standard terminal to manage tmux sessions.

• tmux new -s <name> : Start a new session with a specific name.
• tmux ls : List all currently running tmux sessions.
• tmux attach -t <name> : Attach to an existing background session.
• tmux detach (or Prefix + d) : Detach from the current session (leaves it running in the background).
• tmux kill-session -t <name> : Shut down a specific session and close all its programs.
• tmux kill-server : Danger! Kills ALL running tmux sessions and the tmux server.

2. Window (Tab) Management

Windows in tmux act like tabs in a modern web browser.

• tmux new-window -n <name> : Create a new window and give it a name.
• tmux select-window -t <session>:<index> : Jump to a specific window by its index number (e.g., dev:2).
• tmux rename-window <new_name> : Rename the current window.
• tmux next-window / tmux previous-window : Cycle through open windows.

3. Splitting Panes (-h vs -v)

Tmux’s naming convention for splits refers to the direction of the dividing line, which can sometimes feel counter-intuitive.

• tmux split-window -h : Horizontal Split. Draws a horizontal dividing line, giving you a left and right pane (side-by-side).
• tmux split-window -v : Vertical Split. Draws a vertical dividing line, giving you a top and bottom pane (stacked).

Note: If no flag is provided, split-window defaults to a vertical (top/bottom) split.

4. Built-in Layouts

Tmux has five standard layouts that automatically arrange your current panes. You can apply them using tmux select-layout <layout_name>.

• even-horizontal : Spreads all panes out left-to-right, giving them equal width.
• even-vertical : Stacks all panes top-to-bottom, giving them equal height.
• main-horizontal : Creates one large “main” pane on top, and splits the remaining panes evenly left-to-right underneath it.
• main-vertical : Creates one large “main” pane on the left, and stacks the remaining panes evenly top-to-bottom on the right.
• tiled : Arranges all panes into a grid of equal size (e.g., 4 panes become a perfect 2x2 square).

5. Chaining Commands (\;)

Chaining tmux commands into a single line allows you to build complex environments instantly without writing a full bash script.

• The Problem: A standard semicolon (;) is interpreted by your shell (Bash/Zsh). The shell will launch tmux, wait for you to exit, and then try to run the next command, which will fail.
• The Solution: By escaping the semicolon as \;, you hide it from the shell. The entire string is passed directly into tmux, which reads the \; as its own internal separator and runs the commands sequentially.
• The Golden Rule: Always start chained commands by creating a detached session (new-session -d). If you don’t, tmux pulls you into the session immediately and halts the execution of the rest of your chain until you exit.

Sequential Example:

tmux new-session -d -s my-session ; split-window -v ; attach-session -t my-session

1. Tmux creates a detached session in the background.
2. Tmux reads \; and moves to the next command, splitting the window in the background.
3. Tmux reads \; and runs the final command, pulling your terminal view into the fully built session.

7. The Bash Script Method

For robust project setups, place this script (e.g., start-dev.sh) in your project root. It checks if the session exists first to prevent errors upon reconnection:

#!/bin/bash

# Automatically names the session after the folder you are in
SESSION_NAME=$(basename "$PWD")

tmux has-session -t "$SESSION_NAME" 2>/dev/null

if [ $? != 0 ]; then
  # Create detached session with first tab
  tmux new-session -d -s "$SESSION_NAME" -n "main"

  # Create second tab
  tmux new-window -t "$SESSION_NAME:2" -n "grid"

  # Split into 4 panes total
  tmux split-window -t "$SESSION_NAME:2"
  tmux split-window -t "$SESSION_NAME:2"
  tmux split-window -t "$SESSION_NAME:2"

  # Snap into 2x2 grid
  tmux select-layout -t "$SESSION_NAME:2" tiled

  # Focus back on the first tab
  tmux select-window -t "$SESSION_NAME:1"
fi

# Attach to the setup
tmux attach-session -t "$SESSION_NAME"