tmux - SKILL.md Agent Skill

name: tmux description: 'Control tmux sessions by sending keystrokes and scraping pane output. Use when you need an interactive TTY: manipulating existing tmux sessions (e.g. other coding agents), running interactive CLIs that require a TTY (e.g. vim, python REPL, ncurses apps), spawning dev servers or long-running processes that must outlive the agent, or orchestrating multiple coding agents (claude, droid, codex, aider) with shared dev environments. Requires tmux on PATH (macOS/Linux or WSL).'

tmux Skill

Use tmux only when you need an interactive TTY to:

Manipulate existing tmux sessions (e.g. other coding agents)
Run interactive CLIs that require a TTY (e.g. vim)
Spawn long-running processes that you want them to last even after the agent finishes (e.g. a dev server)

Prefer native bash tool with background mode for long-running, non-interactive tasks.

Quickstart

SESSION=agentic-python
tmux new -d -s "$SESSION" -n shell
tmux send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux capture-pane -p -J -t "$SESSION":0.0 -S -200

After starting a session, always print monitor commands:

To monitor:
  tmux attach -t "$SESSION"
  tmux capture-pane -p -J -t "$SESSION":0.0 -S -200

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.

Finding sessions

List sessions: scripts/find-sessions.sh (bundled with this skill).
Filter by name: scripts/find-sessions.sh -q pattern.

Sending input safely

Prefer literal sends: tmux send-keys -t target -l -- "$cmd".
Control keys: tmux send-keys -t target C-c.

Watching output

Capture recent history: tmux capture-pane -p -J -t target -S -200.
Wait for prompts: scripts/wait-for-text.sh -t session:0.0 -p 'pattern' (bundled).
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

On Windows, use WSL and install tmux inside WSL.

Orchestrating Coding Agents

Session naming convention

{proj}-claude-1   # Claude Code agent 1
{proj}-claude-2   # Claude Code agent 2
{proj}-droid-1    # Droid agent 1
{proj}-shared     # Dev servers / watchers (multiple windows)

Same pattern works for any agent CLI (codex, aider, etc.).

Launching agents

One session per agent instance, started interactively:

PROJ=myapp
tmux new-session -d -s "${PROJ}-claude-1" -- claude --allow-dangerously-bypass-permissions
tmux new-session -d -s "${PROJ}-droid-1"  -- droid
tmux new-session -d -s "${PROJ}-codex-1"  -- codex --full-auto

# Shared session for long-running processes
tmux new-session -d -s "${PROJ}-shared" -n "dev-server"
tmux new-window  -t "${PROJ}-shared" -n "logs"

Sending tasks

Wait for the agent to finish its startup or current prompt turn before sending the next input. Then:

tmux send-keys -t "${PROJ}-claude-1" "Fix the login bug in auth.ts" Enter

Shared session

tmux send-keys -t "${PROJ}-shared:dev-server" "npm run dev" Enter
tmux send-keys -t "${PROJ}-shared:logs"       "tail -f app.log" Enter

Tips:

Use separate git worktrees per agent to avoid branch conflicts
Keep agent sessions single-window; use {proj}-shared for everything that outlives an agent run

Cleanup

Kill a session: tmux kill-session -t "$SESSION".
Kill all sessions on default socket: tmux list-sessions -F '#{session_name}' | xargs -r -n1 tmux kill-session -t.
Never use tmux kill-server to avoid killing shared or user-managed sessions.

Helper: wait-for-text.sh

scripts/wait-for-text.sh polls a pane for a regex (or fixed string) with a timeout.

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)