Putting tmux Keybindings on a Macropad

KM16 Macropad combines sixteen keycaps with an anodised aluminium body and three knobs. VIA can make its keys emit spare function codes that tmux turns into direct navigation bindings.

How can one key replace a tmux prefix sequence?

A hardware macro could emit the prefix and a command key, but timing and terminal handling make that sequence fragile. A cleaner design gives the pad an uncommon output such as F13 and adds a tmux root-table binding with no prefix. tmux then receives one key and runs one named command.

Keep the operating-system and tmux layers documented separately. Verify F13 in the terminal first, then bind it to a harmless action such as selecting the last window.

Which tmux actions deserve physical keys?

Select window, last window, next window, previous window, choose tree and copy mode are visible and reversible. Zoom can be useful when a window contains several panes. Start with navigation that changes what you see rather than what a program receives.

Do not bind kill-pane, kill-session, detach-all, send-keys or a literal Enter during the first setup. Those actions either alter state or affect a program that may not be visible.

Should you use send-keys or direct commands?

Use direct tmux commands for tmux behavior. The send-keys command sends input into a pane as if it were typed, which is appropriate only when the program should receive the key. Selecting window two is a tmux command, so it should not be simulated through pane input.

Reload the configuration with source-file and inspect current bindings before testing. tmux reads its default configuration when the server starts, not whenever a new session appears, so an edited file may not affect an existing server until sourced.

What changes inside nested tmux sessions?

An inner and outer tmux can both claim the same prefix or root binding. The outer server sees the terminal input first. Use different prefixes or reserve macropad root keys for only one layer, and display the active session name prominently.

The KM16 Macropad has enough controls to make nested mappings confusing quickly. Begin with four navigation keys, keep a normal prefix route and test after starting a fresh server. A physical label should name the tmux action and its intended server. Use tmux's binding-list command to confirm the root key is not already assigned. If a collision exists, choose another spare output rather than silently replacing a binding you still need. Store the added tmux lines together and comment each with its physical pad position. Retest that list after every tmux upgrade.