Tmux config with Zellij-style shortcut hints bar - training wheels for tmux newcomers

.tmux.conf

# =============================================================================
# Tmux Training Wheels Configuration
# A Zellij-inspired shortcut hints bar for tmux newcomers
#
# Blog post: https://timvw.be/2026/02/12/tmux-training-wheels-a-zellij-inspired-shortcut-hints-bar/
# =============================================================================

# --- General settings ---
set -g mouse on                    # Enable mouse support (scroll, select, resize)
set -g history-limit 100000        # Generous scrollback buffer
set -g set-clipboard on            # Allow tmux to set the system clipboard
set -g renumber-windows on         # Renumber windows when one is closed

# Copy-mode: yank to system clipboard (macOS)
bind-key -T copy-mode-vi y send -X copy-pipe-and-cancel "pbcopy"

# --- Status bar ---
set -g status-left '#S '           # Show session name in the left status
set -g status-left-length 100

# --- Custom keybindings ---

# prefix + a: Create a new named session (prompts for name)
bind-key a command-prompt -p "New session name:" { new-session -d -s "%%" ; switch-client -t "%%" }

# prefix + h: Toggle the hints bar on/off
# Uses tmux conditional: if status == 2 (hints visible), collapse to single line.
# Otherwise, expand back to two lines (hints visible).
bind-key h if -F '#{==:#{status},2}' 'set -g status on' 'set -g status 2'

# =============================================================================
# Zellij-style shortcut hints bar
# =============================================================================
#
# HOW IT WORKS:
#   set -g status 2    enables a second status line below the default one.
#   status-format[1]   defines the content of that second line.
#
# COLOR CODING (inspired by Zellij):
#   Green   = Session operations  (detach, list, new, rename, prev, next)
#   Blue    = Window operations   (new, next, prev, list, rename)
#   Magenta = Pane operations     (vsplit, hsplit, zoom, kill, next, navigate)
#
# FORMAT PATTERN:
#   Each shortcut follows:  #[bg=<color>,fg=<text>] <key> #[bg=colour235,fg=white] <action>
#   This creates a "pill" effect where the key stands out against the description.
#
# SEPARATORS:
#   │  (Unicode box-drawing)  separates shortcuts within a category
#   ║  (Unicode double line)  separates categories
#
# BACKGROUND:
#   colour235 (dark grey) is used as the base background, giving the hints bar
#   its own visual identity separate from the main status line.
#
# =============================================================================

set -g status 2
set -g status-interval 1
set -g status-format[1] '#[bg=colour235,fg=white] #[fg=green,bold]SESSION #[bg=green,fg=black] ^b #[bg=colour235,fg=colour245]+ #[bg=green,fg=black] d #[bg=colour235,fg=white] Detach #[fg=colour240]│ #[bg=green,fg=black] s #[bg=colour235,fg=white] List #[fg=colour240]│ #[bg=green,fg=black] a #[bg=colour235,fg=white] New #[fg=colour240]│ #[bg=green,fg=black] $ #[bg=colour235,fg=white] Rename #[fg=colour240]│ #[bg=green,fg=black] ( #[bg=colour235,fg=white] Prev #[fg=colour240]│ #[bg=green,fg=black] ) #[bg=colour235,fg=white] Next #[fg=colour240]║ #[fg=blue,bold]WINDOW #[bg=blue,fg=white] ^b #[bg=colour235,fg=colour245]+ #[bg=blue,fg=white] c #[bg=colour235,fg=white] New #[fg=colour240]│ #[bg=blue,fg=white] n #[bg=colour235,fg=white] Next #[fg=colour240]│ #[bg=blue,fg=white] p #[bg=colour235,fg=white] Prev #[fg=colour240]│ #[bg=blue,fg=white] w #[bg=colour235,fg=white] List #[fg=colour240]│ #[bg=blue,fg=white] , #[bg=colour235,fg=white] Rename #[fg=colour240]║ #[fg=magenta,bold]PANE #[bg=magenta,fg=white] ^b #[bg=colour235,fg=colour245]+ #[bg=magenta,fg=white] %% #[bg=colour235,fg=white] VSplit #[fg=colour240]│ #[bg=magenta,fg=white] " #[bg=colour235,fg=white] HSplit #[fg=colour240]│ #[bg=magenta,fg=white] z #[bg=colour235,fg=white] Zoom #[fg=colour240]│ #[bg=magenta,fg=white] x #[bg=colour235,fg=white] Kill #[fg=colour240]│ #[bg=magenta,fg=white] o #[bg=colour235,fg=white] Next #[fg=colour240]│ #[bg=magenta,fg=white] ←↓↑→ #[bg=colour235,fg=white] Navigate'