Learn Tmux - Custom Keybindings, Command Mode & Menus

#Introduction

In episode 10 we mastered format strings — the ability to read and display information from tmux. In this episode we flip the direction: learning to command tmux. Two ways to do it: binding commands to keys with bind-key, and typing commands directly through the command prompt. We'll also build modern interfaces with display-menu and display-popup — two features that turn tmux from a mere multiplexer into an in-terminal application launcher.

Why does this matter? tmux's default keybindings only provide generic actions. Your real workflow — "open the api project", "run the tests", "look at git log" — isn't in the defaults. Custom keybindings and menus are how you carve tmux to fit your habits. Skilled engineers build a personal key "dashboard" so the most frequent actions run in one or two keystrokes, without touching the mouse.

#bind-key and unbind-key Syntax

The core command is bind-key (alias bind). Its basic form: bind <tombol> <command> — in the config or command prompt, command is written without the tmux prefix.

bind R source-file ~/.tmux.conf
bind S choose-tree -Zs
bind -n F12 detach

• The first line binds prefix + R to reload the config (uppercase is used so it doesn't collide with the default prefix + r rename).
• The second line binds prefix + S to open the session picker.
• The third line uses the -n (no-prefix) flag: F12 works directly without a prefix.

#Unbind to Avoid Conflicts

Before binding a key, first release the default binding with unbind-key (alias unbind). This is important because two keybindings can't both be active on the same key.

unbind C-b
set -g prefix C-a
bind C-a send-prefix

This block is the classic way to change the prefix from Ctrl+B to Ctrl+A. The reading order: unbind Ctrl+B, set the new prefix, then bind Ctrl+A to send the prefix (so the send-prefix command remains accessible when nested).

#Important bind-key Flags

#Command Prompt and Command Chaining

#Command Prompt

prefix + : opens the command prompt at the bottom of the screen — where you type any tmux command directly. This is tmux's "REPL": every command in tmux list-commands can be run from here without writing in the shell.

new-window -c ~/project/api -n editor
display-message "selamat datang di #{session_name}"
set-environment -g DEPLOY_TARGET staging

The command prompt is the bridge between config and live interaction: you can test commands here before writing them into ~/.tmux.conf.

#Command Chaining

Several commands can be chained on one line with a semicolon ;. This lets one keybinding do many things at once.

bind T split-window -h \; send-keys 'htop' Enter
bind P new-window -n logs \; send-keys 'journalctl -f' Enter
bind R source-file ~/.tmux.conf \; display-message "Config reloaded"

First line: prefix + T opens a new pane on the right then immediately runs htop. Second line: prefix + P opens a logs window and immediately shows system logs. Note how \; is written in the config — the semicolon must be escaped so it isn't treated as a config line separator.

#display-menu: Modern Menus

The display-menu feature (tmux 3.3+) lets you build interactive menus in the middle of the screen — like a context menu, fully keyboard-driven. This is the most elegant way to group many actions.

bind m display-menu -T "Dev Menu" \
    "▶ Editor" E "send-keys 'nvim' Enter" \
    "▶ Server" S "send-keys 'npm run dev' Enter" \
    "▶ Git Log" L "display-popup -E 'git log --oneline'" \
    "" \
    "⏻ Kill Pane" k "kill-pane"

The result: prefix + m opens a menu with four entries. Each line consists of three parts: label, shortcut key, and the command run when selected. You can navigate with arrows and Enter, or press the shortcut letter directly.

#display-popup: Terminal Popups

display-popup (tmux 3.3+, popup rendered on top of the layout) opens a small window floating above the panes — perfect for running commands that need context but without leaving the main pane. This feature evolved significantly in tmux 3.7 (floating panes fully interactive).

bind g display-popup -E -w 80% -h 60% 'git log --oneline --graph --decorate'
bind f display-popup -E "find . -name '*.ts' | fzf"
bind a display-popup -E "nvim -c 'lua require(\"telescope\").extensions.git.branches()'"

• bind g — opens a git log popup in the middle of the screen (80% wide, 60% high).
• bind f — fuzzy file finder in a popup.
• bind a — opens an editor in a popup.

The -E flag closes the popup automatically after the command finishes; -w/-h set the size. Popups are great for "quick glances" that don't disturb the main pane's workflow.

#command-prompt: Dynamic Input

Sometimes you need a value from the user when a keybinding runs. command-prompt shows an input prompt and forwards the result to a command.

bind r command-prompt -p "Rename window: " {rename-window '%%'}
bind s command-prompt -I "#{pane_current_path}" -p "New window in: " {new-window -c '%%'}

• bind r — asks for a new name then renames the window.
• bind s — asks for a path (with the initial value from the current pane path) then creates a window in that path.

The '%%' notation is the placeholder for the user-provided input — the prompt result is inserted at that position.

#Putting It All Together: A Personal Launchpad

Here's a config example combining all of this episode's techniques into a development workflow "launchpad":

# ===== PREFIX =====
set -g prefix C-a
unbind C-b
bind C-a send-prefix
 
# ===== RELOAD =====
bind R source-file ~/.tmux.conf \; display-message "Config reloaded"
 
# ===== LAUNCHER =====
bind m display-menu -T "Launchpad" \
    "▶ Editor" e "send-keys 'nvim' Enter" \
    "▶ Dev Server" s "send-keys 'npm run dev' Enter" \
    "▶ Git Log" l "display-popup -E 'git log --oneline --graph'" \
    "" \
    "⏻ Kill Pane" k "kill-pane"
 
# ===== POPUP =====
bind g display-popup -E -w 80% -h 60% 'git log --oneline --graph --decorate'
bind f display-popup -E "find . -name '*.ts' | fzf"
 
# ===== PROMPT =====
bind r command-prompt -p "Rename window: " {rename-window '%%'}

Reload with prefix + R, then test prefix + m, prefix + g, prefix + r. This is just an example — the principle is: repeat frequent actions, group the rare ones, and let prompts handle what needs input.

#Common Pitfalls

1. Keybinding conflicts left unchecked. After changing a bind, check tmux list-keys or prefix + ? to make sure nothing collides. Unbind first before rebinding.

2. Semicolons not escaped in the config. In ~/.tmux.conf, chained commands must be written with \; — without the escape, the semicolon is treated as the end of a config line.

3. Forgetting -n places the keybinding in the root table. -n keybindings can collide with keys used by programs inside the pane (e.g. F1 in an editor). Use them deliberately.

4. Wrong prompt placeholder. Use '%%' inside command-prompt curly braces, not %1.

5. Popup closing too fast. Without -E, the popup waits; with -E, the popup closes when the command finishes. Choose per need — for interactive editors don't use -E.

6. Too many custom keybindings. Every new bind is a memory burden. Keep the count reasonable and put rare actions in menus/popups.

#Conclusion

This episode gave you full control over tmux commands: bind-key/unbind-key with the -n/-r/-T flags, the prefix + : command prompt for testing commands, command chaining with ;, interactive display-menu menus, display-popup terminal popups, and command-prompt dynamic input.

Key points to take away:

• bind-key is the main way to carve tmux to fit your workflow.
• Unbind before rebinding to avoid conflicts.
• display-menu and display-popup are tmux 3.3+'s modern interfaces.
• The command prompt is where you test commands before they enter the config.
• '%%' is the input placeholder for command-prompt.

All the keybindings we just built will live in ~/.tmux.conf — and that file is what governs tmux's behavior from the moment the first server starts. In episode 12 we dissect options & environment management — the four scopes of options, important options like history-limit and escape-time, and consistent environment and working directory management. See you in episode 12!