Conclusion: A native multiplexer with tmux's key tables, configured by ~/.tai/mplex.toml

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	shell-multiplexer-auto-attach
Document type	Conclusion
Tier	N/A
Date decided	2026-10-12
Decided by	retoor, advised by tai (agent, Claude Sonnet 5)
Status	Active
Confidence	Medium

Question / problem statement

The native wrapper that had been built (NativePlexerBackend) was a single-pty byte relay with one shortcut (Ctrl+A q, kill). retoor asked for the multiplexer to have exactly the same features as tmux regarding shortcuts, with the main key and the others switchable through a config file, ~/.tai/mplex.toml. Shortcuts like split, windows, detach and copy mode need panes, windows, a screen model, a persistent server and a client, so the question was how to get there and what to match.

Conclusion

Keep the multiplexer native and make it a real tmux-shaped system: one detached server process per TAI_HOME owning every pty, window layout, scrollback and session; thin clients that attach over a Unix socket and receive finished frames. Key tables, command names, command flags and option names follow tmux 3.6, taken from the installed binary's own dumps rather than from memory, and are embedded as data. The default prefix is C-b, as in tmux. ~/.tai/mplex.toml (TOML, because it is stdlib on Python 3.11+ and unambiguous) holds [options] and [keys.<table>]; bad entries are skipped loudly, counted, announced on the status line and listed by show-messages. Not implemented, and refused with a clear message instead of silently ignored: mouse, display-menu, customize-mode, display-popup, hooks, pipe-pane, join-pane/move-pane, link-window, respawn-*, wait-for, lock commands.

Supporting sources

local-tmux-3-6-keybinding-and-option-dumps.md: the exact default tables, notes, options and command list that were embedded.
man7-tmux-manual.md, tao-of-tmux-server-internals.md: the client/server split and the command model that were copied structurally.
stalkr-remote-tty-resize-design.md, systemd-ptyfwd-resize-forwarding.md, lkml-2003-sigwinch-foreground-process-group.md: resize forwarding and pty handling that the server now does itself.

Alternatives considered and rejected

Build on tmux as a substrate (the recommendation of multiplexer-proposal-design-basis.md). Not taken for the multiplexer itself: the request was for tai's own multiplexer with its own config file and key semantics, and it keeps tai a single stdlib-only file with no external binary. The tmux backend remains for terminals already inside tmux (TmuxPlexerController).
Keep the transparent relay and add a few shortcuts. Rejected: windows, panes, scrollback and detach all need a screen model and a persistent owner of the ptys.
Reproduce tmux's key tables from memory. Rejected after the installed binary turned out to be available; memory would have missed details (the repeat flags, the copy-mode tables, the notes).
Support tmux.conf syntax as the config. Rejected: the request was explicitly for a similar but differently named file, and TOML gives validation errors with a location.

Risks / open questions

Behavior was compared with tmux 3.6 for layouts, windows and copy mode (see mplex.md, "Checked against tmux 3.6"); the listed remaining differences (wrapped lines, bracket fallback, mouse) are open.
No reflow on resize and wide characters count as one column (limits of TuiVtScreen).
The server is a long-lived background process; a crash loses every pane. Mitigation so far: one broad handler around command execution and the control socket, tracebacks in plexer/server.log.
Revisit if tmux changes its default tables, or if mouse support is requested.

Action taken

Implemented in tai.py (the Mplex* classes, MplexCli, NativePlexerBackend as a thin attach), documented in mplex.md, covered by unit tests in test_tai.py and integration tests in tests/mplex.py and tests/plexer.py.

Changelog

Date	Change
2026-10-12	Initial conclusion recorded.
2026-10-12	Risks corrected after the tmux comparison runs: layouts, window ordering and copy mode were compared command by command, and several defaults (window height for detached sessions, remainder cell placement, selection rules, search placement) were changed to match.

4.4 KiB Raw Permalink Blame History