One tmux Window per Agent: The Setup

The anodised aluminium KM16 Macropad carries sixteen keycaps and three knobs: one large and two small. Its VIA-remappable outputs can select tmux windows without putting agent approval actions on hardware.

Why use one window per agent instead of split panes?

A tmux window normally fills the attached terminal, while panes divide one window into smaller terminals. Giving each agent a window preserves width for diffs, logs and prompts. It also reduces the chance of typing into a neighboring pane after a small focus movement.

Panes remain useful for a log or test watcher paired with one agent. The rule is not absolute. Use a window as the unit of attention and add a pane only when both processes belong to the same task.

How do you name and index the windows?

tmux gives every session a numbered window list and lets you rename the current window. Use short task names such as auth, tests or docs, then keep a written map from index to task. Names do not have to be unique, so the index and session together remain the reliable target.

New windows fill the first available gap. If fixed numbers drive physical controls, avoid deleting a middle window or renumber deliberately after closing work. Confirm the status line before trusting a label copied from yesterday.

How do you jump to an agent with one press?

Make a pad position emit a spare function key in VIA, then bind that key in tmux's root key table to select one explicit window. A root-table binding avoids timing a hardware macro that sends the tmux prefix followed by a digit. Test F13 with one window before adding more.

Keep navigation separate from text. A key should only select a window, not type an answer, press Enter or accept a change. The newly visible agent prompt then receives a deliberate keyboard response.

How do you see which window needs attention?

tmux supports activity and bell monitoring, and its status formats can show flags for windows outside view. Configure a restrained indicator and test it with harmless output. Constant logs can create permanent activity, so monitor only panes whose silence and output mean something.

The KM16 Macropad offers more positions than most people can supervise. Begin with three agent windows and one last-window key. Label tasks, not personalities, and remove a binding when its window closes so an old key cannot select unrelated work. Keep a plain tmux tree-view key as a fallback. When a physical label and the status line disagree, trust the live tmux window list and correct the label before continuing.