Smux

smux

Tmux pane control and cross-pane agent communication. Use tmux-bridge (the high-level CLI) for all cross-pane interactions. Fall back to raw tmux commands only when you need low-level control.

tmux-bridge — Cross-Pane Communication

A CLI that lets any AI agent interact with any other tmux pane. Works via plain bash. Every command is atomic: type types text (no Enter), keys sends special keys, read captures pane content.

DO NOT WAIT OR POLL

Other panes have agents that will reply to you via tmux-bridge. Their reply appears directly in YOUR pane as a [tmux-bridge from:...] message. Do not sleep, poll, read the target pane for a response, or loop. Type your message, press Enter, and move on.

The ONLY time you read a target pane is:

• Before interacting with it (enforced by the read guard)
• After typing to verify your text landed before pressing Enter
• When interacting with a non-agent pane (plain shell, running process)

Read Guard

The CLI enforces read-before-act. You cannot type or keys to a pane unless you have read it first.

1. tmux-bridge read <target> marks the pane as "read" 2. tmux-bridge type/keys <target> checks for that mark — errors if you haven't read 3. After a successful type/keys, the mark is cleared — you must read again before the next interaction

$ tmux-bridge type codex "hello"
error: must read the pane before interacting. Run: tmux-bridge read codex

Command Reference

Target Resolution

Targets can be:

• tmux native: session:window.pane (e.g. shared:0.1), pane ID (%3), or window index (0)
• label: Any string set via tmux-bridge name — resolved automatically

Read-Act-Read Cycle

Every interaction follows read → act → read. The CLI enforces this.

Sending a message to an agent:

tmux-bridge read codex 20                    # 1. READ — satisfy read guard
tmux-bridge message codex 'Please review src/auth.ts'
                                              # 2. MESSAGE — auto-prepends sender info, no Enter
tmux-bridge read codex 20                    # 3. READ — verify text landed
tmux-bridge keys codex Enter                 # 4. KEYS — submit
# STOP. Do NOT read codex for a reply. The agent replies into YOUR pane.

Approving a prompt (non-agent pane):

tmux-bridge read worker 10                   # 1. READ — see the prompt
tmux-bridge type worker "y"                  # 2. TYPE
tmux-bridge read worker 10                   # 3. READ — verify
tmux-bridge keys worker Enter                # 4. KEYS — submit
tmux-bridge read worker 20                   # 5. READ — see the result

Messaging Convention

The message command auto-prepends sender info and location:

[tmux-bridge from:claude pane:%4 at:3:0.0] Please review src/auth.ts

The receiver gets: who sent it (from), the exact pane to reply to (pane), and the session/window location (at). When you see this header, reply using tmux-bridge to the pane ID from the header.

Agent-to-Agent Workflow

# 1. Label yourself
tmux-bridge name "$(tmux-bridge id)" claude

# 2. Discover other panes
tmux-bridge list

# 3. Send a message (read-act-read)
tmux-bridge read codex 20
tmux-bridge message codex 'Please review the changes in src/auth.ts'
tmux-bridge read codex 20
tmux-bridge keys codex Enter

Example Conversation

Agent A (claude) sends:

tmux-bridge read codex 20
tmux-bridge message codex 'What is the test coverage for src/auth.ts?'
tmux-bridge read codex 20
tmux-bridge keys codex Enter

Agent B (codex) sees in their prompt:

[tmux-bridge from:claude pane:%4 at:3:0.0] What is the test coverage for src/auth.ts?

Agent B replies using the pane ID from the header:

tmux-bridge read %4 20
tmux-bridge message %4 '87% line coverage. Missing the OAuth refresh token path (lines 142-168).'
tmux-bridge read %4 20
tmux-bridge keys %4 Enter

---

Raw tmux Commands

Use these when you need direct tmux control beyond what tmux-bridge provides — session management, window navigation, creating panes, or low-level scripting.

Capture Output

tmux capture-pane -t shared -p | tail -20    # Last 20 lines
tmux capture-pane -t shared -p -S -          # Entire scrollback
tmux capture-pane -t shared:0.0 -p           # Specific pane

Send Keys

tmux send-keys -t shared -l -- "text here"   # Type text (literal mode)
tmux send-keys -t shared Enter               # Press Enter
tmux send-keys -t shared Escape              # Press Escape
tmux send-keys -t shared C-c                 # Ctrl+C
tmux send-keys -t shared C-d                 # Ctrl+D (EOF)

For interactive TUIs, split text and Enter into separate sends:

tmux send-keys -t shared -l -- "Please apply the patch"
sleep 0.1
tmux send-keys -t shared Enter

Panes and Windows

# Create panes (prefer over new windows)
tmux split-window -h -t SESSION              # Horizontal split
tmux split-window -v -t SESSION              # Vertical split
tmux select-layout -t SESSION tiled          # Re-balance

# Navigate
tmux select-window -t shared:0
tmux select-pane -t shared:0.1
tmux list-windows -t shared

Session Management

tmux list-sessions
tmux new-session -d -s newsession
tmux kill-session -t sessionname
tmux rename-session -t old new

Claude Code Patterns

# Check if session needs input
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"

# Approve a prompt
tmux send-keys -t worker-3 'y' Enter

# Check all sessions
for s in shared worker-2 worker-3 worker-4; do
  echo "=== $s ==="
  tmux capture-pane -t $s -p 2>/dev/null | tail -5
done

Tips

• Read guard is enforced — you MUST read before every type/keys
• Every action clears the read mark — after type, read again before keys
• Never wait or poll — agent panes reply via tmux-bridge into YOUR pane
• Label panes early — easier than using %N IDs
• `type` uses literal mode — special characters are typed as-is
• `read` defaults to 50 lines — pass a higher number for more context
• Non-agent panes are the exception — you DO need to read them to see output
• Use capture-pane -p to print to stdout (essential for scripting)
• Target format: session:window.pane (e.g., shared:0.0)

tmux-bridge

A single CLI that lets any AI agent (Claude Code, Codex, Gemini CLI, etc.) interact with any other tmux pane. Works via plain bash — any tool that can run shell commands can use it.

Every command is atomic: type types text (no Enter), keys sends special keys, read captures pane content. There is no compound "send" command — you control each step and verify between them.

DO NOT WAIT OR POLL — EVER

Other panes have agents that will reply to you via tmux-bridge. When you send a message to another agent, their reply will appear directly in YOUR pane as a [tmux-bridge from:...] message. You do NOT need to:

• Sleep or wait after sending
• Poll the target pane for a response
• Read the target pane to check if they replied
• Loop or retry to see output

Type your message, press Enter, and move on. The other agent will type their reply back into your pane. You'll see it arrive.

The ONLY time you need to read a target pane is:

• Before interacting with it (enforced — see Read Guard below)
• After typing to verify your text landed correctly before pressing Enter
• When interacting with a non-agent pane (plain shell, running process) where there's no agent to reply back

Read Guard — Enforced by CLI

The CLI enforces read-before-act. You cannot type or keys to a pane unless you have read it first.

How it works: 1. tmux-bridge read <target> marks the pane as "read" 2. tmux-bridge type/keys <target> checks for that mark — errors if you haven't read 3. After a successful type/keys, the mark is cleared — you must read again before the next interaction

This enforces the read-act-read cycle at the CLI level. If you skip the read, the command fails:

$ tmux-bridge type codex "hello"
error: must read the pane before interacting. Run: tmux-bridge read codex

When to Use

USE this skill when:

• Sending messages to another agent running in a tmux pane
• Reading output from another pane
• Labeling and discovering panes by name
• Any cross-pane interaction between agents

When NOT to Use

DON'T use this skill when:

• Running one-off shell commands in the current pane
• Tasks that don't involve other tmux panes
• You need raw tmux commands → use the tmux skill directly

Command Reference

Target Resolution

Targets can be:

• tmux native: session:window.pane (e.g. shared:0.1), pane ID (%3), or window index (0)
• label: Any string set via tmux-bridge name — resolved automatically

This means tmux-bridge type codex "hello" works directly if the pane was labeled codex.

Messaging Convention

The CLI is format-agnostic — it types exactly what you give it. The recommended convention for agent-to-agent messages is to frame them yourself:

[tmux-bridge from:claude] Please review src/auth.ts

You type this framing as part of your message text. This lets the receiving agent know who sent it and how to reply.

Receiving messages — IMPORTANT

When you see a message prefixed with `[tmux-bridge from:<sender>]`, you MUST reply using tmux-bridge:

tmux-bridge read <sender> 20
tmux-bridge type <sender> "[tmux-bridge from:myname] your response here"
tmux-bridge read <sender> 20
tmux-bridge keys <sender> Enter

This sends your reply directly into the sender's pane so they see it immediately. Do not just respond in your own pane — the sender won't see it unless you send it back via tmux-bridge.

Keep replies concise (1-3 sentences). They will be typed into the sender's terminal as a single line.

Example conversation

Agent A (claude) sends:

tmux-bridge read codex 20       # 1. READ — satisfy read guard
tmux-bridge type codex '[tmux-bridge from:claude] What is the test coverage for src/auth.ts?'
                                 # 2. TYPE — text appears, no Enter yet
tmux-bridge read codex 20       # 3. READ — verify text landed
tmux-bridge keys codex Enter    # 4. KEYS — press Enter to submit
# Done. Do NOT wait, poll, or read codex for the response.
# Agent B will reply via tmux-bridge and it will appear in your pane.

Agent B (codex) sees in their prompt:

[tmux-bridge from:claude] What is the test coverage for src/auth.ts?

Agent B replies:

tmux-bridge read claude 20      # 1. READ — satisfy read guard
tmux-bridge type claude '[tmux-bridge from:codex] src/auth.ts has 87% line coverage. Missing coverage on the OAuth refresh token path (lines 142-168).'
                                 # 2. TYPE — text appears, no Enter yet
tmux-bridge read claude 20      # 3. READ — verify text landed
tmux-bridge keys claude Enter   # 4. KEYS — press Enter to submit
# Done. The reply appears in Agent A's pane automatically.

Read-Act-Read Cycle

Every interaction with another pane MUST follow the read → act → read cycle. The CLI enforces this — type/keys will error if you haven't read first, and each action clears the read mark.

The full cycle for sending a message:

1. Read the target pane (satisfies read guard) 2. Type your message text (clears read mark) 3. Read again (verify text landed, re-satisfy read guard) 4. Keys Enter (submit the message, clears read mark) 5. Read again if you need to see the result (non-agent panes)

Example: sending a message to an agent

# 1. READ — check the pane and satisfy read guard
tmux-bridge read codex 20

# 2. TYPE — type the message (no Enter)
tmux-bridge type codex '[tmux-bridge from:claude] Please review the changes in src/auth.ts'

# 3. READ — verify the text landed correctly
tmux-bridge read codex 20

# 4. KEYS — press Enter to submit
tmux-bridge keys codex Enter

# STOP. Do NOT read codex to check for a reply.
# The other agent will reply via tmux-bridge into YOUR pane.

Example: approving a prompt (non-agent pane)

# 1. READ — see what the prompt is asking
tmux-bridge read worker 10

# 2. TYPE — type the answer
tmux-bridge type worker "y"

# 3. READ — verify it landed
tmux-bridge read worker 10

# 4. KEYS — press Enter to submit
tmux-bridge keys worker Enter

# 5. READ — for non-agent panes, you DO need to read to see the result
tmux-bridge read worker 20

Agent-to-Agent Workflow

Step 1: Label yourself

tmux-bridge name "$(tmux-bridge id)" claude

Step 2: Discover other panes

tmux-bridge list

Step 3: Read, type, read, Enter

tmux-bridge read codex 20
tmux-bridge type codex '[tmux-bridge from:claude] Please review the changes in src/auth.ts and suggest improvements'
tmux-bridge read codex 20
tmux-bridge keys codex Enter
# Done. Wait for the reply to appear in your pane.

Tips

• Read guard is enforced — you MUST read before every type/keys. The CLI will error otherwise.
• Every action clears the read mark — after type, you must read again before keys.
• Never wait or poll — agent panes reply to you via tmux-bridge. The response appears in YOUR pane.
• Label panes early — it makes cross-agent communication much easier than using %N IDs
• `type` uses literal mode — it uses -l so special characters are typed as-is
• `read` defaults to 50 lines — pass a higher number for more context
• Non-agent panes (shells, processes) are the exception — you DO need to read them to see output
• Frame messages yourself — use the [tmux-bridge from:yourname] convention when messaging other agents

tmux Session Control

For cross-pane agent communication, use [`tmux-bridge`](../tmux-bridge/SKILL.md) — a higher-level CLI that handles target resolution, safe input, and wait-for-response. The raw tmux commands below are still useful as reference.

Control tmux sessions by sending keystrokes and reading output. Essential for managing Claude Code sessions.

When to Use

✅ USE this skill when:

• Monitoring Claude/Codex sessions in tmux
• Sending input to interactive terminal applications
• Scraping output from long-running processes in tmux
• Navigating tmux panes/windows programmatically
• Checking on background work in existing sessions

When NOT to Use

❌ DON'T use this skill when:

• Running one-off shell commands → use exec tool directly
• Starting new background processes → use exec with background:true
• Non-interactive scripts → use exec tool
• The process isn't in tmux
• You need to create a new tmux session → use exec with tmux new-session

Example Sessions

Common Commands

List Sessions

tmux list-sessions
tmux ls

Capture Output

# Last 20 lines of pane
tmux capture-pane -t shared -p | tail -20

# Entire scrollback
tmux capture-pane -t shared -p -S -

# Specific pane in window
tmux capture-pane -t shared:0.0 -p

Send Keys

# Send text (doesn't press Enter)
tmux send-keys -t shared "hello"

# Send text + Enter
tmux send-keys -t shared "y" Enter

# Send special keys
tmux send-keys -t shared Enter
tmux send-keys -t shared Escape
tmux send-keys -t shared C-c          # Ctrl+C
tmux send-keys -t shared C-d          # Ctrl+D (EOF)
tmux send-keys -t shared C-z          # Ctrl+Z (suspend)

Window/Pane Navigation

# Select window
tmux select-window -t shared:0

# Select pane
tmux select-pane -t shared:0.1

# List windows
tmux list-windows -t shared

Creating New Panes (Preferred over new windows)

IMPORTANT: When the user asks to create a new window or terminal, always join it as a pane in the current window using split-window instead of creating a separate window. This keeps everything visible side by side.

# Add a new pane to the right (horizontal split)
tmux split-window -h -t SESSION

# Add a new pane below (vertical split)
tmux split-window -v -t SESSION

# Re-balance pane sizes after adding
tmux select-layout -t SESSION tiled

If there are already multiple panes and the layout gets cramped, use tiled layout to distribute evenly:

tmux select-layout -t SESSION tiled

Session Management

# Create new session
tmux new-session -d -s newsession

# Kill session
tmux kill-session -t sessionname

# Rename session
tmux rename-session -t old new

Sending Input Safely

For interactive TUIs (Claude Code, Codex, etc.), split text and Enter into separate sends to avoid paste/multiline edge cases:

tmux send-keys -t shared -l -- "Please apply the patch in src/foo.ts"
sleep 0.1
tmux send-keys -t shared Enter

Claude Code Session Patterns

Check if Session Needs Input

# Look for prompts
tmux capture-pane -t worker-3 -p | tail -10 | grep -E "❯|Yes.*No|proceed|permission"

Approve Claude Code Prompt

# Send 'y' and Enter
tmux send-keys -t worker-3 'y' Enter

# Or select numbered option
tmux send-keys -t worker-3 '2' Enter

Check All Sessions Status

for s in shared worker-2 worker-3 worker-4 worker-5 worker-6 worker-7 worker-8; do
  echo "=== $s ==="
  tmux capture-pane -t $s -p 2>/dev/null | tail -5
done

Send Task to Session

tmux send-keys -t worker-4 "Fix the bug in auth.js" Enter

Notes

• Use capture-pane -p to print to stdout (essential for scripting)
• -S - captures entire scrollback history
• Target format: session:window.pane (e.g., shared:0.0)
• Sessions persist across SSH disconnects