Tmux Claude SDK

[Created by Codex: 019b995e-bfff-7a70-866a-8f1846d53bbd]

Purpose

Drive Claude Code (cc) through tmux with a deterministic session naming scheme and verified control-key semantics.

Naming (Required)

•Initial: tmux-sdk-{uuid7}
•Final: tmux-sdk-{uuid7}-sid-{sid}-pid-{pid}

Example:

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

Core Capabilities

1) Spawn + Rename (sid/pid)

•Spawn a tmux session using zsh so cc alias resolves.
•Run cc --log-dir <dir> to isolate logs.
•Wait for the TUI footer and extract sid (UUID4 below divider; validate bypass permissions).
•Resolve the Claude process pid as the best-match child of #{pane_pid}.
•Rename using tmux rename-session (safe for observers).

2) Input + Control Keys

•Send prompt: type text + Enter (0d).
•Clear input (no Enter): Ctrl-C (03) clears the unsent input line.
•Abort generation: Esc (1b) shows “Interrupted”.
•Rewind menu: Esc Esc (1b, short gap, 1b) opens “Rewind”.
•Exit Claude: Ctrl-C Ctrl-C exits Claude to shell.

Bundled Code

This skill includes a self-contained Python library plus E2E tests:

•Library package: scripts/tmux_claude/
•E2E tests: scripts/tests/test_tmux_claude_e2e.py
•Runner: scripts/run_e2e_tests.py

Run E2E Tests

bash

cd /Users/sotola/.codex/skills/tmux-claude-sdk && \
  python scripts/run_e2e_tests.py

Keep tmux sessions (debug):

bash

cd /Users/sotola/.codex/skills/tmux-claude-sdk && \
  TMUX_CLAUDE_KEEP_SESSIONS=1 python scripts/run_e2e_tests.py

Use the Library

Import path note: the package lives in scripts/tmux_claude/. Run from scripts/ or add scripts/ to PYTHONPATH.

python

from tmux_claude import TmuxClaudeManager

mgr = TmuxClaudeManager(prefix="tmux-sdk")
sess = mgr.spawn(cwd="~/some/repo", log_dir="/tmp/agent-XXXXX-harness")
sess.send_prompt("Reply with: OK")
sess.escape()  # abort