smux

$27

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

• tmux-bridge read <target> marks the pane as "read"

• tmux-bridge type/keys <target> checks for that mark — errors if you haven't read

• 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

Command

Description

Example

tmux-bridge list

Show all panes with target, pid, command, size, label

tmux-bridge list

tmux-bridge type <target> <text>

Type text without pressing Enter

tmux-bridge type codex "hello"

tmux-bridge message <target> <text>

Type text with auto sender info and reply target

tmux-bridge message codex "review src/auth.ts"

tmux-bridge read <target> [lines]

Read last N lines (default 50)

tmux-bridge read codex 100

tmux-bridge keys <target> <key>...

Send special keys

tmux-bridge keys codex Enter

tmux-bridge name <target> <label>

Label a pane (visible in tmux border)

tmux-bridge name %3 codex

tmux-bridge resolve <label>

Print pane target for a label

tmux-bridge resolve codex

tmux-bridge id

Print this pane's ID

tmux-bridge id

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)