tmux

What this skill does

# tmux Skill

Use tmux as a programmable terminal multiplexer for interactive work. Works on Linux and macOS with stock tmux; avoid custom config by using a private socket.

## Quickstart

The session registry eliminates repetitive socket/target specification through automatic session tracking (~80% reduction in boilerplate):

**IMPORTANT**: Before creating a new session, ALWAYS check existing sessions first to avoid name conflicts:

```bash
# Check existing sessions to ensure name is available
./tools/list-sessions.sh

# Create and register a Python REPL session (choose a unique name)
./tools/create-session.sh -n claude-python --python

# Send commands using session name (auto-lookup socket/target)
./tools/safe-send.sh -s claude-python -c "print(2+2)" -w ">>>"

# Or with a single session, omit -s entirely (auto-detect)
./tools/safe-send.sh -c "print('hello world')" -w ">>>"

# List all registered sessions with health status
./tools/list-sessions.sh

# Clean up dead sessions
./tools/cleanup-sessions.sh
```

After starting a session, ALWAYS tell the user how to monitor it by giving them a command to copy/paste (substitute actual values from the session you created):

```
To monitor this session yourself:
  ./tools/list-sessions.sh

Or attach directly:
  tmux -S <socket> attach -t <session-name>

Or to capture the output once:
  tmux -S <socket> capture-pane -p -J -t <session-name>:0.0 -S -200
```

This must ALWAYS be printed right after a session was started (i.e. right before you start using the session) and once again at the end of the tool loop. But the earlier you send it, the happier the user will be.

## How It Works

The session registry provides three ways to reference sessions:

1. **By name** using `-s session-name` (looks up socket/target in registry)
2. **Auto-detect** when only one session exists (omit `-s`)
3. **Explicit** using `-S socket -t target` (backward compatible)

Tools automatically choose the right session using this priority order:
1. Explicit `-S` and `-t` flags (highest priority)
2. Session name `-s` flag (registry lookup)
3. Auto-detect single session (if only one exists)

**Benefits:**
- No more repeating `-S socket -t target` on every command
- Automatic session discovery
- Built-in health tracking
- Activity timestamps for cleanup decisions
- Fully backward compatible

## Common Workflows

For practical examples of managing tmux sessions through their lifecycle, see the [Session Lifecycle Guide](./references/session-lifecycle.md).

This guide covers:
- **Daily workflows**: Ephemeral sessions, long-running analysis, crash recovery, multi-session workspaces
- **Decision trees**: Create vs reuse, cleanup timing, error handling
- **Tool reference matrix**: Which tools to use at each lifecycle stage
- **Troubleshooting**: Quick fixes for common problems (session not found, commands not executing, cleanup issues)
- **Best practices**: 10 DO's and 10 DON'Ts with examples

## Finding sessions

List all registered sessions with health status:
```bash
./tools/list-sessions.sh           # Table format
./tools/list-sessions.sh --json    # JSON format
```

Output shows session name, socket, target, health status, PID, and creation time.

## Sending input safely

The `./tools/safe-send.sh` helper provides automatic retries, readiness checks, and optional prompt waiting:

```bash
# Using session name (looks up socket/target from registry)
./tools/safe-send.sh -s claude-python -c "print('hello')" -w ">>>"

# Auto-detect single session (omit -s)
./tools/safe-send.sh -c "print('world')" -w ">>>"

# Explicit socket/target (backward compatible)
./tools/safe-send.sh -S "$SOCKET" -t "$SESSION":0.0 -c "print('hello')" -w ">>>"
```

See the [Helper: safe-send.sh](#helper-safe-sendsh) section below for full documentation.

## Watching output

- Capture recent history (joined lines to avoid wrapping artifacts): `tmux -S "$SOCKET" capture-pane -p -J -t target -S -200`.
- For continuous monitoring, poll with the helper script (below) instead of `tmux wait-for` (which does not watch pane output).
- You can also temporarily attach to observe: `tmux -S "$SOCKET" attach -t "$SESSION"`; detach with `Ctrl+b d`.
- When giving instructions to a user, **explicitly print a copy/paste monitor command** alongside the action—don't assume they remembered the command.

## Spawning Processes

Some special rules for processes:

- when asked to debug, use lldb by default
- **CRITICAL**: When starting a Python interactive shell, **always** set the `PYTHON_BASIC_REPL=1` environment variable before launching Python. This is **essential** - the non-basic console (fancy REPL with syntax highlighting) interferes with send-keys and will cause commands to fail silently.
  ```bash
  # When using create-session.sh, this is automatic with --python flag
  ./tools/create-session.sh -n my-python --python
  
  # When creating manually:
  tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
  ```

## Synchronizing / waiting for prompts

Use timed polling to avoid races with interactive tools:

```bash
# Wait for Python prompt
./tools/wait-for-text.sh -s claude-python -p '^>>>' -T 15 -l 4000

# Auto-detect single session
./tools/wait-for-text.sh -p '^>>>' -T 15

# Explicit socket/target
./tools/wait-for-text.sh -S "$SOCKET" -t "$SESSION":0.0 -p '^>>>' -T 15 -l 4000
```

For long-running commands, poll for completion text (`"Type quit to exit"`, `"Program exited"`, etc.) before proceeding.

## Interactive tool recipes

- **Python REPL**: Use `./tools/create-session.sh -n my-python --python`; wait for `^>>>`; send code; interrupt with `C-c`. The `--python` flag automatically sets `PYTHON_BASIC_REPL=1`.
- **gdb**: Use `./tools/create-session.sh -n my-gdb --gdb`; disable paging with safe-send; break with `C-c`; issue `bt`, `info locals`, etc.; exit via `quit` then confirm `y`.
- **Interactive git** (`git add -p`, `git stash -p`, `git checkout -p`, `git reset -p`): Use `./tools/create-session.sh -n my-git --shell`; run the git command; wait for hunk prompt pattern `\?\s*$`; send single-letter responses (`y` stage, `n` skip, `s` split, `q` quit). Each response requires Enter.
- **Other TTY apps** (ipdb, psql, mysql, node, bash): Use `./tools/create-session.sh -n my-session --shell`; poll for prompt; send literal text and Enter.

## Cleanup

Killing sessions (recommended - removes both tmux session and registry entry):
```bash
# Kill a specific session by name
./tools/kill-session.sh -s session-name

# Auto-detect and kill single session
./tools/kill-session.sh

# Dry-run to see what would be killed
./tools/kill-session.sh -s session-name --dry-run
```

Registry cleanup (removes registry entries only, doesn't kill tmux sessions):
```bash
# Remove dead sessions from registry
./tools/cleanup-sessions.sh

# Remove sessions older than 1 hour
./tools/cleanup-sessions.sh --older-than 1h

# See what would be removed (dry-run)
./tools/cleanup-sessions.sh --dry-run
```

Manual cleanup (when not using registry):
- Kill a session when done: `tmux -S "$SOCKET" kill-session -t "$SESSION"`.
- Kill all sessions on a socket: `tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t`.
- Remove everything on the private socket: `tmux -S "$SOCKET" kill-server`.

## Helper: create-session.sh

`./tools/create-session.sh` creates and registers new tmux sessions with automatic registry integration.

**IMPORTANT**: Before creating a session, ALWAYS run `./tools/list-sessions.sh` to check for existing sessions and ensure your chosen name is unique.

```bash
./tools/create-session.sh -n <name> [--python|--gdb|--shell] [options]
```

**Key options:**
- `-n`/`--name` session name (required)
- `--python` launch Python REPL with PYTHON_BASIC_REPL=1
- `--gdb` launch gdb debugger
- `--shell` launch bash shell (default)
- `-S`/`--socket` custom socket path (optional, uses default)
- `-w`/`--window` window name (default: "shell")
- `--no-re