# Tmux Observer Friendly

> This skill should be used when creating or restarting tmux sessions in an observer-friendly way (preserve attached observers by not killing the session), while force-replacing panes/processes and converging to exactly 1 session, 1 window, and 1 pane without affecting other sessions.

- Skill: `tankygranny05/tmux-observer-friendly` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tankygranny05/tmux-observer-friendly`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/tmux-observer-friendly/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tankygranny05 (https://skillmd.com/u/tankygranny05)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tankygranny05/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.

```bash
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`.

```bash
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`.