# Tmux Claude Sdk

> This skill should be used when controlling Claude Code sessions via tmux (spawn, detect sid/pid, rename, send prompts, Ctrl-C clear, Esc abort, Esc Esc rewind, Ctrl-C Ctrl-C exit) while preserving observability via --log-dir sse_lines.jsonl.

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

---


# 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
```