Tmux Steipete

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

Security Scan

The skill's code and instructions match a tmux remote-control purpose, but there are small metadata mismatches and usage patterns (scanning/targeting arbitrary tmux sockets) that could be abused or indicate sloppy packaging; review before installing.

Purpose & Capability

Name/description, required binary (tmux), scripts, and runtime instructions align with a tool to control tmux sessions. The ability to list, capture, and send keystrokes is expected for this purpose. However, the skill exposes optional scanning of multiple sockets (--all) which — if pointed at a shared socket directory — can enumerate other users' sessions; that is a sensitive capability but coherent with the stated goal.

Instruction Scope

SKILL.md and the included scripts instruct the agent to send keystrokes and scrape pane output (capture-pane), which is exactly the advertised functionality. The instructions reference an environment variable CLAWDBOT_TMUX_SOCKET_DIR (and allow arbitrary -S socket paths) even though requires.env is empty; this gives the agent scope to target any tmux socket path the operator or agent supplies, which could lead to accessing or controlling unrelated sessions if misused.

Install Mechanism

No install spec; this is instruction+script-only and requires tmux on PATH. Nothing is downloaded or extracted from external URLs.

Credentials

The registry lists no required env vars, but SKILL.md and the scripts rely on CLAWDBOT_TMUX_SOCKET_DIR (with a TMPDIR fallback). That environment dependency is reasonable for socket location, but it's not declared in the metadata. No credentials or unrelated environment access is requested.

Persistence & Privilege

always:false and there is no install-time modification of other skills or global agent settings. The skill does not request persistent privileges beyond using tmux sockets accessible to the process.

What to consider before installing

This skill appears to do what it says (control tmux sessions) and only requires tmux, but review before installing: - Metadata mismatch: the embedded _meta.json ownerId differs from the registry ownerId — that suggests copy/paste or packaging issues; verify the publisher identity if that matters to you. - Socket targeting is powerful: the scripts accept arbitrary socket paths and a --all scan mode. If the socket directory is shared (e.g., a world-writable /tmp path or system tmux socket), the skill could list, read, and send keystrokes to other users' tmux sessions — effectively running commands in their shells. Only run this skill in an isolated environment or ensure CLAWDBOT_TMUX_SOCKET_DIR points to a private socket directory. - The SKILL.md references CLAWDBOT_TMUX_SOCKET_DIR but the skill metadata doesn't declare it; treat that env var as required configuration and confirm its value before use. - No network exfiltration endpoints or hidden downloads were found in the files, but the core capability (send-keys, capture-pane) is inherently sensitive. If you plan to allow autonomous agent invocation, be cautious: an agent could use this skill to control local shells if given socket paths. If you want to proceed: verify the publisher, restrict the socket directory to a private location, and test in a non-production environment first.

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)