tmux

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

tmux (terminal multiplexer) is a foundational Unix tool, but in the OpenClaw context, the tmux skill is something much more specific: it's the technique for AI agents to control interactive CLI applications that require a real terminal. It teaches OpenClaw how to create detached tmux sessions, send keystrokes to them, and scrape the pane output — effectively giving the AI 'hands' to operate interactive programs. This is critical because many powerful CLI tools (Python REPLs, database consoles, SSH sessions, 1Password CLI, interactive installers) require a TTY and can't be automated with simple shell pipes. The tmux skill solves this by creating a virtual terminal that the AI can puppeteer: send input with `tmux send-keys`, read output with `tmux capture-pane`, and manage the lifecycle with `tmux new-session` and `tmux kill-session`. The skill covers several patterns: basic session management (create, list, kill), keystroke-based interaction (send commands, press Enter, handle prompts), output scraping (capture what's displayed in the pane), and socket-based isolation (using `-S` for per-tool sockets so sessions don't collide). It's the underlying mechanism that makes skills like 1Password CLI, Coding Agent, and Cursor Agent work. For OpenClaw users, the tmux skill is usually invisible — other skills use it under the hood. But understanding it is valuable for building custom automations that interact with tools lacking non-interactive modes. If you find yourself saying 'this CLI needs me to type something interactively,' the tmux pattern is the answer. The socket pattern (`$TMPDIR/openclaw-tmux-sockets/`) is important: each tool gets its own tmux socket, preventing session name collisions and making cleanup reliable. Sessions are created detached (`new -d`) so they run in the background. Best suited for: skill authors building automations for interactive CLIs, power users who need AI to control terminal applications, developers understanding OpenClaw's internal automation patterns, anyone bridging between AI agents and legacy terminal tools.

Tags: terminal, multiplexer, session, automation

Category: Developer Tools

Use Cases

  • Automate 1Password CLI authentication (requires interactive TTY)
  • Run Python/Node REPLs with AI-driven input/output
  • Manage SSH sessions from the AI assistant
  • Interactive database consoles (psql, mysql, redis-cli)
  • Long-running background processes with periodic status checks
  • Skill development: wrap any interactive CLI for AI automation

Tips

  • Use socket isolation: `tmux -S $TMPDIR/openclaw-tmux-sockets/tool.sock` to avoid collisions
  • Always create sessions detached: `tmux -S sock new -d -s session-name`
  • Use `tmux -S sock capture-pane -t session -p` to read current pane content
  • Add short delays (0.5-1s) after send-keys before capturing output — commands need time to execute
  • Use `tmux -S sock send-keys -t session 'command' Enter` — don't forget the Enter!
  • Clean up sessions when done: `tmux -S sock kill-session -t session`
  • For multi-step interactions, chain send-keys with sleeps: send input → wait → read output → send next
  • The 1Password skill is the best reference implementation for the tmux pattern

Known Issues & Gotchas

  • tmux must be installed separately — it's not bundled with macOS anymore (Homebrew: `brew install tmux`)
  • Session names must be unique per socket — always use descriptive, timestamped names
  • send-keys doesn't wait for the command to complete — you need to add sleep/poll for output
  • capture-pane returns what's visible in the pane, not the full scrollback — use `-S -` for full history
  • Socket files in $TMPDIR get cleaned on reboot — don't expect sessions to survive restarts
  • tmux sessions run as your user — they inherit your permissions and environment
  • Some interactive tools (like fzf) use alternate screen buffers that capture-pane can't read
  • On Linux, $TMPDIR may not be set — fall back to /tmp for socket paths

Alternatives

  • screen
  • expect/pexpect
  • PTY (exec pty:true)
  • script (util-linux)

Community Feedback

OpenClaw + Tmux Setup: A Game-Changing Workflow. The tmux skill teaches OpenClaw how to interact with the environment: it can inspect, create, or kill sessions, capture pane output and send keystrokes.

— Tmux Cheatsheet Blog

Remote control tmux sessions for interactive command-line work. Send keystrokes and scrape pane output from Python REPLs, debuggers, and other interactive CLIs.

— Smithery.ai

Manages interactive terminal sessions, REPLs, and long-running background processes within tmux panes to enable persistent and parallel command execution.

— MCP Market

Interactive CLI output streaming + attach/recover (tmux-backed workflow). Add first-class support for streaming and attaching to long-running interactive CLI processes.

— GitHub Issues (OpenClaw)

Configuration Examples

Basic tmux automation pattern

# Create isolated socket directory
SOCKDIR="$TMPDIR/openclaw-tmux-sockets"
mkdir -p "$SOCKDIR"
SOCK="$SOCKDIR/my-tool.sock"

# Create detached session
tmux -S "$SOCK" new -d -s my-session

# Send a command
tmux -S "$SOCK" send-keys -t my-session 'echo hello world' Enter

# Wait for output
sleep 1

# Read pane content
tmux -S "$SOCK" capture-pane -t my-session -p

Interactive REPL pattern

# Start a Python REPL in tmux
tmux -S "$SOCK" new -d -s python-repl 'python3'
sleep 1

# Send Python commands
tmux -S "$SOCK" send-keys -t python-repl 'import json' Enter
sleep 0.5
tmux -S "$SOCK" send-keys -t python-repl 'print(json.dumps({"hello": "world"}))' Enter
sleep 0.5

# Read output
tmux -S "$SOCK" capture-pane -t python-repl -p

# Cleanup
tmux -S "$SOCK" kill-session -t python-repl

List and manage sessions

# List all sessions on a socket
tmux -S "$SOCK" list-sessions

# List all OpenClaw tmux sockets
ls $TMPDIR/openclaw-tmux-sockets/

# Kill all sessions on a socket
tmux -S "$SOCK" kill-server

# Check if a session exists
tmux -S "$SOCK" has-session -t my-session 2>/dev/null && echo 'exists' || echo 'gone'

Installation

brew install tmux

Source: bundled