Tmux

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

Security Scan

The skill's requirements, included script, and runtime instructions are coherent with its stated purpose of controlling tmux sessions; it does not request unrelated credentials or install arbitrary software.

Purpose & Capability

The skill only requires the tmux binary and its instructions and script exclusively use tmux commands (new-session, send-keys, capture-pane, kill-session). The included wait-for-text.sh polls tmux panes for text; this is directly aligned with 'remote-control tmux sessions'.

Instruction Scope

Instructions explicitly tell the agent to start and drive interactive programs inside tmux and to scrape pane output. This is expected for the stated purpose, but it means the skill will cause arbitrary commands to run inside user sessions (examples include launching 'claude'/'codex' with flags that bypass permissions). Also the guidance to always use the default tmux server means the skill will operate on the user's primary tmux server and could interact with or affect other user sessions if names collide.

Install Mechanism

No install spec; this is instruction-only plus a small included Bash helper script. Nothing is downloaded or written to disk beyond the provided script, so installation risk is low.

Credentials

The skill declares no required environment variables, credentials, or config paths. The SKILL.md examples reference running external agent binaries but do not request secret tokens from the environment.

Persistence & Privilege

always is false and the skill does not request persistent elevated privileges or modify other skills. It uses the default tmux server by design, which is a functional decision rather than a privilege escalation.

Assessment

This skill appears internally consistent and does what it says: orchestrate and scrape tmux panes. Before installing, consider: - The skill uses the default tmux server and an 'oc-' naming convention; if you already run tmux sessions, the skill could accidentally target or kill sessions with conflicting names. Prefer running in a dedicated socket or separate user if you need isolation. - The skill drives arbitrary CLI processes inside tmux — do not run untrusted binaries via these sessions. Examples in the docs (like --dangerously-skip-permissions, --yolo, or --full-auto) are risky flags for real agent binaries; avoid using them unless you understand the implications. - The included wait-for-text.sh polls panes and can block until timeouts; review timeout settings to avoid long-running hangs. - If you need stronger containment, run tmux under a dedicated user, dedicated container, or use a custom socket (contrary to the skill's default recommendation) to avoid interacting with your interactive desktop/server tmux sessions. If you are comfortable with these caveats, the skill is coherent with its purpose.

tmux Skill

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

Default Server — No Custom Sockets

Always use the default tmux server. Do NOT use -S custom sockets. The user needs to tmux attach easily without knowing obscure socket paths.

Session Naming

Convention: oc-${project}-${feature} (e.g. oc-knowhere-date-range-picker, oc-deck-auth-flow)

• oc- prefix = OpenClaw-managed, avoids collision with user sessions
• Easy to find: tmux ls | grep oc-

Quickstart

SESSION=oc-myproject-feature

tmux new-session -d -s "$SESSION" -c ~/projects/myproject
tmux send-keys -t "$SESSION" 'claude --dangerously-skip-permissions' Enter
tmux capture-pane -p -J -t "$SESSION" -S -200

After starting a session, tell the user:

To monitor: tmux attach -t $SESSION

Targeting panes and naming

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

Sending input safely

• Prefer literal sends: tmux send-keys -t target -l -- "$cmd".
• Control keys: tmux send-keys -t target C-c.
• For interactive TUI apps like Claude Code/Codex, do not append Enter in the same send-keys. These apps may treat a fast text+Enter sequence as paste/multi-line input and not submit. Send text and Enter as separate commands with a small delay:

tmux send-keys -t target -l -- "$cmd" && sleep 0.1 && tmux send-keys -t target Enter

Watching output

• Capture recent history: tmux capture-pane -p -J -t target -S -200.
• 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).

Orchestrating Coding Agents (Codex, Claude Code)

tmux excels at running multiple coding agents in parallel:

# Create sessions in different worktrees
tmux new-session -d -s oc-project-fix1 -c ~/projects/project-fix1
tmux new-session -d -s oc-project-fix2 -c ~/projects/project-fix2

# Launch agents
tmux send-keys -t oc-project-fix1 'claude --dangerously-skip-permissions' Enter
tmux send-keys -t oc-project-fix2 'codex --full-auto' Enter

# Send a prompt (text + Enter separated by delay)
tmux send-keys -t oc-project-fix1 -l -- "Fix the date picker styling." && sleep 0.1 && tmux send-keys -t oc-project-fix1 Enter

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

# Get full output
tmux capture-pane -p -t oc-project-fix1 -S -500

Tips:

• Use separate git worktrees for parallel fixes (no branch conflicts)
• bun install / pnpm install first before running agents 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 kill-session -t "$SESSION".
• Kill all OpenClaw sessions: tmux ls -F '#{session_name}' | grep '^oc-' | xargs -n1 tmux kill-session -t.