Tmux Control Mode Protocol Documentation

Overview

Control mode is a text-based protocol activated with -C (or -CC for no echo). The client sends tmux commands on stdin; the server responds with structured output blocks and asynchronous notifications.

Input (Client → Server)

Commands are standard tmux commands terminated by newline. An empty line detaches the client.

Output Blocks (Command Responses)

%begin TIME COMMAND_NUM FLAGS
[output lines]
%end TIME COMMAND_NUM FLAGS       # success

or

%begin TIME COMMAND_NUM FLAGS
[output lines]  
%error TIME COMMAND_NUM FLAGS     # failure

• TIME - Unix timestamp
• COMMAND_NUM - Sequential command number
• FLAGS - Currently 0 or 1

Notifications (Asynchronous)

Identifiers

Character Escaping

Non-printable characters and backslashes are encoded as octal \XXX:

• Backslash → \134
• Newline → \012

Flow Control

• pause-after=N flag: Server sends %pause when buffering exceeds N seconds, client must send refresh-client -A pane:+ to resume
• Extended output: %extended-output includes age in milliseconds
• Max buffer age without pause-after: 5 minutes (then client disconnects)

Subscriptions

Subscribe to format changes:

refresh-client -B name:what:format

• what: %* (all panes), %N (specific pane), @* (all windows), @N (window), or empty (session)

Initialization (-CC mode)

Server sends DCS sequence: \033P1000p (7 bytes) on connect.

Tmux Data Model & Object Hierarchy

Entity Relationships

Server (singleton)
├── Sessions ($0, $1, ...)
│   └── Winlinks (index 0, 1, 2, ...)
│       └── → Window (shared reference)
├── Windows (@0, @1, ...) [global pool]
│   ├── Layout Tree (binary tree of cells)
│   └── Panes (%0, %1, ...) [leaf nodes]
├── Clients (terminal connections)
└── Session Groups (optional sync groups)

Core Entities

Session ($N)

A named, persistent context that survives client disconnection.

• Can exist with zero clients attached
• Multiple clients can attach to the same session

Window (@N)

A container of panes with a tiling layout. Windows are global (not session-specific).

• Same window can appear in multiple sessions (linked windows)
• Changes are visible to all sessions containing the window

Winlink (Session ↔ Window link)

The join table between sessions and windows, providing per-session metadata.

• When you "move" or "renumber" a window, you're changing the winlink's idx
• When no winlinks reference a window, it's destroyed

Pane (%N)

A terminal subdivision within a window, containing a pty and shell process.

• Leaf nodes in the layout tree
• Each has independent scrollback buffer

Layout Cell (Pane Arrangement)

A binary tree describing spatial arrangement of panes.

Layout Example:
┌─────────┬─────────┐
│         │  pane1  │
│  pane0  ├─────────┤
│         │  pane2  │
└─────────┴─────────┘

Tree:
LAYOUT_LEFTRIGHT
├── LAYOUT_WINDOWPANE (pane0)
└── LAYOUT_TOPBOTTOM
    ├── LAYOUT_WINDOWPANE (pane1)
    └── LAYOUT_WINDOWPANE (pane2)

Client

A connected terminal or control mode connection.

• A client attaches to at most one session at a time
• Control mode clients receive structured protocol output instead of terminal rendering

Session Group (Optional)

Synchronizes windows across multiple sessions.

• All sessions in a group share the same windows
• Creating/closing a window affects all grouped sessions
• Useful for multiple terminals showing identical window sets

ID Namespaces

IDs are never reused within a server lifetime—safe for tracking.

Key Implications for Control Mode

1. Track by ID, not index: Window indices change; @N IDs don't
2. Windows are shared: %layout-change @5 affects all sessions containing @5
3. Pane output is global: %output %3 is the same pane regardless of which session you're viewing
4. Clients are independent: Multiple control clients can attach to different sessions simultaneously

Tmux Data Model — Source References

All structures are in the tmux/tmux repository.

Core Structures

Control Mode Structures

Notification Handlers

Control mode notifications are implemented in control-notify.c:

Other Key Files

No — panes cannot be shared across multiple windows.

Each pane has a single struct window *window back-pointer (tmux.h#L1174), not a list:

struct window_pane {
    u_int         id;
    struct window *window;    // ← Single window, not multiple
    // ...
};

Comparison

Panes Are Moved, Not Linked

Commands like join-pane and break-pane move the pane by reassigning its window pointer (cmd-join-pane.c#L150):

TAILQ_REMOVE(&src_w->panes, src_wp, entry);   // Remove from source
src_wp->window = dst_w;                        // Reassign pointer
TAILQ_INSERT_AFTER(&dst_w->panes, ...);        // Add to destination

The pane exists in exactly one window at any time.