Tmux Observer Friendly

Tmux Observer Friendly

[Created by Codex: 019b82d6-67dd-7010-a99f-522999f29f85]

Overview

Create and restart tmux sessions without kicking already-attached observers by never killing the tmux session; instead, replace panes and clean up windows until the session has exactly one window and one pane.

Definition: Observer-Friendly Tmux

• Preserve any existing tmux attach -t <session> connections by never running tmux kill-session for the target session.
• Restart the running workload by creating a fresh pane and force-killing old panes (not the session).
• Converge to exactly 1 session, 1 window, and 1 pane for deterministic observer UX.
• Leave all other tmux sessions untouched.

Workflow (Idempotent Convergence)

1. Decide session_name, directory, and what command should run in the session.
2. If the session does not exist, create it detached.
3. If the session exists:
   • Keep one window; kill all other windows in the session.
   • Create a fresh pane in the kept window.
   • Kill all old panes (force-terminates any running processes).
4. Ensure exactly one remaining pane, then send the command to that pane.

Script

Run the bundled script for deterministic session management:

• scripts/setup_hermione_session.py (sample implementation)

Default Behavior (Claude Code Resume)

Send cd <folder> && cc --resume <session_id> to the session's remaining pane.

python scripts/setup_hermione_session.py \
  --name Hermione --folder ~/TheSwarm/Armada --session ba73acbe-6a42-4317-a634-33948601db8d

Custom Command

Override the default resume command with --command.

python scripts/setup_hermione_session.py --name MySess --folder ~/myproj --command "python main.py"

Guardrails

• Avoid tmux kill-session -t <session> when observers are attached.
• Avoid tmux kill-server and tmux detach-client -a for observer-friendly workflows.
• Prefer pane/window operations (kill-pane, kill-window) scoped to the target session.

Local Reference

If additional background is required, load: ~/KnowledgeBase/startup/TMUX_SESSION_GUIDE.md.