Conclusion: Build on tmux, Never Guess at "Is This a Human" Alone

Metadata

Field	Value
Institute	Molodetz Institute — Research & Retrieval Division
Subject	shell-multiplexer-auto-attach
Document type	Conclusion
Tier	N/A
Date decided	2026-10-09
Decided by	retoor, advised by tai (agent, Claude Sonnet 5)
Status	Active for the tmux-backed controller and the shell-detection rules; the rejection of a from-scratch multiplexer was reversed for the native backend by tmux-parity-native-multiplexer.md (2026-10-12)
Confidence	High

Question / problem statement

retoor asked for a tai-managed terminal multiplexer, auto-attached transparently whenever a real interactive bash shell starts — but explicitly not when bash is invoked by automation, scripts, or tools (including tai/Claude Code's own shell tool) that happen to also source .bashrc — supporting resize, sound/bell passthrough, events, raw keystroke handling, a named-socket or fd-based control channel, programmatic commands (read pane content, grep it, write/type at a position, animated typing), and continuous full-session logging. Deep research was explicitly requested before any implementation.

Conclusion

Build this as a thin control layer on top of tmux, not as a new PTY multiplexer kernel. tmux already provides, battle-tested, exactly the substrate this proposal needs: a client-server architecture over a configurable Unix socket (-L/-S), persistent sessions that survive disconnects, native SIGWINCH/resize handling, bell passthrough, hooks, a human-typing interface (send-keys/capture-pane), a structured scripting interface (control mode, -CC), and a continuous-logging primitive (pipe-pane) that directly satisfies "remember the whole process log." tai (per its own root README.md) already optionally depends on tmux and already shells out to tmux capture-pane rather than reimplementing terminal capture — this proposal is a natural extension of that existing posture, not a new direction.

The one genuinely hard, unsolved-by-tooling part of the request is reliably distinguishing a human-opened interactive shell from bash being invoked by a script, IDE, or AI coding agent sourcing the same .bashrc. This research found it is a recognized, actively-discussed, unsolved-in-general problem (VS Code's own agent-terminal issues, security detection-rule false-positive guidance, dedicated "AI agent terminal detection" posts) with no single reliable signal — only a combination of weaker ones ($- containing i, $TMUX unset, $SSH_TTY/$SSH_CONNECTION, parent process name, an agent-identifying env var), each individually defeatable in one direction or the other.

Supporting sources

../man7-tmux-manual.md, ../tao-of-tmux-server-internals.md, ../github-tmux-discussion-3567-no-raw-socket-api.md — tmux's client-server/socket architecture and the hard boundary of what's scriptable (commands + control mode, no raw socket protocol).
../tmuxai-dev-control-mode.md, ../github-tmux-discussion-4016-control-mode-output.md, ../github-tmux-wiki-control-mode.md, ../libtmux-pane-interaction.md, ../tmuxai-dev-faq.md — the concrete mechanisms (-CC framing, send-keys/capture-pane loop, pipe-pane streaming) the control layer is built from.
../android-adb-cfmakeraw-commit.md, ../stalkr-remote-tty-resize-design.md, ../systemd-ptyfwd-resize-forwarding.md, ../coral-mdt-console-sigwinch-commit.md, ../lkml-2003-sigwinch-foreground-process-group.md — what would have to be hand-built (raw termios mode, SIGWINCH handling, resize-over-socket forwarding) if tmux were not used; the cost this recommendation avoids entirely, since tmux already does all of it internally.
../bash-manual-interactive-shell-definition.md, ../cyberciti-nixcraft-dollar-dash-test.md, ../oreilly-bash-cookbook-interactive-test.md, ../pythontutorials-net-ps1-child-process-caveat.md, ../gitlab-mr-3383-stdin-stdout-isatty-mismatch.md, ../lkml-mailing-list-tty-s-insufficient.md — why $- is the right first-line interactivity check, and why isatty/PS1-alone checks fail in documented, specific ways.
../elastic-detection-rule-interactive-terminal-python.md, ../panoramicdata-detecting-ai-agent-terminals.md, ../github-vscode-community-discussion-161238.md, ../github-vscode-issue-253265.md, ../github-fak-issue-11425-pty-interactive-prompt-detection.md — independent, cross-domain confirmation that human-vs-automation terminal detection is a recognized hard problem with no single reliable signal, only combined weaker ones plus explicit allowlisting by known tool identity.
../bbs-archlinux-tmux-env-guard.md, ../codegenes-net-ssh-tty-tmux-guard.md, ../unix-stackexchange-ssh-tmux-nesting.md, ../santini-tmux-safety-file.md — the concrete guard conditions ($TMUX, $SSH_TTY/$SSH_CONNECTION) and, critically, the mandatory safety-file bypass pattern for when the auto-attach logic itself is wrong.
../dasroot-net-tmux-vs-zellij.md, ../theregister-tiling-multiplexer-survey.md — why tmux specifically, not Zellij, fits this proposal's scripting-and-SSH-heavy requirements.
../github-bitcanon-autotyper.md, ../nncron-send-keys-delay-docs.md, ../tabby-typewriter-mode-docs.md, ../raycast-fake-typing-effect.md, ../k6-browser-presssequentially.md — the basis for a typing-animation command syntax (per-character delay, inline pause/speed tokens, optional randomization).

Alternatives considered and rejected

A from-scratch terminal multiplexer (raw termios mode, SIGWINCH handling, a hand-rolled Unix-socket IPC protocol, session persistence, all built independently). Rejected: this re-solves a problem tmux has already solved, for a project whose own stated design philosophy (root README.md) is dependency-light and pragmatic, and which already optionally depends on tmux and already shells out to it for capture rather than reimplementing. The "research is done, confidence high" status above specifically reflects how thoroughly this exact problem surface (raw mode, resize forwarding, socket IPC) turned out to already be solved, documented, and battle-tested elsewhere.
Zellij as the substrate instead of tmux. Considered, not dismissed out of hand — but tmux fits better given tai already optionally depends on it, and the research (dasroot-net-tmux-vs-zellij.md) found tmux specifically stronger for scripting and SSH/remote use, which is the actual requirement here; Zellij's documented strength is a discoverable interactive UI, not a scripting substrate.
A single boolean "is this shell interactive" check as the sole auto-attach gate. Rejected: both the bash-detection dossiers and the automation-false-positive dossiers in this subject independently show this fails in both directions (automation tools that pass isatty()/$- checks; genuinely interactive shells an over-narrow check might miss).

Risks / open questions

Unconditionally auto-wrapping every bash session from .bashrc is a high-blast-radius, hard-to-reverse-if-wrong system change: it can break automation, CI, IDE-integrated terminals, and — if misdetected — the agent's own shell tool (the exact tool this research is being conducted through). This was explicitly not implemented as part of this research task; it is proposed, pending the human's explicit review and confirmation of the exact activation condition and the mandatory safety-bypass mechanism (per santini-tmux-safety-file.md) before any .bashrc on a real machine is touched.

Action taken

None yet. This was a research-and-proposal task; implementation is explicitly deferred pending retoor's review of the proposal presented alongside this archive.

Changelog

Date	Change
2026-10-09	Initial conclusion recorded.
2026-10-12	Status note: the "from-scratch multiplexer" alternative was rejected here, then taken for the native backend on explicit request; see `tmux-parity-native-multiplexer.md`. The detection rules and the tmux controller remain in force.

8.0 KiB Raw Blame History