Tmux

Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.

Security Scan

The skill is coherent with its stated purpose (remote-controlling tmux sessions); it contains only small metadata mismatches and some privacy risks inherent to capturing tmux panes, but nothing that indicates malicious intent.

Purpose & Capability

The name/description match the included scripts and instructions: everything is about controlling tmux, sending keystrokes, and scraping pane output. Minor inconsistency: the registry metadata listed no required binaries, but SKILL.md metadata and the scripts clearly require tmux on PATH.

Instruction Scope

Instructions are narrowly scoped to tmux operations (create sessions, send-keys, capture-pane, wait-for-text). They also include guidance to scan sockets under CLAWDBOT_TMUX_SOCKET_DIR and to capture pane history — which is expected for this skill but means the agent can read any terminal content accessible via those sockets (potentially exposing secrets). There are no network exfiltration endpoints or unrelated file reads in the instructions.

Install Mechanism

No install spec; this is instruction-only plus two small helper shell scripts. Nothing is downloaded or written by an installer.

Credentials

The skill requests no credentials and no config paths in the registry, but SKILL.md uses an environment variable (CLAWDBOT_TMUX_SOCKET_DIR) to locate sockets. That env var is reasonable for purpose but should have been declared. No secrets are requested by the skill itself.

Persistence & Privilege

always:false (no forced inclusion) and the skill does not attempt to modify other skills or system-wide agent settings.

Assessment

This skill does what it says: it controls tmux sessions and reads pane output. Before installing, verify you have tmux installed and review/confirm the two helper scripts (wait-for-text.sh and find-sessions.sh). Pay special attention to CLAWDBOT_TMUX_SOCKET_DIR: make sure the socket directory is private and that the agent should legitimately have access to the tmux sockets there — any tmux session accessible to that socket can be read and have keystrokes injected, which could expose sensitive terminal output or let the agent run commands in those sessions. Also note the small metadata mismatch (registry didn't list tmux as a required binary while SKILL.md does); ensure the runtime environment includes tmux and that you are comfortable granting the skill access to the specified socket directory.

tmux Skill (Clawdbot)

Use tmux only when you need an interactive TTY. Prefer bash background mode for long-running, non-interactive tasks.

Quickstart (isolated socket, bash tool)

SOCKET_DIR="${CLAWDBOT_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/clawdbot-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/clawdbot.sock"
SESSION=clawdbot-python

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

After starting a session, always print monitor commands:

To monitor:
  tmux -S "$SOCKET" attach -t "$SESSION"
  tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

Socket convention

• Use CLAWDBOT_TMUX_SOCKET_DIR (default ${TMPDIR:-/tmp}/clawdbot-tmux-sockets).
• Default socket path: "$CLAWDBOT_TMUX_SOCKET_DIR/clawdbot.sock".

Targeting panes and naming

• Target format: session:window.pane (defaults to :0.0).
• Keep names short; avoid spaces.
• Inspect: tmux -S "$SOCKET" list-sessions, tmux -S "$SOCKET" list-panes -a.

Finding sessions

• List sessions on your socket: {baseDir}/scripts/find-sessions.sh -S "$SOCKET".
• Scan all sockets: {baseDir}/scripts/find-sessions.sh --all (uses CLAWDBOT_TMUX_SOCKET_DIR).

Sending input safely

• Prefer literal sends: tmux -S "$SOCKET" send-keys -t target -l -- "$cmd".
• Control keys: tmux -S "$SOCKET" send-keys -t target C-c.

Watching output

• Capture recent history: tmux -S "$SOCKET" capture-pane -p -J -t target -S -200.
• Wait for prompts: {baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern'.
• Attaching is OK; detach with Ctrl+b d.

Spawning processes

• For python REPLs, set PYTHON_BASIC_REPL=1 (non-basic REPL breaks send-keys flows).

Windows / WSL

• tmux is supported on macOS/Linux. On Windows, use WSL and install tmux inside WSL.
• This skill is gated to darwin/linux and requires tmux on PATH.

Orchestrating Coding Agents (Codex, Claude Code)

tmux excels at running multiple coding agents in parallel:

SOCKET="${TMPDIR:-/tmp}/codex-army.sock"

# Create multiple sessions
for i in 1 2 3 4 5; do
  tmux -S "$SOCKET" new-session -d -s "agent-$i"
done

# Launch agents in different workdirs
tmux -S "$SOCKET" send-keys -t agent-1 "cd /tmp/project1 && codex --yolo 'Fix bug X'" Enter
tmux -S "$SOCKET" send-keys -t agent-2 "cd /tmp/project2 && codex --yolo 'Fix bug Y'" Enter

# Poll for completion (check if prompt returned)
for sess in agent-1 agent-2; do
  if tmux -S "$SOCKET" capture-pane -p -t "$sess" -S -3 | grep -q "❯"; then
    echo "$sess: DONE"
  else
    echo "$sess: Running..."
  fi
done

# Get full output from completed session
tmux -S "$SOCKET" capture-pane -p -t agent-1 -S -500

Tips:

• Use separate git worktrees for parallel fixes (no branch conflicts)
• pnpm install first before running codex in fresh clones
• Check for shell prompt (❯ or $) to detect completion
• Codex needs --yolo or --full-auto for non-interactive fixes

Cleanup

• Kill a session: tmux -S "$SOCKET" kill-session -t "$SESSION".
• Kill all sessions on a socket: tmux -S "$SOCKET" list-sessions -F '#{session_name}' | xargs -r -n1 tmux -S "$SOCKET" kill-session -t.
• Remove everything on the private socket: tmux -S "$SOCKET" kill-server.

Helper: wait-for-text.sh

{baseDir}/scripts/wait-for-text.sh polls a pane for a regex (or fixed string) with a timeout.

{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]

• -t/--target pane target (required)
• -p/--pattern regex to match (required); add -F for fixed string
• -T timeout seconds (integer, default 15)
• -i poll interval seconds (default 0.5)
• -l history lines to search (integer, default 1000)