# Tmux Claude Session Spawner

> This skill should be used when spawning and managing tmux sessions running Claude Code (cc), reliably detecting Claude session IDs and renaming sessions to tmux-sdk-{uuid7}-sid-{sid}-pid-{pid} without exceeding macOS terminal limits.

- Skill: `tankygranny05/tmux-claude-session-spawner` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tankygranny05/tmux-claude-session-spawner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tankygranny05/tmux-claude-session-spawner/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-claude-session-spawner

---


# Tmux Claude Session Spawner
*[Created by Codex: 019b995e-bfff-7a70-866a-8f1846d53bbd]*

## Purpose

Spawn tmux sessions that run Claude Code via the `cc` alias, then reliably rename those tmux sessions to include both the Claude session ID (`sid`) and process ID (`pid`).

## Use Cases

- Spawn many Claude Code instances in tmux for parallel work.
- Rename sessions deterministically so tools/agents can map `uuid7 → sid → pid`.
- Avoid macOS “terminal device” exhaustion by batching and cleaning up.

## Naming Convention (Required)

Use:

- Initial name: `tmux-sdk-{uuid7}`
- Final name: `tmux-sdk-{uuid7}-sid-{sid}-pid-{pid}`

Example:

- `tmux-sdk-019b99a3-35df-75df-868e-2c28ec5b7b2f-sid-07d2ee46-0624-4dd5-a979-e3838d4a7437-pid-46444`

## Workflow

### 1) Spawn (Prefer Batching)

- Start each session with `zsh` so `cc` (a `~/.zshrc` alias) resolves correctly.
- Space spawns by ~1s to reduce startup contention.
- Cap concurrent sessions to ≤10 (batching) to avoid terminal device limits.

### 2) Run Claude Code with Isolated Logs

Always pass a dedicated log dir to avoid contaminating production logs:

- `cc --log-dir /tmp/agent-{suffix5}-harness`

Derive `suffix5` from the current agent id (last 5 characters) when available.

### 3) Detect `sid` + `pid` and Rename (Retry Loop)

- Resize the tmux window to prevent UI wrapping before capture.
- Capture the last ~80 lines of the pane and find the status footer:
  - Locate the last divider line (mostly box-drawing characters).
  - Extract a UUID4 followed by `|` from the lines immediately below the divider (handle wrapped `|` on the next line).
  - Validate it is a Claude session UI by requiring `bypass permissions` below the UUID.
- Determine `pid` by:
  - Getting `#{pane_pid}`
  - Selecting the best-matching child process (prefer command lines containing `cli.js` / `symlinks/claude`)
- Rename using `tmux rename-session` (safe; does not detach observers).
- Expect rounds where `renamed 0` occurs; continue retries until all sessions are renamed or the retry budget expires.

## Scripts (Bundled)

Run the deterministic scripts in this skill when automation is needed:

- Spawn + detect + rename (batched, ≤10 alive by default):
  - `python ~/.codex/skills/tmux-claude-session-spawner/scripts/spawn_and_rename.py --count 20`
- Cleanup by prefix (dry-run by default):
  - `python ~/.codex/skills/tmux-claude-session-spawner/scripts/cleanup_sessions.py --prefix tmux-sdk-`

## Troubleshooting

- If rename success drops under heavy load, increase:
  - `--post-spawn-wait` (allow TUI footer to render)
  - `--max-rounds` and/or `--poll-interval` (increase total retry window)
  - `--spawn-interval` (reduce contention)
- If `sid` detection fails intermittently, ensure the capture is wide enough (resize to 200 columns).
  - Avoid “too early” detection; prefer “eventually consistent” retry loops.
  - Treat intermediate `renamed 0` rounds as normal.