Tmux

How to create custom key tables in tmux?

Quick Answer

Create custom key tables to group related commands: bind-key -T mytable h previous-window, then access with bind-key Space switch-client -T mytable. This creates temporary command modes, similar to vim.

bind-key Space switch-client -T window-ops

Detailed Explanation

Key tables let you create custom "modes" in tmux, similar to vim's command modes. You can group related commands under a single key, then use that key to access a temporary command mode where each key performs a specific function.

Creating a Simple Key Table

# Define a window management table
bind-key -T window-ops n new-window
bind-key -T window-ops h previous-window
bind-key -T window-ops l next-window
bind-key -T window-ops r rename-window
bind-key -T window-ops q switch-client -T root  # Return to normal

# Access the table with Ctrl+b w
bind-key w switch-client -T window-ops

Practical Example: Resize Mode

Create a resize mode that lets you repeatedly resize panes without pressing the prefix key:

# Define resize table that stays active after each command
bind-key -T resize-mode h resize-pane -L 2 \; switch-client -T resize-mode
bind-key -T resize-mode j resize-pane -D 1 \; switch-client -T resize-mode
bind-key -T resize-mode k resize-pane -U 1 \; switch-client -T resize-mode
bind-key -T resize-mode l resize-pane -R 2 \; switch-client -T resize-mode
bind-key -T resize-mode q switch-client -T root

# Enter resize mode with Ctrl+b r
bind-key r switch-client -T resize-mode

Built-in Key Tables

root: Normal key bindings (default mode)
prefix: Active after pressing the prefix key
copy-mode: When in copy mode
copy-mode-vi: Vi-style copy mode bindings

Visual Feedback

Show the current key table in your status bar:

# Show current table in status bar
set-option -g status-right '#{?client_key_table,[#{client_key_table}],} %H:%M'

# Display message when entering modes
bind-key w switch-client -T window-ops \; display "Window mode"
bind-key r switch-client -T resize-mode \; display "Resize mode"

Pro Tip

Always include a q key in your custom tables that returns to the root table: bind-key -T mytable q switch-client -T root. This gives you an easy escape route.

Complete Example

A practical window and pane management setup:

# Window operations (Ctrl+b w)
bind-key -T window-ops n new-window \; switch-client -T root
bind-key -T window-ops h previous-window \; switch-client -T window-ops  
bind-key -T window-ops l next-window \; switch-client -T window-ops
bind-key -T window-ops r rename-window \; switch-client -T root
bind-key -T window-ops q switch-client -T root
bind-key w switch-client -T window-ops \; display "Window mode"

# Show mode in status
set-option -g status-right '#{?client_key_table,[#{client_key_table}] ,}%H:%M'

Use Cases

Grouped operations: Window management, pane operations, session control
Repeating actions: Resize mode, navigation mode
Application launchers: Quick access to common programs
Learning tool: Organize commands by function

←Back to FAQ Index