Lucky Tmux Controller

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

Security Scan

The skill is broadly what it says (a tmux controller) and has small, readable helper scripts, but it can read and control any tmux session reachable from the host and the scripts reference environment variables not declared in the manifest — this combination could expose sensitive terminal output and the mismatch should be reviewed before use.

Purpose & Capability

Name and description match the actual behavior: the skill requires the tmux binary and provides instructions and helper scripts to list sessions, capture pane output, wait for text, and send keys via tmux. That capability legitimately needs tmux and the provided commands. Note: the scripts support scanning a socket directory (OPENCLAW_TMUX_SOCKET_DIR / CLAWDBOT_TMUX_SOCKET_DIR) which is reasonable for multi-socket setups but is not declared in requires.env.

Instruction Scope

SKILL.md plus the scripts instruct the agent to capture pane output and send keystrokes. The included wait-for-text.sh prints captured pane contents on timeout and find-sessions.sh can enumerate sessions across sockets; both actions can read arbitrary terminal output from any session accessible via the tmux socket. The instructions do not explicitly warn about sensitive data exposure, and there is a small inconsistency (SKILL.md 'When NOT to Use' says not to create new sessions while the examples include tmux session management commands).

Install Mechanism

No install spec (instruction-only with two small shell scripts). No remote downloads or package installs; nothing is written to disk by an installer. This is the lower-risk category for install mechanisms.

Credentials

The manifest lists no required env vars, but scripts read OPENCLAW_TMUX_SOCKET_DIR and CLAWDBOT_TMUX_SOCKET_DIR (with a fallback into /tmp). Those env vars are optional but present in the runtime behavior and not declared up-front. Because tmux sockets control which sessions are accessible, these environment variables materially affect which sessions the skill can enumerate and read.

Persistence & Privilege

The skill does not request always:true and does not modify other skills or system-wide configs. It relies on the tmux binary and runs helper scripts; autonomous invocation is allowed (platform default) but not combined with any elevated persistent privileges.

What to consider before installing

This skill is functionally consistent with a tmux controller, but take precautions before installing or enabling it: - Understand it can read and send keystrokes to any tmux session accessible via the tmux socket(s) on the host — sensitive data (passwords, tokens, private code) in other panes could be exposed. Only use it on machines and sessions you trust. - The scripts look for OPENCLAW_TMUX_SOCKET_DIR / CLAWDBOT_TMUX_SOCKET_DIR; verify these environment variables (or the default /tmp path) so you know which sockets will be scanned. - Review the two bundled shell scripts locally to confirm no unexpected behavior (they are short and readable). They do not perform network I/O, but they do print pane contents to stdout/stderr on timeout. - If you need tighter control, run the scripts manually first or run the agent/skill in a sandbox/container that restricts access to tmux sockets you do not own. - Consider restricting autonomous use of the skill in the agent (disable autonomous invocation for sensitive workflows) or only enable it for sessions you control. If you want, I can point out exactly which lines reference the environment variables and where pane contents are printed so you can verify them yourself.

tmux Session Control

Control tmux sessions by sending keystrokes and reading output. Essential for managing Claude Code sessions.

When to Use

✅ USE this skill when:

• Monitoring Claude/Codex sessions in tmux
• Sending input to interactive terminal applications
• Scraping output from long-running processes in tmux
• Navigating tmux panes/windows programmatically
• Checking on background work in existing sessions

When NOT to Use

❌ DON'T use this skill when:

• Running one-off shell commands → use exec tool directly
• Starting new background processes → use exec with background:true
• Non-interactive scripts → use exec tool
• The process isn't in tmux
• You need to create a new tmux session → use exec with tmux new-session

Example Sessions

Session	Purpose
shared	Primary interactive session
worker-2 - worker-8	Parallel worker sessions

Common Commands

List Sessions

tmux list-sessions
tmux ls

Capture Output

# Last 20 lines of pane
tmux capture-pane -t shared -p | tail -20

# Entire scrollback
tmux capture-pane -t shared -p -S -

# Specific pane in window
tmux capture-pane -t shared:0.0 -p

Send Keys

# Send text (doesn't press Enter)
tmux send-keys -t shared "hello"

# Send text + Enter
tmux send-keys -t shared "y" Enter

# Send special keys
tmux send-keys -t shared Enter
tmux send-keys -t shared Escape
tmux send-keys -t shared C-c          # Ctrl+C
tmux send-keys -t shared C-d          # Ctrl+D (EOF)
tmux send-keys -t shared C-z          # Ctrl+Z (suspend)

Window/Pane Navigation

# Select window
tmux select-window -t shared:0

# Select pane
tmux select-pane -t shared:0.1

# List windows
tmux list-windows -t shared

Session Management

# Create new session
tmux new-session -d -s newsession

# Kill session
tmux kill-session -t sessionname

# Rename session
tmux rename-session -t old new

Sending Input Safely

For interactive TUIs (Claude Code, Codex, etc.), split text and Enter into separate sends to avoid paste/multiline edge cases:

tmux send-keys -t shared -l -- "Please apply the patch in src/foo.ts"
sleep 0.1
tmux send-keys -t shared Enter

Claude Code Session Patterns

Check if Session Needs Input

# Look for prompts
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"

Approve Claude Code Prompt

# Send 'y' and Enter
tmux send-keys -t worker-3 'y' Enter

# Or select numbered option
tmux send-keys -t worker-3 '2' Enter

Check All Sessions Status

for s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do
  echo "=== $s ==="
  tmux capture-pane -t $s -p 2>/dev/null | tail -5
done

Send Task to Session

tmux send-keys -t worker-4 "Fix the bug in auth.js" Enter

Notes

• Use capture-pane -p to print to stdout (essential for scripting)
• -S - captures entire scrollback history
• Target format: session:window.pane (e.g., shared:0.0)
• Sessions persist across SSH disconnects