---
id: daily-smux
name: "smux"
url: https://skills.yangsir.net/skill/daily-smux
author: shawnpana
domain: ai-agent-orchestration-collaboration
tags: ["tmux", "terminal", "automation", "agent-communication", "devops-tools"]
install_count: 2000
rating: 4.30 (20 reviews)
github: https://github.com/shawnpana/smux
---

# smux

> 跨 tmux pane 通信和控制的统一接口，让 AI Agent 可在不同终端窗格间协作，无需手动切换窗口

**Stats**: 2,000 installs · 4.3/5 (20 reviews)

## Before / After 对比

### 跨窗格协作效率

**Before**:

需要在多个终端窗格间手动切换，复制粘贴命令和输出，协作流程被打断，一个任务需要频繁切换窗口 20 次以上

**After**:

AI Agent 自动在不同窗格间执行命令并传递数据，无需人工干预，跨窗格协作自动完成，零窗口切换

| Metric | Before | After | Change |
|---|---|---|---|
| 窗口切换次数 | 20次 | 0次 | -100% |
| 任务完成时间 | 15分钟 | 3分钟 | -80% |

## Readme

# 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.

- `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`)

Weekly Installs671Repository[shawnpana/smux](https://github.com/shawnpana/smux)GitHub Stars1.2KFirst Seen11 days agoSecurity Audits[Gen Agent Trust HubPass](/shawnpana/smux/smux/security/agent-trust-hub)[SocketPass](/shawnpana/smux/smux/security/socket)[SnykPass](/shawnpana/smux/smux/security/snyk)Installed oncodex666gemini-cli658cursor658opencode657cline656kimi-cli656

---
*Source: https://skills.yangsir.net/skill/daily-smux*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-smux/markdown*