Tmux

---

name: tmux slug: tmux-controller version: 1.0.0 description: Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output. metadata: { "openclaw": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux"] } } }

---

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.