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.