tmux Skill

Control tmux sessions programmatically. Send keys, capture output, run interactive processes.

Cross-platform:

Linux/macOS: Uses native tmux
Windows: Uses psmux (native Windows tmux, 95%+ syntax compatible)

Use tmux when:

SSH to remote servers (persistent sessions)
Interactive TTY needed (REPLs, shells, prompts)
Running multiple processes in parallel
Orchestrating coding agents

Don't use tmux for:

Simple background tasks → use bg run instead
One-shot commands → run directly

Installation

Linux/macOS

# Debian/Ubuntu
sudo apt install tmux

# macOS
brew install tmux

Windows (psmux)

psmux is a native Windows tmux implementation. Same commands, same config.

# WinGet (recommended)
winget install psmux

# Scoop
scoop bucket add psmux https://github.com/marlocarlo/scoop-psmux
scoop install psmux

# Chocolatey
choco install psmux

# Cargo
cargo install psmux

If installation fails:

Check GitHub releases: https://github.com/marlocarlo/psmux/releases
Download .zip, extract, add to PATH
Requires PowerShell 7+ (install: winget install Microsoft.PowerShell)

Verify:

psmux -V
# or just: tmux (psmux ships with tmux alias)

Quick Start

# Unix
tmux -V
tmx new mysession
tmx sync mysession "ls -la"
tmx capture mysession
tmx kill mysession

# Windows
psmux -V
tmx new mysession
tmx sync mysession "Get-ChildItem"
tmx capture mysession
tmx kill mysession

Helper: tmx

Scripts at {baseDir}/scripts/:

tmx.sh — Bash version (Linux/macOS)
tmx.ps1 — PowerShell version (Windows, works everywhere)

Commands

Command	Description
`tmx new <name> [cmd]`	Create session, optionally run cmd
`tmx send <session> "<cmd>"`	Send keys (fire and forget)
`tmx capture <session> [lines]`	Capture output (default 500 lines)
`tmx sync <session> "<cmd>"`	Send + wait + capture
`tmx list`	List all sessions
`tmx kill <session>`	Kill session
`tmx attach <session>`	Attach interactively

Sync Modes

# Wait for shell prompt (default)
tmx sync server "pip install numpy"

# Fixed timeout mode
tmx sync server "make build" --timeout 30   # Bash
tmx sync server "make build" -Timeout 30    # PowerShell

# Custom prompt pattern
tmx sync server "python script.py" --prompt "DONE>"  # Bash
tmx sync server "python script.py" -Prompt "DONE>"   # PowerShell

Pattern 1: SSH Sessions (Most Common)

SSH through tmux gives persistent sessions that survive disconnects.

# Create SSH session
tmx new server "ssh user@myserver.com"

# Wait for password prompt or SSH ready
tmx capture server 20   # Check where we are

# Send password (if needed)
tmx send server "mypassword"

# Wait for shell prompt on remote
tmx sync server "hostname" --prompt '\$'

# Run remote commands
tmx sync server "cd /var/log && ls -la"
tmx sync server "tail -100 nginx/access.log" --timeout 5

# Long-running remote task
tmx send server "docker logs -f mycontainer"
# Later: capture output
tmx capture server 500

# Detach and return later - SSH persists!
tmx list  # session still there
tmx capture server  # get latest output

SSH with sudo:

tmx new prod "ssh admin@prod-server"
tmx sync prod "sudo tail -f /var/log/syslog" --prompt '\[sudo\]'
tmx send prod "sudo_password"
tmx capture prod 200

Pattern 2: Background Process Monitoring

Monitor long-running processes in tmux. Useful when already working in tmux context.

# Start a server
tmx new api "cd /app && python api.py"
tmx sync api "echo 'Server starting...'" --timeout 3

# Check if running
tmx capture api 30 | grep -q "Listening" && echo "API is up"

# Monitor logs
tmx capture api 100

# Tail mode (continuous capture)
for i in {1..10}; do
  tmx capture api 5
  sleep 2
done

# Multiple services
tmx new db "docker run --name postgres -e POSTGRES_PASSWORD=pass postgres"
tmx new redis "redis-server"

# Check all
tmx list
tmx capture db 20
tmx capture redis 20

Pattern 3: Interactive REPL

REPLs work but may need prompt tuning. Use --prompt for custom prompts.

# Python (standard REPL)
tmx new python "python3 -q"
tmx sync python "import sys; print(sys.version)"
tmx sync python "2 + 2"

# IPython (custom prompt)
tmx new ipy "ipython"
tmx sync ipy "print('hello')" --prompt "In \[.*\]:"

# Node.js
tmx new node "node -i"
tmx sync node "1+1" --prompt ">"

Pattern 4: Parallel Agents

# Spin up multiple coding agents
for i in 1 2 3; do
  tmx new "agent-$i" "cd /tmp/project$i && codex --yolo 'Fix bugs'"
done

# Poll for completion
for s in agent-1 agent-2 agent-3; do
  if tmx capture "$s" 20 | grep -q "completed"; then
    echo "$s: DONE"
  fi
done

# Get results
tmx capture agent-1 2000

Key Bindings (when attached)

Key	Action
`Ctrl+b d`	Detach from session
`Ctrl+b c`	Create new window
`Ctrl+b n/p`	Next/Previous window
`Ctrl+b %`	Split vertical
`Ctrl+b "`	Split horizontal
`Ctrl+b [`	Copy mode (scroll)

Platform Differences

Feature	tmux (Unix)	psmux (Windows)
Sessions	✅	✅
Windows/Panes	✅	✅
Detach/Attach	✅	✅
`capture-pane`	✅	✅
`send-keys`	✅	✅
`.tmux.conf`	✅	✅ (also `.psmux.conf`)
Mouse support	✅	✅
SSH mouse	✅	Win11 22H2+

Gotchas

REPL prompts: IPython, IRB, etc. use different prompts. Use --prompt to match.
Named sessions only: No socket complexity
Prompt detection: Default (\$|❯|#|>|>>>) covers most shells
psmux is fresh: If issues, check GitHub releases for updates
Windows needs PowerShell 7+: Install with winget install Microsoft.PowerShell

Raw Commands

# Target syntax: session:window.pane
tmux send-keys -t mysession -l -- "echo hello"
tmux send-keys -t mysession Enter
tmux capture-pane -p -J -t mysession -S -500
tmux list-sessions