tmux Skill

Use tmux as a programmable terminal multiplexer for interactive work.

Quickstart

Always pass -i ${CLAUDE_SESSION_ID} when starting sessions.

# Start a server for a purpose (returns JSON with socket/session/target/log)
${CLAUDE_SKILL_DIR}/scripts/start-session.sh -i ${CLAUDE_SESSION_ID} -s python
# {"socket": "claude/<id>/python", "session": "claude-python-<id>", "target": "...", "log": "..."}

# Send a command and wait for expected output
${CLAUDE_SKILL_DIR}/scripts/send-and-wait.sh -L $SOCKET -t $TARGET -c 'python -q' -p '>>>' -l

# Each purpose gets its own server
${CLAUDE_SKILL_DIR}/scripts/start-session.sh -i ${CLAUDE_SESSION_ID} -s gdb

A PostToolUse hook automatically shows the user the log path (and monitor command if --monitor was not used) after start-session.sh runs.

Pass --monitor to open an Alacritty window attached to the server. Use --monitor when the user asks to watch or says "show me". Do not use it by default.

Architecture

Each -s call creates an isolated tmux server via -L claude/<session-id>/<name>. Sockets are stored in tmux's default directory (usually /tmp/tmux-<uid>/).

• Pass --monitor to open an Alacritty monitoring window for the server
• Stopping a server closes its Alacritty window naturally
• All pane output is automatically logged to ${TMPDIR:-/tmp}/claude-tmux-logs/
• User can discover all sockets via find-sessions.sh

Scripts

Run with -h for help.

Sending commands

Prefer send-and-wait.sh — it sends the command and polls for expected output:

${CLAUDE_SKILL_DIR}/scripts/send-and-wait.sh -L $SOCKET -t $TARGET -c 'print("hello")' -p 'hello' -l

-l sends literally (avoids shell expansion). Omit for key sequences.

For commands with no predictable output, use raw send-keys + capture:

tmux -L $SOCKET send-keys -t $TARGET -l -- "$text"
tmux -L $SOCKET send-keys -t $TARGET Enter
tmux -L $SOCKET capture-pane -p -J -t $TARGET -S -200

Control keys (no -l):

tmux -L $SOCKET send-keys -t $TARGET C-c   # interrupt
tmux -L $SOCKET send-keys -t $TARGET C-d   # EOF

Testing tmux key bindings

send-keys writes bytes directly into the pane's PTY. The tmux prefix interception happens in the client layer (between the terminal and the server), so send-keys bypasses it entirely. Sending C-t via send-keys delivers the raw byte to the shell, not to the tmux binding system.

Consequence: key bindings cannot be triggered via send-keys. What can be tested:

• The bound commands work correctly — extract the command from the binding and run it directly against the server with tmux -L $SOCKET <command> -t $TARGET .... For example, if the binding runs select-layout even-horizontal, test it as:

  tmux -L $SOCKET select-layout -t $TARGET even-horizontal

• The binding is registered — query list-keys with the specific key. For example, to check key Space:

  tmux -L $SOCKET list-keys Space

What cannot be tested without a human at a real terminal: the full keystroke path (terminal → client intercepts prefix → dispatches binding → command runs).

Interactive tool recipes

• Python REPL:

  ${CLAUDE_SKILL_DIR}/scripts/send-and-wait.sh -L $SOCKET -t $TARGET -c 'PYTHON_BASIC_REPL=1 python -q' -p '>>>'
  ${CLAUDE_SKILL_DIR}/scripts/send-and-wait.sh -L $SOCKET -t $TARGET -c 'print(42)' -p '>>>' -l

• lldb/gdb: Disable paging with set pagination off, break with C-c

Cleanup

Kill your server when done. All pane output is preserved in the log file.

# Kill one server
${CLAUDE_SKILL_DIR}/scripts/stop-session.sh -i ${CLAUDE_SESSION_ID} -s python

# Kill all servers for this session
${CLAUDE_SKILL_DIR}/scripts/stop-session.sh -i ${CLAUDE_SESSION_ID}

Stop servers with stop-session.sh. Never run tmux kill-server without -L: that kills the user's own tmux server. The script also removes the claude/<id>/ socket entries.