Tmux on Opensource internals

tmux Parses Escape Sequences Fast: Four Boring Optimisations That Matter

Jay Hubbert — Sun, 11 Oct 2026 10:00:00 +0000

TL;DR: tmux’s parser has no clever trick in it. It’s a state machine with a transition cache, a bsearch(), a trie, and a width cache — four small optimisations, each of which swaps an expensive check for a cheaper one.

The hottest path in tmux is not the redraw. It’s the parser.

Every byte that any program in any pane produces goes through tmux’s own VT parser, and a yes or a cat of a large file will push megabytes through it per second. If the parser is slow, everything is slow.

So here’s how it’s built: a range-compressed state machine with a one-entry transition cache, a binary search over the CSI command table, a character trie for the other direction (terminal key sequences), and a Unicode width cache.

The parser: a state machine with tables

input.c is about 3800 lines, and the core of it is a table-driven state machine in the style of a real VT parser. There are ten states: ground, escape enter, escape intermediate, CSI enter, CSI parameter, CSI intermediate, OSC, DCS, APC, and the string-consumption states.

Each state has a list of transitions, and each transition is a range of bytes:

 c
 
 
struct input_transition {
	int			first;
	int			last;

	const struct input_state	*state;
	int			(*handler)(struct input_ctx *ictx);
};

Ranges rather than a 256-entry table per state, for memory: a transition is {int, int, pointer, pointer} — 24 bytes on 64-bit — and a full table would be 6 KB per state. With ranges, a state might have five transitions.

The parser core:

 c
 
 
/* Parse data. */
static void
input_parse(struct input_ctx *ictx, const u_char *buf, size_t len)
{
	struct screen_write_ctx		*sctx = &ictx->ctx;
	const struct input_state	*state = NULL;
	const struct input_transition	*itr = NULL;
	size_t				 off = 0;

	/* Parse the input. */
	while (off < len) {
		ictx->ch = buf[off++];

		/* Find the transition. */
		if (ictx->state != state ||
		 itr == NULL ||
		 ictx->ch < itr->first ||
		 ictx->ch > itr->last) {
			itr = ictx->state->transitions;
			while (itr->first != -1 && itr->last != -1) {
				if (ictx->ch >= itr->first &&
				 ictx->ch <= itr->last)
					break;
				itr++;
			}
			if (itr->first == -1 || itr->last == -1) {
				/* No transition? Eh? */
				fatalx("no transition from state");
			}
		}
		state = ictx->state;

The trick is the itr cache. The state machine remembers the transition it used last time, and only rescans the table if:

the state changed, or
the character is outside the range of the cached transition.

For a run of printable ASCII in the ground state, the first character scans the table and every subsequent character hits the cached transition. The scan is a linear walk over ranges, which for the ground state is a handful of comparisons.

The collect-buffer optimisation

The comment above screen_write_collect_end() is a nice piece of engineering honesty:

 c
 
 
		/*
		 * Any state except print stops the current collection. This is
		 * an optimization to avoid checking if the attributes have
		 * changed for every character. It will stop unnecessarily for
		 * sequences that don't make a terminal change, but they should
		 * be the minority.
		 */
		if (itr->handler != input_print)
			screen_write_collect_end(sctx);

The idea: tmux batches consecutive printable characters into a “collect buffer” so they can be written to the grid in one go. But collecting requires checking, for each character, whether the attributes have changed — which is the expensive part.

So instead of checking, the parser uses a proxy: if the transition isn’t the plain input_print handler, then the sequence is doing something (setting a colour, moving the cursor) and the collection ends.

That’s a conservative over-approximation. A sequence that doesn’t actually change attributes still ends the collection. But plain text is by far the common case, so the fast path stays fast.

Binary search over the CSI table

Once the parser reaches the CSI dispatch point, it has a final byte and a parameter string, and it needs to find the handler. The table is sorted and searched with bsearch():

 c
 
 
	entry = bsearch(ictx, input_csi_table, nitems(input_csi_table),
	 sizeof input_csi_table[0], input_table_compare);
	if (entry == NULL) {
		log_debug("%s: unknown '%c'", __func__, ictx->ch);
		return (0);
	}

with the comparator:

 c
 
 
static int
input_table_compare(const void *key, const void *value)
{
	const struct input_ctx		*ictx = key;
	const struct input_table_entry	*entry = value;
	if (ictx->ch != entry->ch)
		return (ictx->ch - entry->ch);
	return (strcmp(ictx->interm_buf, entry->interm));
}

The comparison is by final byte first, then by the intermediate string — which is how CSI ? ... h (private mode) gets distinguished from CSI ... h (set mode). The same pattern is used for the ESC dispatch table.

Bounded buffers

The parser context has fixed-size scratch buffers for the small parts of a sequence:

 c
 
 
	u_char				interm_buf[4];
	size_t				interm_len;

	u_char				param_buf[64];
	size_t				param_len;

#define INPUT_BUF_START 32
	u_char			 *input_buf;
	size_t				input_len;
	size_t				input_space;
	enum input_end_type		input_end;

	struct input_param		param_list[24];
	u_int				param_list_len;

The intermediate string of an escape sequence is at most 4 bytes and the parameter string at most 64. A sequence that exceeds them is discarded, not buffered — and that’s not just tidiness, it’s a denial-of-service defence. A hostile program inside a pane could otherwise send an endless CSI 111111111... and make tmux allocate without bound.

The one growable buffer is the OSC/DCS payload, and it’s bounded too:

 c
 
 
	while (ictx->input_len + 1 >= available) {
		available *= 2;
		if (available > input_buffer_size) {
			ictx->flags |= INPUT_DISCARD;
			return (0);
		}
	}

input_buffer_size defaults to INPUT_BUF_DEFAULT_SIZE (1 MB) and is configurable with the input-buffer-size option. When the buffer is discarded, the parser resets and waits for the next sequence — the rest of the garbage is dropped.

The buffer is also shrunk back when the parser returns to the ground state, so one huge OSC doesn’t permanently inflate memory.

The other direction: terminal key sequences

The parser above handles bytes flowing out of a program. The reverse direction — bytes coming from the user’s terminal, which may be an escape sequence rather than a keystroke — is handled by tty-keys.c.

The difficulty: the terminal sends a byte stream, and tmux has to decide whether ESC [ A is the up arrow, or the Escape key followed by [ and A. The answer depends on timing and on what tmux asked the terminal.

tmux stores terminal key sequences in a character trie, where each node has up to three children:

 c
 
 
/* A key tree entry. */
struct tty_key {
	char		 ch;
	key_code	 key;

	struct tty_key	*left;
	struct tty_key	*right;

	struct tty_key	*next;
};

The lookup is a simple binary-tree walk with a “next” pointer for the sequence continuation:

 c
 
 
/* Find the next node. */
static struct tty_key *
tty_keys_find1(struct tty_key *tk, const char *buf, size_t len, size_t *size)
{
	/* If no data, no match. */
	if (len == 0)
		return (NULL);

	/* If the node is NULL, this is the end of the tree. No match. */
	if (tk == NULL)
		return (NULL);

	/* Pick the next in the sequence. */
	if (tk->ch == *buf) {
		/* Move forward in the string. */
		buf++; len--;
		(*size)++;

		/* At the end of the string, return the current node. */
		if (len == 0 || (tk->next == NULL && tk->key != KEYC_UNKNOWN))
			return (tk);

		/* Move into the next tree for the following character. */
		tk = tk->next;
	} else {
		if (*buf < tk->ch)
			tk = tk->left;
		else if (*buf > tk->ch)
			tk = tk->right;
	}

	/* Move to the next in the tree. */
	return (tty_keys_find1(tk, buf, len, size));
}

The left/right pointers are a binary search tree keyed on the byte; the next pointer continues the sequence to the next trie. So the structure is a tree of trees, and the lookup is O(log n) per byte with no allocation.

Terminal replies (device attributes, colour reports, kitty graphics queries) are matched before the general key tree, via a small table of function pointers:

 c
 
 
/* Terminal replies, in the order they are checked. */
static const struct {
	key_code	key;
	int	 (*fn)(struct tty *, const char *, size_t, size_t *, int);
} tty_keys_replies[] = {
	{ KEYC_REPORT_CLIPBOARD, tty_keys_clipboard },
	{ KEYC_REPORT_SYNC, tty_keys_sync },
	{ KEYC_REPORT_DA, tty_keys_device_attributes },
	{ KEYC_REPORT_DA2, tty_keys_device_attributes2 },
	{ KEYC_REPORT_XDA, tty_keys_extended_device_attributes },
	{ KEYC_REPORT_COLOURS, tty_keys_colours1 },
	{ KEYC_REPORT_PALETTE, tty_keys_palette },
	{ KEYC_REPORT_WINSZ, tty_keys_winsz },

That ordering matters: a device attributes reply is ESC [ ? 6 2 ; 1 6 c, which would otherwise be an unknown key sequence.

The escape timeout

The ambiguity between Escape and a sequence prefix is resolved with a timer, and tmux’s timer is adaptive:

 c
 
 
	/* Get the time period. */
	delay = options_get_number(global_options, "escape-time");
	if (delay == 0)
		delay = 1;
	if ((tty->flags & TTY_BRACKETPASTE) &&
	 tty_keys_partial_paste_end(buf, len)) {
		log_debug("%s: increasing delay (partial paste end)", c->name);
		if (delay < 500)
			delay = 500;
	}
	if (tty->flags & (TTY_WAITFG|TTY_WAITBG) ||
	 tty->flags & (TTY_OSC52QUERY|TTY_WINSIZEQUERY) ||
	 (tty->flags & TTY_ALL_REQUEST_FLAGS) != TTY_ALL_REQUEST_FLAGS ||
	 !TAILQ_EMPTY(&c->input_requests)) {
		log_debug("%s: increasing delay (active query)", c->name);
		if (delay < 500)
			delay = 500;
	}

In two specific situations the delay is raised to at least 500 ms:

when the buffer ends with a partial bracketed paste end sequence (ESC [ 201 ~), and
when tmux has an outstanding terminal query and is waiting for a reply.

The second case is the interesting one. If tmux has just asked the terminal for its device attributes and the user presses Escape, the reply and the keystroke arrive in the same stream. Waiting a little longer makes it much more likely that the reply is consumed as a reply rather than being misinterpreted as a Meta-prefixed key.

The exponential-ish retry is handled too: when the timer expires without a match, the buffer is re-parsed with “no longer ambiguous” semantics, so a lone Escape eventually arrives as the Escape key.

There’s a matching problem on the reply side: an Escape immediately before a terminal reply must not be swallowed as Meta. That has its own regression test (regress/tty-keys-reply-escape.sh).

UTF-8 and the width cache

The last hot path is Unicode. Decoding UTF-8 incrementally is the easy part; the hard part is that wcwidth() isn’t cheap, and a screen full of emoji would call it thousands of times per second.

tmux keeps a cache of codepoint widths in a red-black tree:

 c
 
 
struct utf8_width_item {
	wchar_t				wc;
	u_int				width;
	int				allocated;

	RB_ENTRY(utf8_width_item)	entry;
};

seeded with a static table of a few hundred known cases:

 c
 
 
static struct utf8_width_item utf8_default_width_cache[] = {
	{ .wc = 0x0270A, .width = 2 },
	{ .wc = 0x0270B, .width = 2 },
	{ .wc = 0x1F1E6, .width = 1 },
	{ .wc = 0x1F1E7, .width = 1 },
	{ .wc = 0x1F1E8, .width = 1 },

The lookup happens before wcwidth() is called at all:

 c
 
 
/* Get width of Unicode character. */
static enum utf8_state
utf8_width(struct utf8_data *ud, int *width)
{
	struct utf8_width_item	*uw;
	wchar_t			 wc;

	if (utf8_towc(ud, &wc) != UTF8_DONE)
		return (UTF8_ERROR);
	uw = utf8_find_in_width_cache(wc);
	if (uw != NULL) {
		*width = uw->width;
		log_debug("cached width for %08X is %d", (u_int)wc, *width);
		return (UTF8_DONE);
	}
#ifdef HAVE_UTF8PROC
	*width = utf8proc_wcwidth(wc);

There are similar caches for the codepoint-to-utf8_data conversion (utf8_data_tree and utf8_index_tree), so a repeated character doesn’t have to be re-decoded.

The width is also packed into the character word itself rather than kept in a separate structure:

 c
 
 
#define UTF8_GET_SIZE(wc) ...
#define UTF8_GET_WIDTH(wc) ...
#define UTF8_SET_SIZE(wc, sz) ...
#define UTF8_SET_WIDTH(wc, wd) ...

so the width is available without dereferencing anything.

Why the widths are so complicated

The width rules are a mess of Unicode special cases, and tmux handles several of them explicitly:

Combining marks (utf8-combined.c) — a combining character is rendered on top of the previous cell, and does not advance the cursor.
Variation selectors — VS16 (U+FE0F) requests the emoji presentation, which is usually double-width. tmux has an option variation-selector-always-wide because the correct behaviour depends on the outer terminal, which tmux can’t always detect.
Regional indicators (flag emoji) — a pair of regional indicator symbols is one flag, so they combine.
Emoji modifiers (skin tones) — combine with the preceding emoji.
Private use area — where Powerline glyphs live, which have “ambiguous” width. The bundled utf8proc shim says:

 c
 
 
	if (cat == UTF8PROC_CATEGORY_CO) {
		/* The private use category is where powerline and similar
		 * codepoints are stored, they have "ambiguous" width - use 1. */
		return (1);
	}

Wrapping up

There’s no clever trick in the tmux parser. It’s a state machine with a transition cache, a binary search, a trie, and a width cache — four small, boring optimisations, each of which removes work from the innermost loop.

What makes it worth writing down is the shape of the optimisation. Each one replaces a check with a cheaper check:

Expensive	Cheap replacement
256-entry transition table per state	ranges + a one-entry cache
linear scan of the CSI table	`bsearch()`
`wcwidth()` per character	red-black tree of known widths
linear scan of key sequences	binary search tree per node
attribute check per collected character	“is this the print handler?”

Worth internalizing: never do the expensive check when a cheaper one is sufficient, and make the cheap one the default path. That’s the whole story of tmux’s input performance.

tmux Splits the Terminal into Panes: A Tree, Not a Geometry Problem

Jay Hubbert — Tue, 06 Oct 2026 11:00:00 +0000

TL;DR: The hard part of tmux’s pane splitting isn’t the geometry — it’s serialisability. The layout is a tree of three node types, distributed with a divide-and-remainder algorithm, and dumped to JSON so it can be saved, restored, applied elsewhere and shared between servers.

Splitting a terminal into panes sounds like a geometry problem, and it is — but the hard part isn’t the geometry. It’s that the layout has to be serialisable, so it can be saved when you detach, restored when you come back, applied to a different window, and shared between servers.

tmux’s layout system is a tree of cells with three node types, a divide-and-remainder algorithm for distributing space, and a JSON serialisation format.

The tree

tmux.h defines exactly three layout types:

 c
 
enum layout_type { LAYOUT_LEFTRIGHT, LAYOUT_TOPBOTTOM, LAYOUT_WINDOWPANE };

LAYOUT_LEFTRIGHT — a node split vertically into children side by side,
LAYOUT_TOPBOTTOM — a node split horizontally into children stacked,
LAYOUT_WINDOWPANE — a leaf holding one pane.

Each struct layout_cell has a geometry (sx, sy, xoff, yoff) and a list of children. The tree is a general n-ary tree, not a binary one, so a row of three panes is one node with three children rather than a chain of two.

 c
 
 
struct layout_cell {
	struct layout_cell	*parent;

	enum layout_type		 type;
	struct grid_cell		 g;

	TAILQ_HEAD(layout_cells, layout_cell) cells;
	TAILQ_ENTRY(layout_cell)	 entry;

	struct window_pane	*wp;
	int			 flags;
#define LAYOUT_CELL_FLOATING 0x1
};

The LAYOUT_CELL_FLOATING flag is what makes a floating pane work: it marks a cell as not participating in the tiling. layout_cell_is_tiled() explicitly excludes it:

 c
 
 
	int	is_floating = lc->flags & LAYOUT_CELL_FLOATING;
	return is_leaf && !is_floating;

So a floating pane is a cell in the same tree, but the tiling algorithms skip it, and it has its own position, size and z-index.

The seven presets

layout-set.c has a table of preset arrangements:

 c
 
 
static const struct {
	const char	*name;
	void	 	(*arrange)(struct window *);
} layout_sets[] = {
	{ "even-horizontal", layout_set_even_h },
	{ "even-vertical", layout_set_even_v },
	{ "main-horizontal", layout_set_main_h },
	{ "main-horizontal-mirrored", layout_set_main_h_mirrored },
	{ "main-vertical", layout_set_main_v },
	{ "main-vertical-mirrored", layout_set_main_v_mirrored },
	{ "tiled", layout_set_tiled },
};

The lookup does prefix matching, so select-layout -t even is ambiguous between even-horizontal and even-vertical and is an error, while select-layout -t even-h works.

main-horizontal and friends put one pane in a large region and the rest in a strip. The size of the main region comes from an option specified as a percentage:

 c
 
 
	s = options_get_string(w->options, "main-pane-height");
	mainh = args_string_percentage(s, 0, sy, sy, &cause);

so main-pane-height 60% and main-pane-height 20 (absolute cells) both work.

tiled is the interesting one. It’s recursive: it splits the window alternately vertically and horizontally depending on the aspect ratio, and calls layout_resize_adjust() to make sure no pane ends up unusably small. It’s the layout that most resembles a “just divide the screen up” expectation.

Spreading the space

The core algorithm is layout_spread_cell():

 c
 
 
/* Spread out cells inside a parent cell. */
int
layout_spread_cell(struct window *w, struct layout_cell *parent)
{
	struct layout_cell	*lc, *root = w->layout_root;
	u_int			 number, each, size, this, remainder;
	int			 change, changed, status;

	number = 0;
	TAILQ_FOREACH (lc, &parent->cells, entry)
		if (layout_cell_is_tiled(lc) || layout_cell_has_tiled_child(lc))
			number++;
	if (number <= 1)
		return (0);
	status = window_get_pane_status(w);

	if (parent->type == LAYOUT_LEFTRIGHT)
		size = parent->g.sx;
	else if (parent->type == LAYOUT_TOPBOTTOM) {
		if (layout_add_horizontal_border(root, parent, status))
			size = parent->g.sy - 1;
		else
			size = parent->g.sy;
	} else
		return (0);
	if (size < number - 1)
		return (0);
	each = (size - (number - 1)) / number;
	if (each == 0)
		return (0);

	/*
	 * Remaining space after assigning that which can be evenly
	 * distributed.
	 */
	remainder = size - (number * (each + 1)) + 1;

The arithmetic is worth unpacking:

size is the space available, minus one per border if the parent has horizontal borders.
each = (size - (number - 1)) / number — divide the space, having reserved one cell for each of the number - 1 borders between cells.
remainder = size - (number * (each + 1)) + 1 — the space left over after giving every cell each + 1 cells (the extra one accounts for the border that was reserved on the right of each cell).

The remainder is then handed out one cell at a time to the first panes, which is why even-horizontal with a window 81 columns wide and three panes gives 27, 27, 26 rather than 27, 27, 27 with a gap.

The border handling is the subtle part. A pane status line can be either above or below the pane, and whether there is a horizontal border depends on the layout, not just on the option. layout_add_horizontal_border() figures that out, and the whole calculation shifts by one depending on the answer. Getting this wrong is how you end up with a one-column gap in a layout.

Serialisation: the JSON layout string

The layout has to survive a round trip through a string, because:

select-layout saves a layout string and applies it later,
tmux list-windows shows the layout so you can copy it,
join-pane and move-pane move panes between windows with layouts,
and the layout is part of what makes a session portable between servers.

The current format is JSON. The documentation is at the top of layout-custom.c:

text

 * Layouts can be represented as strings in a JSON format (v2). The version 1
 * format will be removed in the future and should no longer be used.
 *
 * The current (v2) format is JSON. The top level has two keys:
 * "V": version number, currently 2
 * "L": root layout cell
 *
 * Each cell is an object with:
 * "t": cell type:
 * "h": horizontal
 * "v": vertical
 * "p": pane
 * "w": cell width
 * "h": cell height
 * "x": horizontal position
 * "y": vertical position
 *
 * If the cell is a node cell (with child cells), it additionally has:
 * "c": array of child cells
 *
 * If the cell is a leaf cell (that is, containing a pane and no child cells),
 * it additionally has:
 * "I": pane ID as %n (currently ignored on parse)
 * "l": index into last panes list if visited and not the active pane
 * "a": true if the active pane
 * "i": pane index
 * "z": z-index, if a floating pane
 */

The dump is a direct recursion:

 c
 
 
/* Append information for a single cell in a JSON (v2) format. */
static int
layout_append_v2(struct layout_cell *lc, struct layout_string *ls)
{
	...
	layout_string_write(ls, "{\"t\":\"%c\",\"w\":%u,\"h\":%u,\"x\":%d"
	 ",\"y\":%d", c, lc->g.sx, lc->g.sy, lc->g.xoff, lc->g.yoff);
	if (type != LAYOUT_WINDOWPANE) {
		layout_string_write(ls, ",\"c\":[");
		n = 0;
		TAILQ_FOREACH(lcchild, &lc->cells, entry) {
			if (layout_append_v2(lcchild, ls) != 0)
				return (-1);
			layout_string_write(ls, ",");
			n++;
		}
		if (n == 0)
			return (-1);
		ls->dat[--ls->size] = '\0'; /* removing trailing comma */
		layout_string_write(ls, "]");
	} else {
		...
		if (wp == wp->window->active)
			layout_string_write(ls, ",\"a\":true");
		else if (window_pane_last_index(wp, &i) == 0)
			layout_string_write(ls, ",\"l\":%u", i);
		...
		if (lc->flags & LAYOUT_CELL_FLOATING) {
			z = layout_cell_zindex(lc);
			layout_string_write(ls, ",\"z\":%u", z);
		}
		layout_string_write(ls, ",\"I\":\"%%%u\"", wp->id);
	}

Note the manual comma handling — ls->dat[--ls->size] = '\0' removes the trailing comma. tmux isn’t using a JSON library; it’s writing JSON by hand, because it needs to produce it incrementally without allocating a tree of JSON values.

The top-level wrapper is:

 c
 
 
	if (~flags & LAYOUT_CUSTOM_OLD_FORMAT)
		xasprintf(&out, "{\"V\":2,\"L\":%s}", layout_string.dat);
	else {
		xasprintf(&out, "%04hx,%s", layout_checksum(layout_string.dat),
		 layout_string.dat);
	}

So a v2 layout looks like:

text

{"V":2,"L":{"t":"h","w":120,"h":40,"x":0,"y":0,"c":[
 {"t":"p","w":60,"h":40,"x":0,"y":0,"a":true,"i":0,"I":"%1"},
 {"t":"p","w":59,"h":40,"x":61,"y":0,"i":1,"I":"%2"}]}}

The old format

Version 1 was a string with a checksum:

text

0123,80x24,0,0,1

with {} for a left-right split and [] for a top-bottom split. The checksum is a rotate-and-add:

 c
 
 
	xasprintf(&out, "%04hx,%s", layout_checksum(layout_string.dat),
	 layout_string.dat);

and it’s verified on parse:

 c
 
 
	if (csum != layout_checksum(input)) {
		*pctx->cause = xstrdup("invalid layout checksum");
		return (-1);
	}

The checksum exists because the v1 format had no way to mark the end of the string, so a truncated or corrupted layout could be parsed as something valid. The v1 parser is also depth-limited:

 c
 
 
/* Maximum nesting depth for version 1 layouts. */
#define LAYOUT_V1_MAX_DEPTH 1000

which exists because the format is recursive and the input is untrusted. There’s a dedicated fuzzer for this: fuzz/layout-fuzzer.c.

Parsing is not just parsing

layout_parse() does considerably more than decode the string. After decoding it:

closes the bottom-right cells until the number of cells matches the number of panes,
repairs a historically-wrong root size,
assigns the panes into the cells.

The “closes the bottom-right cells” step is a compatibility hack: older versions of tmux produced layouts with a different cell count than the pane count, and rather than reject them, tmux patches them up.

Resizing

Resizing a window is resize_window() in resize.c:

 c
 
 
	/* If the window is zoomed, unzoom. */
	zwp = window_zoomed_pane(w);
	if (zwp != NULL) window_unzoom(w, 1);
	/* Resize the layout first. */
	layout_resize(w, sx, sy);
	/* Resize the window, it can be no smaller than the layout. */
	if (sx < w->layout_root->g.sx) sx = w->layout_root->g.sx;

The order matters: the layout is resized first, and then the window is allowed to grow to match it if the layout asked for more.

layout_resize() walks the tree and adjusts the split points. The interesting constraint is that resizing must not change the proportions the user chose — a user who made a pane 30 columns wide at 100 columns total wants it 36 columns wide at 120, not 30. layout_resize_adjust() implements that by moving the boundary between two cells by the same proportion.

There’s a minimum size check (layout_resize_check()) so a pane can’t be squeezed to nothing.

Window sizing policy

Separately from the layout, there’s the question of how big a window should be when several clients of different sizes are attached. That’s resize.c’s recalculate_size(), and it honours the window-size option:

latest — use the size of the most recent client,
largest — use the largest,
smallest — use the smallest,
manual — do not resize automatically.

And aggressive-resize, which controls whether a window is resized as soon as one client resizes, or only when the largest client resizes.

This is the part that tmux gets wrong most often in users’ minds. A window is not the size of the terminal. A window is the size that the layout requires, and the layout is sized to fit the window.

Wrapping up

The design here is a small, clean abstraction — a tree of three node types — with a JSON serialisation that makes the whole thing portable. The complexity is concentrated in three places:

the border arithmetic, which shifts every calculation by one cell depending on the layout,
the compatibility fixes on parse, which exist because old versions produced layouts that are technically wrong but practically usable, and
the resize proportions, which must preserve user intent rather than just fill the space.

Each of those is a case where the “obvious” implementation produces a layout that’s subtly off by one. The only defence is a regression test that checks the exact geometry — and there are a lot of those in regress/.

tmux Sanitises Window Names Against Injection

Jay Hubbert — Fri, 02 Oct 2026 08:30:00 +0000

TL;DR: clean_name() is tmux’s one defence against name-based injection, and it works by encoding rather than filtering: it stores names in a form where the dangerous characters are unrepresentable, rather than keeping a blocklist of bad names.

Window names in tmux are not just strings. They end up in status lines, in control-mode notifications, in #{window_name} format expansions, and in hook commands that are expanded and then parsed as commands. A window name containing #{...} or a quote is a potential injection point.

The defence is a single function called clean_name(). Its history is a good illustration of how injection defence actually evolves: patch, get bypassed, patch again, get bypassed again.

The function

tmux.c:

 c
 
 
char *
clean_name(const char *name, int untrusted)
{
	char	*copy, *cp, *new_name;

	if (!utf8_isvalid(name))
		return (NULL);
	copy = xstrdup(name);
	for (cp = copy; *cp != '\0'; cp++) {
		if (untrusted && cp[0] == '#' && cp[1] == '(')
			*cp = '_';
	}
	utf8_stravis(&new_name, copy, VIS_OCTAL|VIS_CSTYLE|VIS_TAB|VIS_NL);
	free(copy);
	return (new_name);
}

Three things happen:

UTF-8 validation. An invalid sequence is rejected outright, and the caller gets NULL. This isn’t cosmetic: utf8_stravis() walks the string with the UTF-8 decoder, and a malformed string would desynchronise the walk.
#( → _( for untrusted names. The untrusted flag marks names that came from inside a pane — a program that set the terminal title via OSC 0 or OSC 2. A title is the one place where a hostile process can put arbitrary bytes into a name, so #( is defanged there.
vis(3)-style escaping. utf8_stravis() escapes everything that isn’t plainly printable.

Why `vis(3)` and not a hand-rolled check

tmux uses the BSD vis(3) family — bundled in compat/vis.c and compat/unvis.c — because “escape the dangerous characters” is a problem with a long tail, and vis has already enumerated the tail.

The important part is what happens to the characters that are not printable. vis()’s definition of visibility (compat/vis.c) is:

 c
 
 
#define	isvisible(c,flag)						\
	(((c) == '\\' || (flag & VIS_ALL) == 0) &&			\
	(((u_int)(c) <= UCHAR_MAX && isascii((u_char)(c)) &&		\
	(((c) != '*' && (c) != '?' && (c) != '[' && (c) != '#') ||	\
		(flag & VIS_GLOB) == 0) && isgraph((u_char)(c))) ||	\

The #, *, ? and [ exclusions only apply when VIS_GLOB is set. tmux doesn’t set it, so those characters are ordinary visible characters and are stored as-is. # in a window name survives as #.

What does get escaped is everything non-printable, because VIS_CSTYLE and VIS_OCTAL together make vis() fall through to its encoding branches:

 c
 
 
	if (flag & VIS_CSTYLE) {
		switch(c) {
		case '\n':
			*dst++ = '\\';
			*dst++ = 'n';
			goto done;
		case '\r':
			*dst++ = '\\';
			*dst++ = 'r';
			goto done;

so a newline in a name becomes the two characters \ and n, a tab becomes \t, a carriage return becomes \r, and any other non-printable byte becomes an octal escape such as \001. That matters for the control-mode protocol, where a raw newline in a %%window-renamed notification would forge a protocol line.

The consequence for format injection is subtler than it looks. A window name can contain #{, and it can contain #(. Neither is re-expanded when the name is substituted into a status line, because a format expansion’s result isn’t itself expanded — only the E and T modifiers re-expand. So the #{...} in a name is inert text. The #( in a name is not inert, because a format can contain a shell job, and that’s exactly what the explicit rewrite in clean_name() is for.

 c
 
 
	if (flag & VIS_CSTYLE) {
		switch(c) {
		case '\n':
			*dst++ = '\\';
			*dst++ = 'n';
			goto done;
		case '\r':
			*dst++ = '\\';
			*dst++ = 'r';
			goto done;

so a newline in a name becomes the two characters \ and n. That is important for the control-mode protocol, where a raw newline in a %%window-renamed notification would forge a protocol line.

VIS_NL is in the flag list too, and it’s worth being precise about what it does: in BSD vis, VIS_NL means “also encode newline characters” — it is an instruction to encode, not an exemption. Combined with VIS_CSTYLE the newline comes out as \n.

Where it is applied

clean_name() is called from a small, deliberate set of places:

Call site	Context
`window_set_name()` (`window.c`)	window renames, `untrusted` flag passed through
`screen.c:242`	pane title from OSC
`screen.c:256`	pane path from OSC 7
`input.c:3284`	OSC title parsing, `untrusted = 1`
`cmd-rename-session.c:63`	session rename
`cmd-new-window.c:92`, `cmd-new-session.c`	`-n` names
`names.c:169`	the shared “find next unused name” helper
`paste.c:232`, `paste.c:300`	paste buffer names
`cmd-break-pane.c:173`	broken-pane names

The untrusted distinction shows up only in the OSC title path. A name set by a command (rename-window foo) keeps its # characters, because a user typing # into a window name is not an attack. A name set by a program inside a pane has #( rewritten to _(.

Note that the stored name is the sanitised one — there’s no separate “display” form that gets un-escaped. A name that contained a newline is stored with a literal backslash-n in it and displayed that way. That keeps the invariant simple: whatever is in w->name is safe to interpolate into a status line, a control-mode notification or a format.

The history

The git log tells the story of how this went wrong, repeatedly.

d339ab51 — “Sanitize pane titles and window and session names more consistently and strictly, prevents C0 characters and other nonvisible characters causing problems. Reported (with a different fix) by Chris Monardo in GitHub issue 4999.”

Before this, some names were validated and some were not. C0 characters in a window name could produce all kinds of weirdness in the status line and in control-mode output.

64e83caf / eb653314 — “Be more strict about what names and titles we allow and reject them immediately when possible, but allow # again for those directly set by commands (but not escape sequences). From Barrett Ruth in GitHub issue 5175.”

This is the interesting one. The strict version rejected names containing #. That was too strict: users legitimately want # in window names (vim #1, ssh box#2), and the fix was to allow # where it’s harmless while keeping it defanged where it isn’t — the untrusted flag.

746dd91e — “Sanitize paste buffer names in paste_set and paste_rename, GitHub issue 5032 from Barrett Ruth.”

Paste buffer names were a separate hole. They’re format-expanded in places, and they weren’t being cleaned. Fixed by routing them through clean_name() too.

518fcf7e — “Do not sanitize title when popping it from stack, also add a limit to number of pushed titles.”

Terminals push and pop titles with OSC 9/10 and OSC 133. Popping a title restores a previously sanitised title, so sanitising again would double-escape it. The fix was to skip sanitisation on pop, and to cap the title stack so a program can’t grow it without bound.

That last one is a nice illustration of the general tension: sanitisation isn’t idempotent, and a system that both stores and restores sanitised values has to know which side of the boundary each value came from.

What is not defended

A few things to be clear about:

Session and window names aren’t restricted in length or character set beyond “valid UTF-8”. They can contain spaces, quotes, semicolons. The defence is escaping, not rejection.
The command parser’s ${VAR} splicing is a separate issue. A name is escaped; an environment variable isn’t. See How tmux Format Expansion Runs Shell Commands.
Control-mode output from commands isn’t escaped. Names are; command output isn’t. See tmux Control Mode Is an Unauthenticated Command Channel.
A name isn’t escaped for the shell. run-shell "echo #{window_name}" will expand the name and then hand the result to /bin/sh -c. The name is escaped for tmux’s format and control-mode syntaxes, not for sh.

That last one is the most common way people get burned. If a window name comes from an untrusted source and you interpolate it into a shell command, you need shell quoting. cmd_template_replace() provides %% and %1 for exactly this, and they have different escaping rules:

 c
 
 
/*
 * Replace the first %% or any %idx in template by s. %% is intended for use in
 * single quotes, so ' is escaped. %%% and %idx% are for double quotes, so a
 * list of special characters is escaped. %idx is left unescaped.
 */

%1 is deliberately not escaped, on the assumption you’ll quote it yourself. That’s the trap: %1 inside double quotes is fine, %1 inside single quotes isn’t, and %% inside single quotes escapes the quote character but isn’t safe in double quotes.

Wrapping up

clean_name() is a good example of defence that works by encoding rather than filtering. tmux doesn’t maintain a blocklist of dangerous window names. It stores names in a form where the dangerous characters are unrepresentable.

A blocklist would have to know about #{, #(, newlines, quotes, ;, backticks, $(, and every future syntax tmux adds. An encoder only has to know about the characters that aren’t printable — plus the one piece of syntax that genuinely has to be spelled out, #(, which is why that one is handled by hand in clean_name() rather than by vis.

The cost is that the stored and displayed forms are the same, which is simple, but that sanitisation isn’t idempotent. Anything that stores a sanitised value and later restores it — the terminal title stack — has to know which side of the boundary each value came from. That bug is exactly what commit 518fcf7e fixed.

Why tmux Needs Its Own Terminal Emulator

Jay Hubbert — Mon, 28 Sep 2026 15:00:00 +0000

TL;DR: ncurses assumes one application owns one terminal. A multiplexer owns N screens and has to render them into one terminal without the terminal knowing. That one mismatch breaks every assumption ncurses makes, so tmux keeps ncurses for terminfo and writes its own emulator.

tmux links against ncurses. It uses ncurses for exactly one thing: reading the terminfo database.

Everything else — parsing escape sequences, maintaining the screen, tracking the cursor, handling the alternate screen, mouse reporting, bracketed paste — is tmux’s own code, about 8000 lines of it across input.c, screen.c, screen-write.c and grid.c.

This article is about why.

The reason in one sentence

A terminal program owns one screen. A multiplexer owns N screens and has to render them into one terminal — and it has to do that without the terminal knowing that there were N.

That single requirement breaks every assumption ncurses makes.

What ncurses gives you

ncurses is a screen management library. You call initscr(), move(), addstr(), refresh(), and it maintains a virtual screen (curscr) and an optimisation structure (newscr) that lets it compute the minimal set of cursor movements and updates to bring the physical terminal up to date.

Its model is:

one terminal,
one screen buffer,
one cursor,
the application writes to the terminal through the library.

That model is right for vi, lynx and top. It’s wrong for tmux.

The four requirements ncurses cannot meet

1. Several independent screens

A tmux window with four panes has four independent screens, each with its own cursor position, its own scroll region, its own modes, its own alternate screen buffer, its own title.

ncurses has exactly one curscr. There’s no way to have four and render them into one terminal.

2. The terminal is not the target

A multiplexer’s output goes to a terminal that the multiplexer doesn’t control and can’t query. The bytes the multiplexer writes to the outer terminal are its decision, made by comparing what it wants on screen with what it last sent.

ncurses’ optimisation is based on knowing the physical screen’s contents and being the only writer to it. tmux has to build that model itself, because it needs to know what each pane’s screen looks like before it decides how to composite them.

3. The application and the multiplexer both think they own the screen

A program running in a pane believes it has the whole terminal. It uses the alternate screen, sets scroll regions, moves the cursor to absolute positions, and enables mouse reporting.

tmux has to model all of that per pane so that when it renders the pane into a region of the outer terminal, it can translate “move to 10,5” into “move to 10+offset, 5+offset”.

4. The multiplexer is itself a terminal user

tmux’s own client is a terminal program as far as the outer terminal is concerned. It has to deal with terminfo, feature detection and the limitations of whatever terminal the user happens to have. Using ncurses for screen management and implementing a VT parser internally would mean two terminal emulators in one process, fighting over the cursor.

So tmux uses ncurses for terminfo only. The CHANGES file records the decision:

“Stop using ncurses variables and instead build a table of the codes we want into an array for each terminal type. This makes the code a little untidy in places but gets rid of the awful global variables and calling setterm all the time, and shoves all the ncurses-dependent mess into a single file, tty-term.c. It also allows overriding single terminal codes, this is used to fix rxvt on some platforms (where it is missing dch) and in future may allow user customisation a la vim.”

That was in 2009. Before that, tmux used ncurses’ setterm() and its global variables.

What tmux implements instead

The parser

input.c implements a state machine that handles the VT escape sequence families:

CSI — cursor movement, erasing, inserting and deleting, scrolling regions, SGR attributes, device status reports, window manipulation, repeat (CSI b), and the private modes.
ESC — DECSC/DECRC (save/restore cursor), DECALN, IND, NEL, RI, RIS, character set selection.
OSC — window title, palette queries, clipboard, hyperlinks, shell integration marks, notifications.
DCS — Sixel images, DECRQSS queries.
APC — kitty graphics, and passthrough.

The mode handling is a good illustration of the scale of it:

 c
 
 
		case 1000:
			screen_write_mode_clear(sctx, ALL_MOUSE_MODES);
			screen_write_mode_set(sctx, MODE_MOUSE_STANDARD);
			break;
		case 1002:
			screen_write_mode_clear(sctx, ALL_MOUSE_MODES);
			screen_write_mode_set(sctx, MODE_MOUSE_BUTTON);
			break;
		case 1003:
			screen_write_mode_clear(sctx, ALL_MOUSE_MODES);
			screen_write_mode_set(sctx, MODE_MOUSE_ALL);
			break;
		case 1004:
			screen_write_mode_set(sctx, MODE_FOCUSON);
			break;
		case 1005:
			screen_write_mode_set(sctx, MODE_MOUSE_UTF8);
			break;
		case 1006:
			screen_write_mode_set(sctx, MODE_MOUSE_SGR);
			break;
		case 47:
		case 1047:
			screen_write_alternateon(sctx, gc, 0);
			break;
		case 1049:
			screen_write_alternateon(sctx, gc, 1);
			break;
		case 2004:
			screen_write_mode_set(sctx, MODE_BRACKETPASTE);
			break;

Mouse reporting has four encodings (normal, button-event, any-event, and SGR), each with an optional UTF-8 variant, plus focus reporting and bracketed paste. A multiplexer has to track all of that per pane, because each pane’s program has its own idea of what mouse mode it wants.

The screen model

struct screen (screen.c) holds a grid, a cursor, a set of mode bits, a scroll region (rupper/rlower), a title stack, a selection, and — this is the part ncurses has no concept of — an alternate screen buffer:

 c
 
 
/*
 * Enter alternative screen mode. A copy of the visible screen is saved and
 * the history is not updated.
 */
int
screen_alternate_on(struct screen *s, struct grid_cell *gc, int cursor)
{
	u_int		 sx, sy;
	if (SCREEN_IS_ALTERNATE(s))
		return 0;
	sx = screen_size_x(s);
	sy = screen_size_y(s);

	s->saved_grid = grid_create(sx, sy, 0);
	grid_duplicate_lines(s->saved_grid, 0, s->grid, screen_hsize(s), sy);
	...
	s->saved_flags = s->grid->flags;
	s->grid->flags &= ~GRID_HISTORY;

	return 1;
}

tmux keeps its own copy of the alternate screen, with its own history suppressed. The terminal’s smcup/rmcup sequences are a visual convenience; the truth lives in tmux.

That’s essential: when you resize a window with vim in the alternate screen, tmux has to know what was on the alternate screen before the resize, and it has to be able to reconstruct it.

The write path

screen-write.c is the half of the emulator that turns “the application wrote these bytes” into “the grid now looks like this”. It’s about 3300 lines.

The interesting part is the collect buffer: consecutive plain characters are batched into one item, and the batch is trimmed when a later write overlaps it:

 c
 
 
/* Write cell data, collecting if necessary. */
void
screen_write_collect_add(struct screen_write_ctx *ctx,
 const struct grid_cell *gc)
{
	...
	collect = 1;
	if (gc->data.width != 1 || gc->data.size != 1 || *gc->data.data >= 0x7f)
		collect = 0;
	else if (gc->flags & GRID_FLAG_TAB)
		collect = 0;
	else if (gc->attr & GRID_ATTR_CHARSET)
		collect = 0;
	else if ((~s->mode & MODE_WRAP) &&
	 s->cx + ctx->item->used >= sx - 1)
		collect = 0;
	else if (s->mode & MODE_INSERT)
		collect = 0;
	else if (s->sel != NULL)

The collect buffer exists for a specific reason: to decide whether a cell needs to be drawn at all. The alternative — writing every cell one at a time — would make it impossible to know what the terminal currently shows, and therefore impossible to skip unchanged cells. It’s the mechanism behind the diffing described in How tmux Redraws Only What Changed.

The scrollback and reflow

ncurses has no scrollback at all. tmux keeps a history of lines above the visible area, trims it to history-limit, and — this is the hard part — reflows it when the window is resized, so that wrapped paragraphs are rewrapped rather than left ragged.

grid_reflow(), grid_reflow_join() and grid_reflow_split() in grid.c implement text reflow over a grid of fixed-width cells. It has to recognise which lines are continuations of a wrapped line and which are genuinely new lines, and it has to handle wide characters at the wrap boundary.

The performance angle

Doing it yourself is also faster, in a specific way. ncurses’ refresh() is a general-purpose screen update: it diffs two full-screen buffers. tmux’s renderer diffs a pane’s grid against what it last sent to that client, which is a much smaller problem, and it can do it at a finer granularity (spans, damage rectangles, per-cell).

The ncurses model would also force tmux to give ncurses a full-screen buffer of the composited image, which it doesn’t have — the composite is assembled at draw time from four independent pane grids.

The cost

Writing your own terminal emulator isn’t free:

Every terminal bug becomes your bug. If a program does something tmux’s parser doesn’t understand, the pane’s screen diverges from what the program thinks it drew. tmux has to keep up with a moving target of escape sequences, and it has to decide what to do with the ones it doesn’t implement (usually: ignore them, but sometimes: emulate them).
The parser is a security boundary. A hostile program inside a pane is feeding untrusted bytes to the parser. Hence the bounded buffers, the fuzzing harnesses (fuzz/input-fuzzer.c), and the careful handling of the OSC/DCS payload length.
Unicode is a swamp. Character widths, combining marks, variation selectors, emoji modifiers — see How tmux Parses Escape Sequences Fast.
Terminal capability detection is a swamp. See How tmux Works Around Terminal Bugs.

Wrapping up

The general lesson is that a library which embeds an assumption about who owns the resource can only be reused when that assumption holds.

ncurses assumes “one application, one terminal”. That’s the right assumption for a text editor and the wrong one for a multiplexer, a pager with a status bar, a terminal-based debugger, or anything that wants to render two independent screens into one device.

tmux’s decision to reimplement the screen model — while keeping ncurses for the part ncurses is genuinely good at (the terminfo database) — is the kind of separation of concerns that only pays off once you understand exactly which assumption is blocking you.

tmux Control Mode Is an Unauthenticated Command Channel

Jay Hubbert — Sat, 19 Sep 2026 09:00:00 +0000

TL;DR: tmux -C gives you a scriptable protocol with zero authentication — anything that can open the socket can run run-shell. Worse, command output is written into the stream verbatim, so a program that prints a line starting with % can forge a notification in your client.

tmux -C puts tmux into control mode: instead of drawing a screen, the client speaks a line protocol and gets structured events back. It’s the mechanism behind tmux integrations in editors, status bars, scripts and CI systems.

It’s also, in its current form, an unauthenticated remote command channel with a subtle framing problem.

This article is about how control mode works, what it will let you do, and where the sharp edges are.

What control mode looks like

A control-mode client is an ordinary tmux client that happens to have CLIENT_CONTROL set instead of CLIENT_TERMINAL. The flag is set in tmux.c:

 c
 
 
	case 'C':
		if (flags & CLIENT_CONTROL)
			flags |= CLIENT_CONTROLCONTROL;
		else
			flags |= CLIENT_CONTROL;
		break;

-C is control mode. -CC is “control control”: the client puts its own terminal into a raw mode and wraps the protocol in ESC P 1000 p ... ESC \ so that a control client’s output can be embedded in a terminal without being interpreted.

The protocol itself is not a separate wire format. It’s the ordinary client/server IPC (imsg over the UNIX socket), plus a text protocol layered on top. tmux-protocol.h has no control-mode messages at all; everything goes through MSG_COMMAND.

The grammar is documented in the man page under CONTROL MODE, and the implementation is in control.c (about 1100 lines) plus control-notify.c.

Reading commands

The whole command surface is this function (control.c):

 c
 
 
/* Control client input callback. Read lines and fire commands. */
static void
control_read_callback(__unused struct bufferevent *bufev, void *data)
{
	struct client		*c = data;
	struct control_state	*cs = c->control_state;
	struct evbuffer		*buffer = cs->read_event->input;
	char			*line, *error;
	struct cmdq_state	*state;
	enum cmd_parse_status	 status;

	for (;;) {
		line = evbuffer_readln(buffer, NULL, EVBUFFER_EOL_LF);
		if (line == NULL)
			break;
		log_debug("%s: %s: %s", __func__, c->name, line);
		if (*line == '\0') { /* empty line detach */
			free(line);
			c->flags |= CLIENT_EXIT;
			break;
		}

		state = cmdq_new_state(NULL, NULL, CMDQ_STATE_CONTROL);
		status = cmd_parse_and_append(line, NULL, c, state, &error);
		if (status == CMD_PARSE_ERROR)
			cmdq_append(c, cmdq_get_callback(control_error, error));
		cmdq_free_state(state);

		free(line);
	}
}

Every line is parsed with the same parser as an interactive tmux command line and appended to the command queue. There is no allow-list of “safe” control-mode commands. run-shell, source-file, new-session, kill-server — all of it is available.

That’s the point of the design: control mode is meant to be a complete alternative interface, not a restricted one. The restriction story is the server ACL, and it’s described in How tmux Secures its UNIX Socket. Short version: if you can open the socket, you can run commands. A read-only ACL entry limits you to commands flagged CMD_READONLY and disables #() shell jobs in formats.

The reply framing

Replies are wrapped in a guard block so a client can associate output with the command that produced it:

text

%begin 1712345678 0 1
%output %3 some text
%end 1712345678 0 1

The guard lines are emitted from exactly one place, which is deliberate (control.c):

 c
 
 
/*
 * Write a %begin, %end or %error guard around a command's output. This is
 * the only place guard lines are produced, so the block depth is maintained
 * here; when the outermost block closes any deferred notifications are
 * flushed after it. "guard" is always one of the fixed strings from cmdq_guard,
 * never user text.
 */
void
control_write_guard(struct client *c, const char *guard, long t, u_int number,
 int flags)
{
	struct control_state	*cs = c->control_state;
	char			*line;

	if (cs == NULL)
		return;

	if (strcmp(guard, "begin") == 0)
		cs->guard_depth++;

	xasprintf(&line, "%%%s %ld %u %d", guard, t, number, flags);
	control_write_line(c, line);

	if (strcmp(guard, "begin") != 0 && cs->guard_depth > 0 &&
	 --cs->guard_depth == 0)
		control_flush_deferred(c);
}

Notifications (things like %window-renamed or %layout-change) are deferred while a guard block is open, so a notification can never appear in the middle of a command’s output. That was a bug fix in its own right (commit 6db5175e, issue 5458).

Where the protocol gets interesting: the raw sink

Here’s the function that writes arbitrary text into the control stream:

 c
 
 
/*
 * Write a line of command output or error text. This is a sink for arbitrary
 * user-controlled text (command output, capture-pane, error messages), so it
 * must never try to interpret the content: guard tracking is done only in
 * control_write_guard.
 */
void
control_write(struct client *c, const char *fmt, ...)
{
	struct control_state	*cs = c->control_state;
	char			*line;
	va_list			 ap;

	if (cs == NULL)
		return;

	va_start(ap, fmt);
	xvasprintf(&line, fmt, ap);
	va_end(ap);

	control_write_line(c, line);
}

The comment is the whole story. control_write() is a sink: it takes text that may have come from anywhere — a run-shell job, capture-pane, display-message, an error message that echoes back user input — and puts it on the wire verbatim.

Now look at what reaches it:

cmdq_error() in cmd-queue.c writes error text straight through.
server_client_print() writes command output.
capture-pane -p writes the pane contents.
display-message writes a %%message %s line.

Only one of these paths escapes the payload: pane output streamed with %output, which is octal-escaped (control.c):

 c
 
 
	for (i = 0; i < size; i++) {
		if (new_data[i] < ' ' || new_data[i] == '\\') {
			evbuffer_add_printf(message, "\\%03o", new_data[i]);
		} else {
			start = i;
			while (i + 1 < size &&
			 new_data[i + 1] >= ' ' &&
			 new_data[i + 1] != '\\')
				i++;
			evbuffer_add(message, new_data + start, i - start + 1);
		}
	}

So bytes from a pane are safe, but bytes from a command are not.

The consequence is that a program running in a pane, or a run-shell job, that prints a line starting with % can inject a forged notification into the client’s stream:

text

%output %1 fake pane output
%window-renamed @1 pwned

The tmux server itself will not be confused — that’s exactly what the control_write() comment is defending. But a client that parses %-prefixed lines will act on it. If your control-mode client does something security-relevant with %%window-renamed (updating a supervisor’s window list, say), then any command whose output you forward into the control stream is a potential injection point.

The practical mitigation for a client is to only trust % lines that arrive in the right structural position — inside a %begin/%end block, or in the notification section — and to treat the body of a block as opaque data.

A note on window names

Notifications interpolate names directly:

 c
 
 
		if (winlink_find_by_window_id(&cs->windows, w->id) != NULL) {
			control_notify_write(c, "%%window-renamed @%u %s",
			 w->id, w->name);

A window name cannot contain a raw newline, because names go through clean_name(), which uses utf8_stravis() with VIS_OCTAL|VIS_CSTYLE|VIS_NL. VIS_CSTYLE turns newlines into the two characters \n, and VIS_OCTAL turns # into \043 (since # is not a “visible” character to vis(3)).

So a name cannot forge a new line, but it can contain spaces and %, which a naive client might still mis-parse.

DoS protections

Control mode has accumulated a few defences against misbehaving clients, mostly added in response to issues:

 c
 
 
#define CONTROL_BUFFER_LOW 512
#define CONTROL_BUFFER_HIGH 8192
#define CONTROL_MAXIMUM_AGE 300000
#define CONTROL_MAXIMUM_REPLY_BUFFER (64 * 1024 * 1024)

CONTROL_BUFFER_HIGH is a watermark on the write buffer: a client that stops reading will be paused rather than allowed to grow the server’s memory without bound.
CONTROL_MAXIMUM_AGE (five minutes) drops clients that have not consumed their data.
CONTROL_MAXIMUM_REPLY_BUFFER (64 MB) bounds the memory used by buffered command replies — commit a3129249, issue 5565. A client that issues a command producing a huge reply gets disconnected with “too far behind” rather than being allowed to exhaust the server.

There’s also a pile of fixes around clients dying at awkward moments: “do not attempt to write to control clients which have been destroyed”, “do not let a stuck client prevent the server from exiting”, “do not make pty fds blocking again or control mode clients can get stuck”.

Using it responsibly

If you’re writing a control-mode client:

Do not trust the framing of text you did not generate. Treat the contents of a %begin/%end block as opaque bytes, not as protocol.
Do not pipe the output of an arbitrary command into a control client.
Remember there is no authentication. The socket permissions are the entire access control. If your control client listens on a socket other users can reach, it is a remote shell.
Consider server-access -r. A read-only ACL entry is the supported way to give a less-trusted integration query-only access.

Wrapping up

Control mode is a good idea that has not yet grown the security model the rest of the world expects from a network protocol. Everything is UNIX-socket-local, which is why it has survived for a decade — but the control_write() sink means it is one run-shell away from being a protocol injection target.

Here’s the thing: control mode is a decade-old protocol that has outgrown the era it was designed in. Everything that makes it safe today — UNIX-socket locality, filesystem permissions — is an accident of its deployment, not a property of its design. Treat it that way.

tmux Runs Real ptys for Every Pane

Jay Hubbert — Sat, 12 Sep 2026 16:00:00 +0000

TL;DR: A pane isn’t a picture of a terminal — it’s a real pty with a real process behind it, in its own session. That’s why vim and htop work inside tmux, and it’s also why tmux has to handle job control, resize storms and the SIGTTIN hazard that a screen-scraper never sees.

tmux doesn’t “draw” panes. Every pane is a real pseudo-terminal with a real process behind it, running in its own session with the pty as its controlling terminal.

That choice is what makes vim, htop, less, top and even tmux itself work inside a pane. It’s the difference between tmux and a screen-scraper.

It also creates a set of problems a screen-scraper doesn’t have: job control, resize storms, and the classic “background process tried to read from the terminal” problem.

Creating the pty

The pane’s process is created with forkpty(3):

 c
 
 
	/* Fork the new process. */
	new_wp->pid = fdforkpty(ptm_fd, &new_wp->fd, new_wp->tty, NULL, &ws);
	if (new_wp->pid == -1) {
		xasprintf(cause, "fork failed: %s", strerror(errno));
		new_wp->fd = -1;
		...
	}

fdforkpty() is a thin wrapper in compat/fdforkpty.c:

 c
 
 
int
getptmfd(void)
{
	return (INT_MAX);
}

pid_t
fdforkpty(__unused int ptmfd, int *master, char *name, struct termios *tio,
 struct winsize *ws)
{
	return (forkpty(master, name, tio, ws));
}

The ptmfd parameter exists for platforms without forkpty() — AIX, Haiku, HP-UX and Solaris have their own implementations in compat/forkpty-*.c that do the grantpt/unlockpt/ptsname dance by hand.

The winsize passed to forkpty() sets the initial terminal size, which means the program starts out with the right idea of how big it is:

 c
 
 
	/* Initialize the window size. */
	memset(&ws, 0, sizeof ws);
	ws.ws_col = screen_size_x(&new_wp->base);
	ws.ws_row = screen_size_y(&new_wp->base);
	ws.ws_xpixel = w->xpixel * ws.ws_col;
	ws.ws_ypixel = w->ypixel * ws.ws_row;

forkpty() also calls setsid() in the child and makes the slave pty its controlling terminal. That’s the important part: the child is a session leader, and the pty is its terminal.

Why that matters: job control

Because the pane’s process group is the foreground process group of its pty, the kernel delivers Ctrl-C, Ctrl-\ and Ctrl-Z to it exactly as it would on a normal terminal. tcgetpgrp() inside a pane returns the pane’s own process group, and /proc/<pgrp>/cwd gives the pane’s working directory — which is how tmux implements “current path” tracking:

 c
 
 
	if ((pgrp = tcgetpgrp(fd)) == -1)
		return (NULL);
	xasprintf(&path, "/proc/%lld/cmdline", (long long) pgrp);

A screen-scraper can’t do any of this, because there’s no pty — the program is writing to a pipe and the multiplexer has to pretend.

Gotcha: if you ever see a pane’s #{pane_current_path} disagree with what you’d expect, this is the machinery behind it. It reads the real kernel state of the real process group.

The SIGTTIN problem

Job control brings a specific hazard: a background process that reads from its terminal gets stopped by the kernel with SIGTTIN. In a normal shell that’s desirable. In a multiplexer it’s a bug — the program was never in the background from its own point of view.

tmux handles this in two places.

First, the server ignores the job control signals entirely:

 c
 
 
void
proc_set_signals(struct tmuxproc *tp, void (*signalcb)(int))
{
	struct sigaction	sa;

	tp->signalcb = signalcb;

	memset(&sa, 0, sizeof sa);
	sigemptyset(&sa.sa_mask);
	sa.sa_flags = SA_RESTART;
	sa.sa_handler = SIG_IGN;

	sigaction(SIGPIPE, &sa, NULL);
	sigaction(SIGTSTP, &sa, NULL);
	sigaction(SIGTTIN, &sa, NULL);
	sigaction(SIGTTOU, &sa, NULL);
	sigaction(SIGQUIT, &sa, NULL);

Note that tmux never calls tcsetpgrp() or TIOCSPGRP on the pane’s pty. It doesn’t need to: the pane’s child is already the session leader and the foreground process group. tmux isn’t part of that pty’s job control at all.

Second, when a child is stopped by SIGTTIN or SIGTTOU, tmux doesn’t treat it as a crash and doesn’t resume it:

 c
 
 
static void
server_child_stopped(pid_t pid, int status)
{
	struct window		*w;
	struct window_pane	*wp;

	if (WSTOPSIG(status) == SIGTTIN || WSTOPSIG(status) == SIGTTOU)
		return;

	RB_FOREACH(w, windows, &windows) {
		TAILQ_FOREACH(wp, &w->panes, entry) {
			if (wp->pid == pid) {
				if (killpg(pid, SIGCONT) != 0)
					kill(pid, SIGCONT);
			}
		}
	}

Any other stop signal gets a SIGCONT, because a process that stopped itself (or was stopped by SIGSTOP/SIGTSTP) would otherwise stay stopped forever with nobody to type fg.

The outer terminal is a different story

The server writes to the client’s terminal, and it isn’t the foreground process group of that terminal — the client’s shell is. That’s safe because TOSTOP is off by default on most terminals, and tmux never leaves the client’s foreground group (the client owns the tty).

When the user wants to give the terminal back to their shell — Ctrl-Z from inside tmux — it’s the client that does it, not the server:

 c
 
 
	sigact.sa_handler = SIG_DFL;
	if (sigaction(SIGTSTP, &sigact, NULL) != 0)
		fatal("sigaction failed");
	client_suspended = 1;
	kill(getpid(), SIGTSTP);

and on SIGCONT the client tells the server to wake up and redraw.

Resizing: the storm problem

Resizing a pane means calling TIOCSWINSZ on the pty master, which makes the kernel send SIGWINCH to the foreground process group:

 c
 
 
void
window_pane_send_resize(struct window_pane *wp, u_int sx, u_int sy)
{
	struct window	*w = wp->window;
	struct winsize	 ws;

	if (wp->fd == -1)
		return;

	log_debug("%s: %%%u resize to %u,%u", __func__, wp->id, sx, sy);

	memset(&ws, 0, sizeof ws);
	ws.ws_col = sx;
	ws.ws_row = sy;
	ws.ws_xpixel = w->xpixel * ws.ws_col;
	ws.ws_ypixel = w->ypixel * ws.ws_row;
	if (ioctl(wp->fd, TIOCSWINSZ, &ws) == -1)
#ifdef __sun
		/*
		 * Some versions of Solaris apparently can return an error when
		 * resizing; don't know why this happens, can't reproduce on
		 * other platforms and ignoring it doesn't seem to cause any
		 * issues.
		 */
		if (errno != EINVAL && errno != ENXIO)
#endif
		fatal("ioctl failed");
}

The Solaris comment is a perfect example of the kind of thing that accumulates: an errno filter added to work around a platform bug nobody can reproduce.

The problem with resizing is the storm. Dragging a terminal window edge produces dozens of resize events per second. If each one became a TIOCSWINSZ and a SIGWINCH, the program inside the pane would redraw dozens of times per second, burning CPU and flickering.

tmux solves this with a resize queue and a timer. The queue holds pending resizes; a timer (250 ms) fires and decides what to actually do. The decision logic is documented in the source:

 c
 
 
	/*
	 * There are three cases that matter:
	 *
	 * - Only one resize. It can just be applied.
	 *
	 * - Multiple resizes and the ending size is different from the
	 * starting size. We can discard all resizes except the most recent.
	 *
	 * - Multiple resizes and the ending size is the same as the starting
	 * size. We must resize at least twice to force the application to
	 * redraw. So apply the first and leave the last on the queue for
	 * next time.
	 */

The third case is the subtle one. If the user drags the edge out and back to the original size, the net change is zero — and a single TIOCSWINSZ to the same size would produce no SIGWINCH, because the kernel only signals on an actual change. The application would never redraw, and the pane would be left in a stale state. The fix is to apply an intermediate size and then the final size, forcing two signals.

The implementation:

 c
 
 
	first = TAILQ_FIRST(&wp->resize_queue);
	last = TAILQ_LAST(&wp->resize_queue, window_pane_resizes);
	if (first == last) {
		/* Only one resize. */
		window_pane_send_resize(wp, first->sx, first->sy);
		TAILQ_REMOVE(&wp->resize_queue, first, entry);
		free(first);
	} else if (last->sx != first->osx || last->sy != first->osy) {
		/* Multiple resizes ending up with a different size. */
		window_pane_send_resize(wp, last->sx, last->sy);
		window_pane_clear_resizes(wp, NULL);
	} else {
		/*
		 * Multiple resizes ending up with the same size. There will
		 * not be more than one to the same size in succession so we
		 * can just use the last-but-one on the list and leave the last
		 * for later. We reduce the time until the next check to avoid
		 * a long delay between the resizes.
		 */
		r = TAILQ_PREV(last, window_pane_resizes, entry);
		window_pane_send_resize(wp, r->sx, r->sy);
		window_pane_clear_resizes(wp, last);
		tv.tv_usec = 10000;
	}

There’s also a special case: when a pane enters the alternate screen, any pending resize is flushed immediately rather than waiting for the timer, because the alternate screen is about to take over the display and the application will redraw anyway. There’s a regression test for exactly this (regress/alternate-screen-resize.sh).

Not blocking the application

The classic multiplexer failure mode: the application writes faster than the multiplexer drains the pty, the pty buffer fills, and the application blocks.

tmux avoids this by always draining the pty master into its own grid. The read is done by a libevent bufferevent, and the read event is explicitly disabled while parsing:

 c
 
 
	input_parse_pane(wp);
	bufferevent_disable(wp->event, EV_READ);

so that a program producing output at full speed can’t starve the rest of the event loop. The data is parsed and the read event re-armed afterwards.

The unbounded thing isn’t the pty buffer but tmux’s own scrollback, and that’s bounded by the history-limit option, trimmed 10% at a time (see How tmux Stores Grid Cells in Five Bytes).

The other unbounded thing is a hostile program sending an endless unterminated escape sequence. That’s bounded separately, by the input-buffer-size option, defaulting to 1 MB, after which the parser discards the sequence.

Background jobs without a pty

Not everything needs a terminal. run-shell and #() format jobs run without one, using a socketpair instead:

 c
 
 
	if (flags & JOB_PTY) {
		pid = fdforkpty(ptm_fd, &master, tty, NULL, &ws);
	} else {
		if (socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC, out) != 0)
			goto fail;
		pid = fork();

and their output is captured rather than rendered. The distinction matters: a #() job in a status line must not be able to mess with the screen.

Wrapping up

Using real ptys is the decision that makes tmux a good terminal multiplexer rather than a screen-scraper. Everything else in this article is the cost of that decision:

You must implement a terminal emulator, because you now have to know what the program drew.
You must handle job control, because the kernel is now involved.
You must handle resize storms, because SIGWINCH is now delivered to a real process.
You must handle the pty buffer, because a real program is now writing to a real device.

Every one of those is a problem a screen-scraper simply doesn’t have — and every one of them shows up in a user’s terminal as “tmux is doing something weird again”.

tmux Batches Terminal Output: One Write() Per Event Loop Iteration

Jay Hubbert — Sat, 05 Sep 2026 13:00:00 +0000

TL;DR: Every byte tmux sends to a terminal goes through one function that appends to a per-client buffer, and that buffer is flushed with a single write() per event loop iteration. If the terminal can’t keep up, tmux throws the output away and repaints the screen from scratch later — a deliberate trade of bytes for never blocking.

Every byte tmux sends to a terminal goes through one function. That function appends to a buffer, the buffer is written out with a single write() per event loop iteration, and if the terminal cannot keep up, the buffer is thrown away and the screen is redrawn from scratch later.

That is the whole output pipeline. And it’s a good example of a design where the priority is “the terminal must never be the thing that makes tmux slow” rather than “never lose a byte”.

One buffer per client

Each attached client has a struct tty, and each tty has an evbuffer called out. Everything goes through tty_add() (tty.c):

 c
 
 
static void
tty_add(struct tty *tty, const char *buf, size_t len)
{
	struct client	*c = tty->client;

	if (tty->flags & TTY_BLOCK) {
		tty->discarded += len;
		return;
	}

	evbuffer_add(tty->out, buf, len);
	log_debug("%s: %.*s", c->name, (int)len, buf);
	c->written += len;

	if (tty_log_fd != -1)
		write(tty_log_fd, buf, len);
	if ((tty->flags & TTY_STARTED) &&
	 !event_pending(&tty->event_out, EV_WRITE, NULL))
		event_add(&tty->event_out, NULL);
}

Two details matter more than the rest.

The TTY_BLOCK check comes first. If the client is blocked, the bytes are counted in tty->discarded and dropped on the floor. They are not buffered, not queued, not anywhere.
The event_pending() check. Without it, every single escape sequence would try to arm the write event. Checking whether it is already armed turns “arm the event” from an operation per escape sequence into an operation per event loop iteration.

That second one is the kind of thing you only notice when you go looking. It’s also the difference between thousands of redundant event_add() calls per second and a handful.

One write() per iteration

The buffer is drained by a libevent callback:

 c
 
 
static void
tty_write_callback(__unused int fd, __unused short events, void *data)
{
	struct tty	*tty = data;
	struct client	*c = tty->client;
	size_t		 size = EVBUFFER_LENGTH(tty->out);
	int		 nwrite;

	nwrite = evbuffer_write(tty->out, c->fd);
	if (nwrite == -1)
		return;
	log_debug("%s: wrote %d bytes (of %zu)", c->name, nwrite, size);

	if (c->redraw > 0) {
		if ((size_t)nwrite >= c->redraw)
			c->redraw = 0;
		else
			c->redraw -= nwrite;
		log_debug("%s: waiting for redraw, %zu bytes left", c->name,
		 c->redraw);
	} else if (tty_block_maybe(tty))
		return;

	if (EVBUFFER_LENGTH(tty->out) != 0)
		event_add(&tty->event_out, NULL);
}

evbuffer_write() drains as much as the kernel will take in one write() call. If the buffer is not empty afterwards, the event is re-armed and we go around again.

Here’s the payoff: redrawing a 200x50 window with four panes produces one write() syscall. Not one per cell, not one per run, not one per escape sequence. On a local terminal that is the difference between a smooth redraw and a visible stall.

There’s a second, subtler reason for buffering: ordering. tmux sends cursor moves, SGR changes, erases and text, and those have to arrive in order. If they were separate writes, a terminal that processed them out of order — or a write() that returned a partial count — would produce a garbled screen. One buffer, one write, one order.

The slow terminal problem

Now the part that makes this design interesting.

A terminal on a slow link (SSH over a bad connection, a terminal emulator busy doing something else) can be slower than the program producing output. If tmux simply buffered everything, the buffer would grow without bound and tmux would eat all the memory.

tmux’s answer is to throw the output away:

 c
 
 
#define TTY_BLOCK_INTERVAL (100000 /* 100 milliseconds */)
#define TTY_BLOCK_START(tty) (1 + ((tty)->sx * (tty)->sy) * 8)
#define TTY_BLOCK_STOP(tty) (1 + ((tty)->sx * (tty)->sy) / 8)

The threshold is eight screenfuls of pending output. Once the buffer exceeds that, tty_block_maybe() drains the entire buffer:

 c
 
 
static int
tty_block_maybe(struct tty *tty)
{
	struct client	*c = tty->client;
	size_t		 size = EVBUFFER_LENGTH(tty->out);
	struct timeval	 tv = { .tv_usec = TTY_BLOCK_INTERVAL };

	if (size == 0)
		tty->flags &= ~TTY_NOBLOCK;
	else if (tty->flags & TTY_NOBLOCK)
		return (0);

	if (size < TTY_BLOCK_START(tty))
		return (0);

	if (tty->flags & TTY_BLOCK)
		return (1);
	tty->flags |= TTY_BLOCK;

	log_debug("%s: can't keep up, %zu discarded", c->name, size);

	evbuffer_drain(tty->out, size);
	c->discarded += size;
	...

The client is now flagged TTY_BLOCK, so every subsequent tty_add() is dropped. A timer runs every 100 ms and, once the buffer has drained below the stop threshold, the client is flagged for a full redraw:

#define TTY_BLOCK_STOP(tty) (1 + ((tty)->sx * (tty)->sy) / 8)

So the recovery is: lose the intermediate output, but resynchronise the terminal with a complete repaint.

This is a deliberate trade. The alternative — buffering without limit — turns a slow network into a slow tmux and eventually into an OOM kill. The cost is that a user on a slow link sees the screen jump rather than scroll smoothly, and any program whose output matters (a log tail, an interactive REPL) loses the text that was produced while tmux was blocked.

The CHANGES file records the thinking:

“Handle slow terminals and fast output better: when the amount of data outstanding gets too large, discard output until it is drained and we are able to do a full redraw.”

Deferring redraws until the buffer drains

Related to the above: tmux does not redraw on top of pending output. If there’s still data in the buffer, the redraw is deferred:

 c
 
 
	/* Ignore output queued within the current synchronized frame. */
	n = EVBUFFER_LENGTH(tty->out);
	if ((tty->flags & TTY_SYNCING) && n > tty->sync_offset)
		n = tty->sync_offset;

	/* Defer until output drains, preserving damage in client flags. */
	if (n != 0 || (tty->flags & TTY_BLOCK)) {
		if (n != 0)
			log_debug("%s: redraw deferred (%zu left)", c->name, n);
		else
			log_debug("%s: redraw deferred (blocked)", c->name);
		if (!evtimer_initialized(&ev))
			evtimer_set(&ev, server_client_redraw_timer, NULL);
		if (!evtimer_pending(&ev, NULL)) {
			log_debug("redraw timer started");
			evtimer_add(&ev, &tv);
		}
		if (damaged) {
			c->flags |= CLIENT_REDRAWWINDOW;
			return;
		}

This is in server_client_check_redraw(). A 1 ms timer is armed, and the damage information is preserved in the client’s flags so the deferred redraw still knows what changed. The damage is not thrown away and recomputed — it is carried across the deferral.

The reason is not just tidiness. Redrawing on top of pending output means the redraw bytes get interleaved with the pending bytes in the wrong order relative to what the terminal has already been told. You get tearing. Deferring keeps the byte stream consistent.

Caching the terminal’s attribute state

The second big source of wasted bytes is SGR. Every change of colour, attribute or underline style is an escape sequence, and a screen full of coloured text would otherwise be an enormous stream of ESC[...m.

tmux keeps the terminal’s current style in tty->cell and tty->last_cell, and refuses to emit a redundant change:

 c
 
 
	/* Ignore cell if it is the same as the last one. */
	if (gc2.attr == tty->last_cell.attr &&
	 gc2.fg == tty->last_cell.fg &&
	 gc2.bg == tty->last_cell.bg &&
	 gc2.us == tty->last_cell.us &&
		gc2.link == tty->last_cell.link)
		return;

Same idea for the cursor, the scroll region and the terminal modes:

 c
 
 
/* Move cursor to absolute position. */
void
tty_cursor(struct tty *tty, u_int cx, u_int cy)
{
	...
	/* No change. */
	if (cx == thisx && cy == thisy)
		return;

 c
 
 
/* Set region at absolute position. */
static void
tty_region(struct tty *tty, u_int rupper, u_int rlower)
{
	if (tty->rlower == rlower && tty->rupper == rupper)
		return;
	if (!tty_term_has(tty->term, TTYC_CSR))
		return;

The cursor case has an extra wrinkle — the “automargin space”, the phantom column at the right edge of the line:

 c
 
 
	/*
	 * If in the automargin space, and want to be there, do not move.
	 * Otherwise, force the cursor to be in range (and complain).
	 */
	if (cx == thisx && cy == thisy && cx == tty->sx)
		return;
	if (cx > tty->sx - 1) {
		log_debug("%s: x too big %u > %u", __func__, cx, tty->sx - 1);
		cx = tty->sx - 1;
	}

The cursor’s logical position can be one past the last column (the terminal is about to wrap), and tmux has to model that state to avoid emitting a cursor move that would reset the terminal’s wrap flag.

 c
 
 
void
tty_update_mode(struct tty *tty, int mode)
{
	...
	if (tty->mode == mode)
		return;

The mode function also has a fix-up that shows how much terminal-specific knowledge is baked in:

 c
 
 
	/*
	 * If the mouse modes have changed, clear then all and apply
	 * again. There are differences in how terminals track the
	 * various bits.
	 */
	tty_puts(tty, "\033[?1006l\033[?1000l\033[?1002l\033[?1003l");

Rather than trying to unset one mouse mode and set another, tmux clears all of them and re-applies the ones it wants. That’s more bytes in the common case, and fewer in the pathological case where a terminal tracks the bits differently.

Colours get the same treatment, with a diff:

 c
 
	changed = gc2.attr & ~tc->attr;

so only the attribute bits that are actually new get emitted.

Terminfo strings are resolved once

Escape sequences come from terminfo, and terminfo strings contain parameters. tmux resolves them at startup rather than per use, and it prefers the allocating variant of the parameter expander:

 c
 
 
const char *
tty_term_string_i(struct tty_term *term, enum tty_code_code code, int a)
{
	const char	*x = tty_term_string(term, code), *s;
#if defined(HAVE_TIPARM_S)
	s = tiparm_s(1, 0, x, a);
#elif defined(HAVE_TIPARM)
	s = tiparm(x, a);
#else
	s = tparm((char *)x, a, 0, 0, 0, 0, 0, 0, 0, 0);
#endif

tiparm_s is preferred because tiparm() and tparm() use a static buffer, which is both a thread-safety hazard and a source of surprises when two results are alive at once.

Terminfo padding ($<...>) is stripped at parse time, not at use time:

 c
 
 
/*
 * Ignore strings with no padding.
 */

The raw mode handshake

Before any of this happens, the server takes the client’s terminal out of cooked mode. This is tty_start_tty() in tty.c, and it is a single tcsetattr():

 c
 
 
	tio.c_iflag &= ~(IXON|IXOFF|ICRNL|INLCR|IGNCR|IMAXBEL|ISTRIP);
	tio.c_oflag &= ~(OPOST|ONLCR|OCRNL|ONLRET);
	tio.c_lflag &= ~(IEXTEN|ICANON|ECHO|ECHOE|ECHONL|ECHOCTL|ECHOPRT|ECHOKE|ISIG);

Two details matter for performance and correctness:

IXON/IXOFF are cleared, so Ctrl-S and Ctrl-Q reach the application instead of stopping the terminal’s output.
OPOST is cleared, so output is not translated — no \n → \r\n conversion, which means tmux does not have to think about the terminal eating a newline.

The fd is set non-blocking, so the event loop never blocks on a write:

 c
 
	setblocking(c->fd, 0);

Putting the numbers together

For a typical frame — say, a status line update and a few changed cells in one pane — the output is:

text

1 × cursor position
1 × SGR change (maybe)
n × short text runs
1 × cursor position

all in one buffer, flushed with one write(). For a full-screen redraw of four panes it’s one buffer, one write(), and the byte count is proportional to the number of changed cells rather than the number of cells.

Wrapping up

The interesting decision here is not the buffering — that’s standard. It’s the willingness to discard output. tmux treats the terminal as a device that may be arbitrarily slow and decides that falling behind means resynchronise, not queue.

That decision only works because of the other half of the design: tmux keeps a complete model of what the screen should look like, so it can always rebuild it. Without that model, discarding output would mean losing the screen. With it, discarding output costs one full redraw.

Worth internalizing: “never lose a byte” and “never stall” are different goals, and a multiplexer that owns the screen model can safely pick the second one.

tmux Works Around Terminal Bugs: Believe Nothing, Probe Everything

Jay Hubbert — Sun, 30 Aug 2026 12:00:00 +0000

TL;DR: tmux treats terminal capabilities as unverified claims. It layers terminfo, user overrides, named features, runtime probing and a hard-coded table of per-terminal quirks — and when all five layers fail, it keeps a table of lies.

Every terminal multiplexer eventually becomes a museum of terminal bugs. tmux is no exception: CHANGES is 180 KB of release notes and a substantial fraction of it is about terminals doing the wrong thing.

The interesting part isn’t the individual bugs. It’s the layered strategy tmux uses to deal with them, which has five layers:

terminfo — the database, which is frequently wrong or outdated,
overrides — user-supplied corrections, glob-matched on TERM,
named features — a higher-level abstraction over terminfo capabilities,
runtime probing — actually asking the terminal what it supports and parsing the replies,
a per-terminal table — hard-coded knowledge about specific terminals that no amount of probing will reveal.

Layer 1 and 2: terminfo and overrides

tmux reads terminfo through ncurses but immediately takes control of it. terminal-overrides is a per-TERM list of capability corrections:

 c
 
 
	{ .name = "terminal-overrides",
	 ...
	 .default_str = "linux*:AX@",

That default is itself a workaround. The AX capability means “the terminal does not clear the screen with a background colour”. Removing it for TERM=linux* makes tmux do a full sgr0 reset when switching away from a bright colour, because the Linux console has bugs with bright colours:

“The Linux console has some bugs with bright colours, so add some workarounds for it.”

The override mechanism is tty_term_apply() in tty-term.c, which supports name=value (set), name@ (remove) and name! (do not replace). The ! form exists for a specific case:

 c
 
 
	if (term->flags & TERM_NOREPLACE)
		...

which is used for the cstyle feature, so that a terminal’s own Ss/Se (cursor style) capabilities survive. Some terminals have extended DECSCUSR and tmux shouldn’t clobber it.

The values are decoded with strunvis():

 c
 
			if (strunvis(value, cp) == -1) {

so an override value can contain escaped bytes.

Layer 3: named features

Terminfo is a list of capabilities; what tmux actually cares about is capabilities in combination. The terminal-features option names features, and tty-features.c maps each to the terminfo capabilities it requires.

The named features are:

text

256, appesc, bpaste, ccolour, clipboard, hyperlinks, cstyle, extkeys,
focus, ignorefkeys, imagescroll, kittygraphics, margins, mouse, osc7,
overline, progressbar, rectfill, RGB, sixel, strikethrough, sync, title,
usstyle, utf8

Bracketed paste, for example:

 c
 
 
	static const char *const tty_feature_bpaste_capabilities[] = {
		"Enbp=\\E[?2004h",
		"Dsbp=\\E[?2004l",
		NULL
	};

And synchronized output:

 c
 
 
	static const char *const tty_feature_sync_capabilities[] = {
		"Sync=\\E[?2026%?%p1%{1}%-%tl%eh%;", NULL };

Note that the feature is expressed as a synthetic terminfo capability (Sync), not as “the terminal has capability X”. That keeps the feature system independent of terminfo names, which differ between ncurses versions.

The defaults shipped are a compromise:

 c
 
 
	{ .name = "terminal-features",
	 ...
	 .default_str = "xterm*:clipboard:ccolour:cstyle:focus:title,"
			 "screen*:title," "rxvt*:ignorefkeys" },

xterm* gets the features that essentially every xterm derivative has. screen* gets only title setting, because screen’s terminfo entry is minimal and tmux-inside-screen is a common (and painful) configuration. rxvt* gets ignorefkeys — rxvt sends function keys in a format that conflicts with tmux’s own key handling.

Layer 4: asking the terminal

The most reliable capability detection is to ask. tmux sends queries to the terminal and parses the replies, in tty-keys.c:

Query	Reply	Detects
`ESC [ c` (primary DA)	`ESC [ ? 6 2 ; ... c`	sixel, margins, rectfill, clipboard
`ESC [ > c` (secondary DA)	`ESC [ > 4 1 ; 2 0 c`	terminal identity: mintty, tmux, rxvt-unicode
`ESC [ > q` (XTVERSION)	`ESC P > 0 ... ESC \`	XTerm, kitty, WezTerm, foot, ghostty, iTerm2, Rio
`ESC [ ? 2026 $ p`	`ESC [ ? 2026 ; 1 $ y`	synchronized output
`ESC _G i = 31 ... ESC \`	`OK`	kitty graphics
`ESC ] 10 ; ? ESC \`	`ESC ] 10 ; rgb:...`	foreground colour, and theme detection

The secondary DA reply is particularly useful because it identifies the terminal:

 c
 
 
		case 'M':	/* mintty */
		case 'T':	/* tmux */
		case 'U':	/* rxvt-unicode */

which selects a hard-coded feature set for that terminal.

There’s a five-second timeout on the whole process. If nothing answers, tmux falls back to terminfo plus the defaults:

 c
 
 
#define TTY_QUERY_TIMEOUT 5
#define TTY_REQUEST_LIMIT 30

and the foreground/background colour query is repeated every 30 seconds, because a terminal that was busy at startup may answer later.

The “is it VT100-like?” hack

Some terminals respond to device attributes queries; some don’t, and sending a query to a terminal that doesn’t understand it can produce garbage on the screen. tmux guesses:

 c
 
 
	/*
	 * If TERM has XT or clear starts with CSI then it is safe to assume
	 * the terminal is derived from the VT100. This controls whether device
	 * attributes requests are sent to get more information.
	 *
	 * This is a bit of a hack but there aren't that many alternatives.
	 * Worst case tmux will just fall back to using whatever terminfo(5)
	 * says without trying to correct anything that is missing.
	 *
	 * Also add few features that VT100-like terminals should either
	 * support or safely ignore.
	 */
	s = tty_term_string(term, TTYC_CLEAR);
	if (tty_term_flag(term, TTYC_XT) || strncmp(s, "\033[", 2) == 0) {
		term->flags |= TERM_VT100LIKE;
		tty_parse_client_features(c, "bpaste,focus,title", ",");
	}

“Does the clear capability start with ESC [” as a proxy for “is this a VT100 descendant” — and the consequence is that VT100-like terminals are assumed to support bracketed paste, focus reporting and title setting.

This is the kind of heuristic that only works because someone wrote down why it works.

Layer 5: the per-terminal table

Some things cannot be detected. tty_default_features() in tty-features.c is a table of hard-coded feature sets for known terminals — mintty, tmux, rxvt-unicode, iTerm2, foot, WezTerm, ghostty, kitty, Rio, XTerm.

The XTerm entry carries an interesting comment:

 c
 
 
/*
 * xterm also supports DECSLRM and DECFRA, but they can be
 * disabled so not set it here - they will be added if
 * secondary DA shows VT420.
 */

i.e. “xterm supports these features but they can be turned off, so we only enable them if the terminal tells us it is a VT420”. That’s a level of care that only comes from having been bitten.

Individual workarounds

Beyond the detection layers, there’s a long tail of specific fixes. Some of the most instructive:

The `!am` terminal

Terminals without the am (auto right margin) capability wrap at $COLUMNS - 1 rather than $COLUMNS, which makes it impossible to write to the bottom-right cell without scrolling the screen. tmux flags this:

 c
 
 
	/*
	 * Terminals without am (auto right margin) wrap at at $COLUMNS - 1
	 * rather than $COLUMNS (the cursor can never be beyond $COLUMNS - 1).
	 * ...
	 * This is irritating, most notably because it is painful to write to
	 * the very bottom-right of the screen without scrolling.
	 *
	 * Flag the terminal here and apply some workarounds in other places to
	 * do the best possible.
	 */
	if (!tty_term_flag(term, TTYC_AM))
		term->flags |= TERM_NOAM;

and then refuses to write that cell:

 c
 
 
void
tty_putc(struct tty *tty, u_char ch)
{
	const char	*acs;

	if ((tty->term->flags & TERM_NOAM) &&
	 ch >= 0x20 && ch != 0x7f &&
	 tty->cy == tty->sy - 1 &&
	 tty->cx + 1 >= tty->sx)
		return;

and re-positions the cursor explicitly after a wrap, because on such a terminal the cursor position after wrapping isn’t what tmux thinks:

 c
 
 
			/*
			 * On !am terminals, force the cursor position to where
			 * we think it should be after a line wrap - this means
			 * it works on sensible terminals as well.
			 */
			if (tty->term->flags & TERM_NOAM)
				tty_putcode_ii(tty, TTYC_CUP, tty->cy, tty->cx);

The PuTTY wrap flag

Some terminals don’t reset their wrap flag when the scroll region is changed, so a subsequent line feed scrolls the screen. tmux works around it by moving the cursor to column 0 first:

 c
 
 
	/*
	 * Some terminals (such as PuTTY) do not correctly reset the cursor to
	 * 0,0 if it is beyond the last column (they do not reset their wrap
	 * flag so further output causes a line feed). As a workaround, do an
	 * explicit move to 0 first.
	 */
	if (tty->cx >= tty->sx) {
		if (tty->cy == UINT_MAX)
			tty_cursor(tty, 0, 0);
		else
			tty_cursor(tty, 0, tty->cy);
	}

The same class of bug exists in vte, which is why the commit history has both “vte is buggy and doesn’t home the cursor after changing the scroll region” and the general PuTTY fix.

Cursor position after IL and DL

/* Cannot rely on cursor position after DL and IL (some terminals move to column 0, some do not). */

Some terminals home the cursor after inserting or deleting lines, some don’t. tmux never assumes either way.

Bright colours on the Linux console

 c
 
 
	/*
	 * If the current colour is an aixterm bright colour and the new is not,
	 * reset because some terminals do not clear bright correctly.
	 */

Plus the linux*:AX@ default override, which makes tmux use a full sgr0 reset instead of 39m/49m on those terminals.

The Konsole scroll bug

Konsole’s CSI S (scroll up) can’t clear the entire scroll region, and the parameter needs clamping. The CHANGES file records: “Clamp SU (CSI S) parameter to work around a bug in Konsole.”

An earlier attempt at this was reverted:

/* The Konsole SU bug means it can't clear the entire scroll region ... remove the workarounds which just cause bugs on other terminals. */

That’s a good reminder: workarounds for one terminal often break another.

Mouse mode reset

 c
 
 
	/*
	 * If the mouse modes have changed, clear then all and apply
	 * again. There are differences in how terminals track the
	 * various bits.
	 */
	tty_puts(tty, "\033[?1006l\033[?1000l\033[?1002l\033[?1003l");

And a filter for terminals that send spurious wheel-release events:

	/* Some terminals (like PuTTY 0.63) mistakenly send button-release events for scroll-wheel button-press event. */

Bogus terminfo capabilities

tty_term_validate() removes terminfo capabilities that don’t work. The Ms capability (OSC 52, set clipboard) is a common casualty: some terminfo entries have an Ms that expands to nothing.

Terminals that break when you set the title

From the CHANGES file:

“Only attempt to set the title where TERM looks like an xterm (contains ‘xterm’, ‘rxvt’ or is ‘screen’). I hate this but I don’t see a better way: setting the title actually kills some other terminals pretty much dead.”

“I hate this but I don’t see a better way” is the most honest sentence in the entire tmux source.

The escape timeout is adaptive too

One more workaround, in the client: the delay before an ambiguous Escape is treated as the Escape key. It’s stretched when tmux is waiting for a terminal reply, so a reply isn’t mistaken for user input, and when a bracketed paste has just ended.

 c
 
 
	delay = options_get_number(global_options, "escape-time");
	if (delay == 0)
		delay = 1;

with the delay raised to 500 ms in the two special cases.

Wrapping up

The general shape of the solution is: believe nothing, probe everything, and keep a table of lies.

Terminfo is a database maintained by hand, distributed by operating systems that lag behind the terminals they describe, and describing terminals that no longer exist. It’s useful as a starting point and untrustworthy as an answer.

Probing is better, but probing has failure modes of its own: the terminal may not answer, may answer late, may answer with something unexpected, or may be a terminal whose author didn’t read the specification.

And no amount of probing will tell you that PuTTY doesn’t reset its wrap flag, or that the Konsole scroll sequence is broken, or that setting the title on some terminal makes it unusable. That knowledge has to be remembered, written down in a table, and maintained by whoever gets reported.

The terminal-features and terminal-overrides options are the escape hatch, and they exist because the fifth layer inevitably gets something wrong.

tmux Redraws Only What Changed: Five Layers of Less Work

Jay Hubbert — Fri, 21 Aug 2026 14:00:00 +0000

TL;DR: tmux never redraws “the screen” — it redraws the difference. Five stacked mechanisms each remove work: skip unchanged cells, skip untouched regions, skip recomputing the layout, coalesce runs into spans, and during synchronized updates redraw only the lines that actually changed.

A terminal multiplexer that redraws the whole screen on every keystroke is unusable. tmux avoids it with a stack of increasingly precise mechanisms:

cell comparison — don’t emit a cell that has not changed,
damage rectangles — don’t even look at the parts of a window that were not touched,
a cached scene — don’t recompute the layout of the screen if nothing about the layout changed,
span coalescing — don’t emit one escape sequence per cell,
a dirty-line bitmap — during a synchronized update, redraw only the lines that changed.

Here’s how each of those works, in the OpenBSD-flavoured tmux tree at commit 6f655f48.

The starting point: tmux knows what the screen looks like

Unlike a program that just writes bytes to a terminal, tmux maintains a full model of each pane: struct grid in grid.c, a two-dimensional array of cells with a history of scrolled-off lines above it.

That’s what makes diffing possible. To know whether a cell needs to be redrawn, you need to know what it should look like versus what the terminal does look like. tmux keeps the “should” in the grid and tracks the “does” in a second grid per client that is only updated when something is actually sent.

Without that second grid, none of the rest of this article is possible.

Level 1: comparing cells

grid.c has two comparison functions, and the split between them matters:

 c
 
 
/* Check if two styles are (visibly) the same. */
int
grid_cells_look_equal(const struct grid_cell *gc1, const struct grid_cell *gc2)
{
	int flags1 = gc1->flags, flags2 = gc2->flags;

	if (gc1->fg != gc2->fg || gc1->bg != gc2->bg)
		return (0);
	if (gc1->attr != gc2->attr)
		return (0);
	if ((flags1 & ~GRID_FLAG_CLEARED) != (flags2 & ~GRID_FLAG_CLEARED))
		return (0);
	if (gc1->link != gc2->link)
		return (0);
	return (1);
}

/* Compare grid cells. Return 1 if equal, 0 if not. */
int
grid_cells_equal(const struct grid_cell *gc1, const struct grid_cell *gc2)
{
	if (!grid_cells_look_equal(gc1, gc2))
		return (0);
	if (gc1->data.width != gc2->data.width)
		return (0);
	if (gc1->data.size != gc2->data.size)
		return (0);
	return (memcmp(gc1->data.data, gc2->data.data, gc1->data.size) == 0);
}

grid_cells_look_equal() compares style only: foreground, background, attributes, hyperlink. grid_cells_equal() additionally compares the character data itself.

The ~GRID_FLAG_CLEARED masking is a nice piece of care. GRID_FLAG_CLEARED is bookkeeping — it marks a cell that has been explicitly cleared — and it isn’t visible to the user. Masking it out means a cleared cell still compares equal to a cell with the same style, so a redundant clear doesn’t force a redraw.

The two levels get used for different things. Style comparison decides whether a run of cells can be emitted as one SGR change; full comparison decides whether a cell needs to be written at all.

Level 2: the per-cell skip

The hot path is screen_write_cell1() in screen-write.c. When tmux writes a character into the grid, it checks whether the terminal already shows that character:

 c
 
 
	/* If no change, do not draw. */
	if (skip) {
		if (s->cx >= gl->cellsize)
			skip = grid_cells_equal(gc, &grid_default_cell);
		else {
			gce = &gl->celldata[s->cx];
			if (gce->flags & GRID_FLAG_EXTENDED)
				skip = 0;
			else if (gc->flags != gce->flags)
				skip = 0;
			else if (gc->attr != gce->data.attr)
				skip = 0;
			else if (gc->fg != gce->data.fg)
				skip = 0;
			else if (gc->bg != gce->data.bg)
				skip = 0;
			else if (gc->data.width != 1)
				skip = 0;
			else if (gc->data.size != 1)
				skip = 0;
			else if (gce->data.data != gc->data[0])
				skip = 0;
		}
	}

This is deliberately not a call to grid_cells_equal(). It’s a hand-unrolled comparison against the packed representation, because this is the innermost loop of the whole program: it runs for every character of every program that outputs anything.

The packed comparison can’t handle every case, so it bails out to the slow path:

GRID_FLAG_EXTENDED cells (RGB colours, wide characters, hyperlinks,

8-bit attributes) aren’t stored packed, so they’re always redrawn,
a wide character (width != 1) spans several cells and its padding has to be redrawn with it,
a multi-byte character can’t be compared with a single byte.

For plain ASCII in the default colours — the overwhelming majority of terminal output — this is four integer compares and one byte compare.

Level 3: damage rectangles

Even with per-cell skipping, tmux would have to walk every cell of every pane on every redraw. Damage rectangles avoid the walk.

A window accumulates a list of damaged regions (screen-redraw.c):

 c
 
 
/* A damaged rectangle in a window. */
struct redraw_damage {
	u_int				 x;
	u_int				 y;
	u_int				 sx;
	u_int				 sy;

	int				 flags;
#define REDRAW_DAMAGE_SCROLL 0x1

	TAILQ_ENTRY(redraw_damage)	 entry;
};

/*
 * If there are more damage rectangles than this, they are collapsed into
 * one.
 */
#define REDRAW_DAMAGE_MAX 16

Damage is recorded when a pane writes (redraw_damage_window() in screen-write.c), when an image is drawn (image-grid.c), and when a floating pane moves (window.c).

The interesting part is how damage is merged. redraw_apply_window_damage() walks the existing list and tries to fold a new rectangle into an existing one:

 c
 
 
		x0 = (x < rd->x) ? x : rd->x;
		y0 = (y < rd->y) ? y : rd->y;
		x1 = (x + sx > rd->x + rd->sx) ? x + sx : rd->x + rd->sx;
		y1 = (y + sy > rd->y + rd->sy) ? y + sy : rd->y + rd->sy;

		area = sx * sy + rd->sx * rd->sy;
		union_area = (x1 - x0) * (y1 - y0);
		if (union_area > 2 * area)
			continue;

The union_area > 2 * area test is the interesting one. Merging two rectangles that are far apart creates a bounding box that covers a lot of undamaged area. If the union is more than twice the size of the two rectangles combined, the merge is rejected and the new rectangle is added as a separate entry instead.

That keeps the list small without letting a scattered set of changes turn into “redraw everything”.

And past 16 rectangles, everything collapses into one bounding box:

 c
 
 
	TAILQ_INSERT_TAIL(&w->damage, rd, entry);
	if (++w->damage_count > REDRAW_DAMAGE_MAX)
		redraw_collapse_damage(w);

The same idea shows up in the damage flags: REDRAW_DAMAGE_SCROLL marks damage that the terminal can satisfy with a scroll rather than with repainted text, and redraw_client_damage() skips those regions when the terminal has already been told to scroll.

This whole mechanism is relatively new. The commit that introduced it says:

“Instead of redrawing the entire pane or scene when moving or redrawing a pane, add damage rectangles and redraw only the affected spans.”

Level 4: the cached scene

Damage tells you what changed. The scene tells you where everything is, and it is expensive to compute: pane positions, border positions, status line spans, scrollbars, the regions outside the window.

screen-redraw.c caches it per client and invalidates it with a generation counter:

 c
 
 
/* Get the cached redraw scene, rebuilding it if needed. */
static struct redraw_scene *
redraw_get_scene(struct client *c)
{
	struct redraw_scene	*scene = c->redraw_scene;
	struct window		*w = c->session->curw->window;
	const char		*reason = NULL;
	u_int			 ox, oy, sx, sy;

	redraw_get_window_offset(c, &ox, &oy, &sx, &sy);
	if (scene == NULL)
		reason = "missing";
	else if (scene->w != w)
		reason = "window changed";
	else if (scene->generation != w->redraw_scene_generation)
		reason = "generation changed";
	else if (scene->ox != ox || scene->oy != oy)
		reason = "offset changed";
	else if (scene->sx != sx || scene->sy != sy)
		reason = "size changed";
	if (reason != NULL) {
		log_debug("%s: @%u scene invalid: %s", c->name, w->id, reason);
		redraw_free_scene(scene);
		scene = redraw_make_scene(c);
		c->redraw_scene = scene;
	}
	return (scene);
}

The reason string is a nice touch — it’s logged, so you can see why the scene was rebuilt. When something feels slow, log_debug will tell you whether you were paying for geometry or for pixels.

The generation counter is a uint64_t assigned from a single global counter, so it’s unique across all windows:

 c
 
 
/*
 * Mark a window's cached redraw scenes as out of date. Generations are unique
 * across all windows so a scene can never match a new window that reuses the
 * address of a freed one.
 */
void
redraw_invalidate_scene(struct window *w)
{
	static uint64_t	next_generation;

	w->redraw_scene_generation = ++next_generation;
}

The comment on the counter explains why: a freed window’s address could otherwise be reused by a new window and the generation counter would accidentally match. This is the same class of bug as the ABA problem in lock-free data structures.

Building the scene allocates a temporary grid of cells. That grid is a single static buffer that is grown, never freed per frame:

 c
 
 
	ncells = (size_t)bctx->sx * bctx->sy;
	if (ncells > redraw_ncells) {
		redraw_cells = xreallocarray(redraw_cells, ncells, sizeof *redraw_cells);
		redraw_ncells = ncells;
	}

Level 5: spans

The scene isn’t a grid of cells when it’s finished; it’s a list of spans. The file’s own comment explains the pipeline:

text

 * 1) redraw_build_cells fills a temporary grid of struct redraw_build_cell
 * objects, one per visible cell. It marks pane contents, scrollbars,
 * borders, pane status lines and any cells outside the window.
 * 2) redraw_make_scene takes the grid ... and converts them into spans
 * by joining adjacent cells that have the same type and data.

The span types are:

 c
 
 
/* Type of span in the scene. */
enum redraw_span_type {
	REDRAW_SPAN_PANE,	/* inside a pane */
	REDRAW_SPAN_OUTSIDE,	/* outside the window */
	REDRAW_SPAN_EMPTY,	/* inside the window but nothing visible */
	REDRAW_SPAN_STATUS,	/* pane status line */
	REDRAW_SPAN_BORDER,	/* pane border */
	REDRAW_SPAN_SCROLLBAR,	/* pane scrollbar */
	REDRAW_SPAN_MENU,	/* window menu */
};
#define REDRAW_SPAN_TYPES 7

A span is “a run of cells that are all the same kind of thing”. A whole pane line becomes one span, and a whole status line becomes one span.

Level 6: writing the spans

The final stage is tty_draw_line() in tty-draw.c, a state machine that walks a line of cells and produces terminal output. Two things matter here.

First, runs of cells with the same style are accumulated into a buffer and flushed in one go:

 c
 
 
	if (grid_cells_look_equal(gcp, &last)) {
		...
		buf[len++] = ...;
		...
	}

with a fixed char buf[1000] — a stack buffer, no allocation, sized so that a full line of ordinary text fits without spilling.

Second, empty cells aren’t written as spaces. They’re cleared with the terminal’s own erase sequence, which is both shorter and correct for background colours:

 c
 
 
static void
tty_draw_line_clear(struct tty *tty, struct tty_ctx *ctx, u_int py, u_int px,
 u_int nx, u_int ny)

using EL, EL1 or ECH depending on what the terminal supports and where the run is.

Level 7: synchronized output and the dirty-line bitmap

The last mechanism is for applications that use synchronized output (the DECSET 2026 mode) — vim with set t_RV and friends. In that mode the terminal buffers everything until it receives an end-of-synchronised-update, so tmux can defer output.

tmux tracks which lines changed with a bitmap (screen-write.c):

 c
 
 
	if (bs != NULL && wp->sync_dirty_size == sy)
		return (bs);

The bitmap is allocated once per pane size and reused, and it’s what screen_write_sync_flush_dirty() uses to redraw only the lines that changed when the sync frame ends.

The commit that added scroll tracking to it is a good illustration of the kind of thinking that makes this fast:

“As well as tracking modified (dirty) lines during a synchronized update, also track scrolled lines. This means they can be scrolled as one instead of forcing each line to be redrawn — much less expensive for a very common operation.”

Scrolling is by far the most common thing a terminal program does. Being able to express it as “one scroll” rather than “80 repainted lines” is worth a lot.

Putting it together

The full path for a keystroke in a pane is roughly:

text

program writes to pty
 → input.c parses the bytes into a screen_write context
 → screen-write.c updates the grid, marking damage
 → damage rectangles accumulate on the window
 → next event loop iteration, the client's scene is looked up
 → the scene is reused if nothing structural changed
 → spans are drawn, comparing against the client's grid
 → unchanged cells emit nothing
 → changed cells are batched into runs
 → the whole thing is one write() to the client's tty

Each layer removes work rather than adding it. The two most impactful single decisions are probably the hand-unrolled packed cell comparison (level 2) and the damage rectangle merging with the 2x area cutoff (level 3): the first makes the common case cheap, the second keeps the common case from happening at all.

The overall design goal is stated in the commit that introduced the scene cache:

“A scene is generated and cached in the client: it holds positions and sizes of panes, borders and so on. The scene is invalidated when a pane is moved or resized.”

Everything else follows from that: if the geometry hasn’t changed, there’s no reason to recompute the geometry.

Why tmux Is a Server and Not a Terminal Program

Jay Hubbert — Fri, 14 Aug 2026 09:00:00 +0000

TL;DR: tmux is a daemon that owns real ptys plus thin clients that connect over a UNIX socket. The client hands its terminal file descriptors to the server, so the server writes the composited screen straight into your terminal — the client isn’t even in the output path.

tmux is not a terminal emulator that draws a picture of a terminal. It’s a daemon that owns real ptys, plus a set of thin clients that connect to it over a UNIX socket and ask it questions.

That split is the single most important architectural decision in tmux, and almost everything else follows from it: why panes survive a disconnect, why several people can watch the same session, why the output goes to the terminal from the server rather than from the client, and why control mode exists at all.

The shape of the system

text

 tmux new-window ──┐
 tmux attach ─┤
 tmux -C ─┼──► client process ──socket──► server process
 your editor ─┘ │ │
 │ ├── pty A (vim)
 │ ├── pty B (shell)
 └── terminal fd ───────►├── pty C (top)
 (passed over the socket)

The client is a short-lived or long-lived process that:

connects to the socket,
sends its terminal name, terminfo capabilities, cwd, environment and features,
passes its stdin and stdout file descriptors to the server,
then either reads commands from the socket and writes them to the terminal (the control client), or just waits (the attach client).

The server is the process that owns the ptys, parses their output, maintains the grid, and writes the composited screen into the client’s terminal.

The server is a daemon

The server is started with socketpair() + fork() + daemon() (proc.c):

 c
 
 
pid_t
proc_fork_and_daemon(int *fd)
{
	pid_t	pid;
	int	pair[2];

	if (socketpair(AF_UNIX, SOCK_STREAM, PF_UNSPEC, pair) != 0)
		fatal("socketpair failed");
	switch (pid = fork()) {
	case -1:
		fatal("fork failed");
	case 0:
		close(pair[0]);
		*fd = pair[1];
		if (daemon(1, 0) != 0)
			fatal("daemon failed");
		return (0);
	default:
		close(pair[1]);
		*fd = pair[0];
		return (pid);
	}
}

daemon(1, 0) means: detach from the controlling terminal, but keep the current working directory. The server ends up in its own session with no controlling terminal.

That’s the point. A server with a controlling terminal dies when the terminal goes away. A server without one keeps running, and so do all the programs running in its panes.

The race between two clients both trying to start a server is handled with a lock file. client_get_lock() in client.c takes an flock() on <socket>.lock, and only the winner starts a server:

 c
 
 
		locked = 1;
		goto retry;

with a comment explaining the subtlety:

 c
 
 
			/*
			 * Always retry at least once, even if we got the lock,
			 * because another client could have taken the lock,
			 * started the server and released the lock between our
			 * connect() and flock().
			 */

The protocol is imsg, and it carries file descriptors

tmux uses the OpenBSD imsg library (bundled in compat/imsg.c) for the client/server protocol. The message types are in tmux-protocol.h:

 c
 
 
/* Protocol version. */
#define PROTOCOL_VERSION 8

/* Message types. */
enum msgtype {
	MSG_VERSION = 12,

	MSG_IDENTIFY_FLAGS = 100,
	MSG_IDENTIFY_TERM,
	MSG_IDENTIFY_TTYNAME,
	MSG_IDENTIFY_OLDCWD, /* unused */
	MSG_IDENTIFY_STDIN,
	MSG_IDENTIFY_ENVIRON,
	MSG_IDENTIFY_DONE,
	MSG_IDENTIFY_CLIENTPID,
	MSG_IDENTIFY_CWD,
	MSG_IDENTIFY_FEATURES,
	MSG_IDENTIFY_STDOUT,
	MSG_IDENTIFY_LONGFLAGS,
	MSG_IDENTIFY_TERMINFO,

	MSG_COMMAND = 200,
	MSG_DETACH,
	...

The message numbering is meaningful: 100-series is the handshake, 200-series is session lifecycle and commands, 300-series is file transfer (run-shell output, #{...} job output, and the pipe-pane machinery).

The version is checked on every message:

 c
 
 
	version = imsg->hdr.peerid & 0xff;
	if (imsg->hdr.type != MSG_VERSION && version != PROTOCOL_VERSION) {
		proc_send(peer, MSG_VERSION, -1, NULL, 0);
		peer->flags |= PEER_BAD;

The interesting part of imsg for tmux is that it can pass file descriptors along with messages. proc_add_peer() enables it:

 c
 
 
	imsgbuf_init(&peer->ibuf, fd);
	imsgbuf_allow_fdpass(&peer->ibuf);

The client hands over its terminal

This is the mechanism that makes the whole design work. The client’s handshake includes its stdin and stdout:

 c
 
 
	if ((fd = dup(STDIN_FILENO)) == -1)
		fatal("dup failed");
	proc_send(client_peer, MSG_IDENTIFY_STDIN, fd, NULL, 0);
	if ((fd = dup(STDOUT_FILENO)) == -1)
		fatal("dup failed");
	proc_send(client_peer, MSG_IDENTIFY_STDOUT, fd, NULL, 0);

and the server picks them up:

 c
 
 
	case MSG_IDENTIFY_STDIN:
		if (datalen != 0)
			return (-1);
		c->fd = imsg_get_fd(imsg);
		log_debug("client %p IDENTIFY_STDIN %d", c, c->fd);
		break;
	case MSG_IDENTIFY_STDOUT:
		if (datalen != 0)
			return (-1);
		c->out_fd = imsg_get_fd(imsg);
		log_debug("client %p IDENTIFY_STDOUT %d", c, c->out_fd);
		break;

The server now holds the client’s terminal file descriptor. When the server renders the screen, it writes the escape sequences straight into the user’s terminal. The client isn’t in the data path for output at all.

This has three consequences:

Latency. Every byte of screen output crosses the socket? No — it doesn’t. The server writes directly to the terminal fd it was given. The socket only carries commands into the server.
The client is replaceable. Detach and re-attach is a new client handing over a new terminal fd. The server keeps the session.
Multiple clients. Two people attach to the same session; the server renders for each client separately, at each client’s size, with each client’s terminal capabilities.

The server also learns what the terminal can do

The client sends its terminfo capabilities to the server:

 c
 
 
	for (i = 0; i < ncaps; i++) {
		proc_send(client_peer, MSG_IDENTIFY_TERMINFO, -1,
		 caps[i], strlen(caps[i]) + 1);
	}

The client reads terminfo using ncurses (setupterm() and tigetstr() in tty-term.c) and ships the ~100 capabilities tmux cares about. The server then builds its own struct tty_term from that list.

This inversion is important: the client does no rendering and no escape sequence translation. It’s a transport. The server is the thing that knows about terminals.

Two kinds of client

The server distinguishes two client personalities, and they behave completely differently.

Attach clients have a terminal. The server puts the terminal into raw mode, renders the composited screen into it, and forwards keystrokes into the active pane:

 c
 
 
	if (c->flags & CLIENT_CONTROL)
		control_start(c);
	else if (c->fd != -1) {
		if (tty_init(&c->tty, c) != 0) {
			close(c->fd);
			c->fd = -1;
		} else {
			tty_resize(&c->tty);
			c->flags |= CLIENT_TERMINAL;
		}

Note that a control client never gets a tty at all — it’s excluded from the screen-drawing path entirely:

 c
 
 
	if (c->flags & (CLIENT_CONTROL|CLIENT_SUSPENDED))
		return;

Control clients (tmux -C) speak a text protocol. They never render anything. They send commands, ask for pane output with %output, and receive notifications such as %window-renamed. This is the interface used by editors and status bars, and it’s covered in tmux Control Mode Is an Unauthenticated Command Channel.

Why the split is worth it

The alternative design — a single process that owns everything — is simpler in the abstract, and it’s roughly what screen(1) does. The daemon design buys five things:

1. Sessions outlive the terminal. tmux detach, close the laptop, reopen it tomorrow: the programs are still running, the scrollback is still there. With a single-process design, the multiplexer dies with the terminal and takes the programs with it.

2. Sharing. Several users can attach to the same session. The server renders separately for each client, so one person on a 4K monitor and another on a phone both get a correct view.

3. The server can outlive the client’s connection. A client on a flaky SSH link can be disconnected and reconnected without disturbing the session. tmux even has attach -d and the detach-on-destroy option for exactly this.

4. Control mode falls out for free. Because the server is a server, it can have a client that is not a terminal at all. A scripting interface isn’t a special case bolted on; it’s just another client.

5. The server is the right place for the event loop. A single event loop in the daemon serves every client and every pane. A client that disconnects takes nothing with it.

The costs

The split isn’t free, and the code shows where it hurts:

The server must trust the client’s claims about its terminal. The client says “here are my terminfo capabilities” and the server believes them. A lying client gets a wrong screen.
The server holds file descriptors for clients. When a client dies without cleaning up, the server has a stale fd. The CLIENT_EXIT and “do not attempt to write to control clients which have been destroyed” fixes are the accumulated scar tissue from this.
Every command crosses a process boundary. tmux new-window from a script is a round trip through a socket, not a function call. For a script that runs thousands of commands, that matters — which is why tmux -C exists as a way to keep a persistent connection.
The client and server can disagree. The client thinks the terminal is 80x24; the server thinks it is 100x30. The resize protocol exists to reconcile this:

 c
 
	case MSG_RESIZE:

Debugging is harder. tmux has no debugger-friendly separation between “the terminal” and “the multiplexer”.

Wrapping up

The classic mistake in writing a terminal multiplexer is to make the multiplexer be the terminal: one process that owns a terminal, parses what programs write, and draws a picture. That works, and it’s what screen does.

tmux’s insight is that the multiplexer should be a service that owns resources (ptys, sessions, scrollback) and clients that provide endpoints (terminals, or script interfaces).

Once the multiplexer is a service, everything else — sharing, persistence, scripting, remote attachment — is a consequence rather than a feature.

tmux Secures its UNIX Socket

Jay Hubbert — Tue, 04 Aug 2026 10:00:00 +0000

TL;DR: There is no password, no token, no challenge-response in tmux. If you can open the socket, you own the session — so the entire security model is socket permissions, a 0700 per-user directory, and an optional in-memory ACL keyed on the peer’s real uid/gid from getpeereid(3).

A tmux server is a daemon that owns real ptys. Any process that can talk to its UNIX socket can run commands as the user who started the server, including run-shell and source-file.

There is no password, no token, no challenge-response anywhere in the tmux source — grep -rn "passphrase" . returns nothing.

That means the entire security model of tmux is:

the permissions on the socket file,
the permissions on the directory containing it,
an optional in-memory ACL keyed on the peer’s uid and gid,
and a pile of path handling to make sure the socket ends up somewhere an attacker cannot pre-create.

This is a walk through all four, based on the OpenBSD-flavoured tmux tree at commit 6f655f48 (version 3.7b plus ~1300 commits).

The socket is the boundary

The server creates its socket in server_create_socket() (server.c):

 c
 
 
/* Create server socket. */
int
server_create_socket(uint64_t flags, char **cause)
{
	struct sockaddr_un	sa;
	size_t			size;
	mode_t			mask;
	int			fd, saved_errno;

	memset(&sa, 0, sizeof sa);
	sa.sun_family = AF_UNIX;
	size = strlcpy(sa.sun_path, socket_path, sizeof sa.sun_path);
	if (size >= sizeof sa.sun_path) {
		errno = ENAMETOOLONG;
		goto fail;
	}
	unlink(sa.sun_path);

	if ((fd = socket(AF_UNIX, SOCK_STREAM, 0)) == -1)
		goto fail;

	if (flags & CLIENT_DEFAULTSOCKET)
		mask = umask(S_IXUSR|S_IXGRP|S_IRWXO);
	else
		mask = umask(S_IXUSR|S_IRWXG|S_IRWXO);
	if (bind(fd, (struct sockaddr *)&sa, sizeof sa) == -1) {

The umask() dance is the first line of defence, and it’s deliberately different for the two kinds of socket:

Socket	Selected by	umask	Resulting mode
default	no `-S`	`0117`	`0660` — owner and group read/write
custom	`-S /path`	`0177`	`0600` — owner only

The default socket is group-writable on purpose: it lives in a private 0700 directory, but the group bits let a shared tmux work for a team without every member needing to be root or the same user. Everything else about group membership is handled by the ACL below.

Note also unlink(sa.sun_path) before bind(). The server removes whatever file is already at that path. That’s convenient — it cleans up stale sockets — but it means the socket path must be somewhere only the owner can write to. Otherwise another user could plant a file there and have it deleted, or, worse, race the server for the name.

The 0700 directory under /tmp

The default socket path is built by make_label() (tmux.c). The steps matter:

 c
 
 
	xasprintf(&base, "%s/tmux-%ld", path, (long)uid);
	free(path);
	if (mkdir(base, S_IRWXU) != 0 && errno != EEXIST) {
		xasprintf(cause, "couldn't create directory %s (%s)", base,
		 strerror(errno));
		goto fail;
	}
	if (lstat(base, &sb) != 0) {
		...
	}
	if (!S_ISDIR(sb.st_mode)) {
		xasprintf(cause, "%s is not a directory", base);
		goto fail;
	}
	if (sb.st_uid != uid || (sb.st_mode & TMUX_SOCK_PERM) != 0) {
		xasprintf(cause, "directory %s has unsafe permissions", base);
		goto fail;
	}
	xasprintf(&path, "%s/%s", base, label);

Four separate protections:

The directory is created 0700, so only the owner can list or enter it.
lstat() is used, not stat(). A symlink pointing at a directory is rejected because lstat sees the symlink, not the target. This is the classic /tmp/tmux-$UID symlink attack, closed.
The owner must be the current uid, so a directory left behind by a recycled uid is refused.
TMUX_SOCK_PERM is 007 — other rwx is forbidden. Group bits are explicitly allowed, matching the 0660 socket.

The directory list itself is validated. check_socket_path() rejects relative paths and any .. component:

 c
 
 
static int
check_socket_path(const char *path, char **cause)
{
	char	*copy, *next, *tmp;

	if (*path != '/') {
		xasprintf(cause, "socket directory %s is not an absolute path",
		 path);
		return (0);
	}
	copy = tmp = xstrdup(path);
	while ((next = strsep(&tmp, "/")) != NULL) {
		if (strcmp(next, "..") == 0) {
			xasprintf(cause, "socket directory %s contains ..",
			 path);
			free(copy);
			return (0);
		}
	}

The list comes from TMUX_SOCK, which is "$TMUX_TMPDIR:" _PATH_TMP, and each candidate is realpath()-resolved before use.

One rough edge: the `-L` label

Look again at the last line of make_label():

 c
 
	xasprintf(&path, "%s/%s", base, label);

The label isn’t validated at all. -L takes a name for the socket inside the tmux-$UID directory, and a label containing a slash or .. escapes that directory:

text

tmux -L ../victim

resolves to /tmp/tmux-1000/../victim. The socket is then created there with mode 0660 and unlink()ed by the client on startup.

This isn’t a privilege escalation by itself — you still need to be the same user — but it means the 0700 directory guarantee doesn’t hold for -L labels, and the unlink() in client_connect() will delete a file at that path. The -S option is worse in the same way: it skips the directory entirely, and only the 0600 socket mode protects it.

Gotcha: if you use -L for multiple tmux servers, treat the label as trusted input. It isn’t validated the way the socket path is.

The ACL: real peer credentials

The optional access control list is the interesting part, because it’s based on the credentials of the connecting process rather than anything the client claims. The kernel gives the server the peer’s uid and gid via getpeereid(3), and tmux reads them once, at accept time (proc.c):

 c
 
 
	imsgbuf_allow_fdpass(&peer->ibuf);
	event_set(&peer->event, fd, EV_READ, proc_event_cb, peer);

	if (getpeereid(fd, &peer->uid, &peer->gid) != 0) {
		peer->uid = (uid_t)-1;
		peer->gid = (gid_t)-1;
	}

The failure case is nicely handled: if getpeereid fails, the peer gets uid and gid of (uid_t)-1, and every ACL lookup for them fails. It fails closed.

The check itself is in server-acl.c:

 c
 
 
static struct server_acl_entry *
server_acl_check(struct client *c)
{
	struct server_acl_entry	*entry;
	uid_t			 uid;
	gid_t			 gid;

	uid = proc_get_peer_uid(c->peer);
	if (uid == (uid_t)-1)
		return (NULL);

	entry = server_acl_entry_find(uid, 0);
	if (entry != NULL)
		return (entry);

	gid = proc_get_peer_gid(c->peer);
	if (gid == (uid_t)-1)
		return (NULL);

	return (server_acl_entry_find(gid, SERVER_ACL_IS_GROUP));
}

So the policy is:

the uid entry wins if there is one; only otherwise is the gid consulted,
there’s no “other” or “anyone” entry type — only users and groups,
each entry is either read-only or read-write,
root is always allowed, and the owner is always allowed, and neither can be changed.

The default policy is set in server_acl_init():

 c
 
 
void
server_acl_init(void)
{
	RB_INIT(&server_acl_entries);

	if (getuid() != 0)
		server_acl_allow(0, 0);
	server_acl_allow(getuid(), 0);
}

Note the entries live in a plain in-memory red-black tree. There’s no ACL file. Restart the server and the list is gone. That’s a deliberate trade-off: it keeps the attacker’s ability to write to a well-known configuration file out of the picture.

The server-access command is a thin wrapper over this. It resolves names with getpwnam()/getgrnam(), refuses to change the owner or root, and treats -r/-w as implying -a:

 c
 
 
	if ((~flags & SERVER_ACL_IS_GROUP) && (id == 0 || id == getuid())) {
		cmdq_error(item, "%s owns the server, can't change access", name);
		return (CMD_RETURN_ERROR);
	}

Read-only is enforced in two places

A read-only ACL entry sets CLIENT_READONLY on the joining client (server_acl_join()). That flag is then checked twice:

in cmd-queue.c, a read-only client may only run commands whose entry has the CMD_READONLY flag:

 c
 
 
	flags = !!(state->flags & CMDQ_STATE_CONTROL);
	cmdq_guard(item, "begin", flags);
	if (flags &&
	 saved != NULL &&
	 (saved->flags & CLIENT_READONLY) &&
	 (~entry->flags & CMD_READONLY)) {
		cmdq_error(item, "client is read-only");

in format.c, shell jobs in formats are disabled outright for read-only clients:

 c
 
 
	if (c != NULL && (c->flags & CLIENT_READONLY))
		ft->flags |= FORMAT_NOJOBS;

That second one is the important one, because #(command) inside a format string is a shell execution, and a status line is a format string.

The ACL is only consulted at accept time

server_accept() is the only place the ACL gates entry:

 c
 
 
	c = server_client_create(newfd);
	if (!server_acl_join(c)) {
		c->exit_message = xstrdup("access not allowed");
		c->retval = 1;
		c->flags |= CLIENT_EXIT;
	}

Clients that are already connected are only re-evaluated when the ACL itself is changed — and even then, only for deny/allow-write/deny-write operations, not for a plain server-access -a, because server_acl_update() isn’t called from server_acl_allow(). A client that connected before you added it to the ACL keeps its access.

Also worth noting: the very first client — the one that caused the server to start — is created directly in server_client_create() and never passes through server_accept(), so it’s implicitly authorised.

The execute bit dance

There’s one more piece of socket permission logic, in server_update_socket():

 c
 
 
/* Update socket execute permissions based on whether sessions are attached. */
void
server_update_socket(void)
{
	struct session	*s;
	static int	 last = -1;
	int		 n, mode;
	struct stat sb;

	n = 0;
	RB_FOREACH(s, sessions, &sessions) {
		if (s->attached != 0) {
			n++;
			break;
		}
	}

	if (n != last) {
		last = n;

		if (stat(socket_path, &sb) != 0)
			return;
		mode = sb.st_mode & ACCESSPERMS;
		if (n != 0) {
			if (mode & S_IRUSR)
				mode |= S_IXUSR;
			if (mode & S_IRGRP)
				mode |= S_IXGRP;
			if (mode & S_IROTH)
				mode |= S_IROTH;
		} else
			mode &= ~(S_IXUSR|S_IXGRP|S_IXOTH);
		chmod(socket_path, mode);
	}
}

On a UNIX socket the “execute” bit means “may connect”. tmux adds it while a session is attached and removes it when nothing is attached, so an idle server isn’t accepting connections from a group that has access to the directory.

The stat()/chmod() pair follows symlinks, which is a small sharp edge when -S points into a world-writable directory.

What this means in practice

The threat model is simple to state and worth internalising:

Anyone who can connect() to the socket owns the session. There’s no second factor. tmux -S /tmp/x attach as an allowed user gives full command execution, including run-shell, source-file and #() format jobs.
The default socket is group-writable. Being in the right group is equivalent to being the user who started the server. Use -S with a private path if that matters, or set an explicit ACL.
The ACL is coarse. It’s uid or gid, read-only or read-write. There’s no per-command policy, and it doesn’t survive a restart.
Read-only is a genuinely useful downgrade, because it also disables shell jobs in formats — the usual way an untrusted user would try to get code execution out of a status line.

Wrapping up

The design is defensible. tmux assumes the socket directory is a trusted per-user boundary, and it defends that boundary carefully. The lstat() check, the ownership check, the .. rejection and the 0700 directory are all there specifically because /tmp is hostile.

What it doesn’t do is pretend that being able to open the socket is the same as being harmless.

Here’s the thing: the model is “the socket is the credential”. That’s fine for a single-user desktop, and it’s the reason tmux needs no password machinery at all. But the moment you share a tmux server, you’re sharing a shell, and the only knob is server-access -r.

tmux Format Expansion Runs Shell Commands: A Template Language With a Footgun

Jay Hubbert — Mon, 27 Jul 2026 11:00:00 +0000

TL;DR: tmux formats are code, and they execute where they’re expanded. #(command) runs a shell, #{VAR} splices an environment variable in verbatim, and #{E:VAR} re-expands that value as a format — which turns a plain environment variable into shell execution.

tmux formats are strings with #{...} holes in them. The status line, the pane border, display-message, the #{...} interpolation in hook commands — all of them are format strings, and the format language has grown a surprising amount of power: it can run shell commands, read environment variables, and re-expand its own output.

This is the anatomy of that language, and the places where it stops being a templating convenience and starts being a security-relevant primitive.

The pieces

The format language lives in format.c (about 7300 lines). The core syntax handled by format_expand1():

Syntax	Meaning
`#{name}`	Look up a format variable (`window_name`, `pane_pid`, …)
`#{name:modifier}`	Look up with modifiers (`:s/a/b/`, `:t`, `:p`, …)
`#(command)`	Run a shell command and use its output
`##[style]`	Look up a style
`%%`	A literal `%`

Every command that takes a format expands it before doing anything else. run-shell, if-shell, pipe-pane, display-message, send-keys, new-window, split-window, set-option for format options, and the status line itself.

The shell escape hatch

#(command) runs a command. The implementation is format_job_get():

 c
 
 
/* Find a job. */
static char *
format_job_get(struct format_expand_state *es, const char *cmd)
{
	...
	fj0.tag = ft->tag;
	fj0.cmd = cmd;
	if ((fj = RB_FIND(format_job_tree, jobs, &fj0)) == NULL) {
		fj = xcalloc(1, sizeof *fj);
		fj->client = ft->client;
		fj->tag = ft->tag;
		fj->cmd = xstrdup(cmd);

		RB_INSERT(format_job_tree, jobs, fj);
	}

	format_copy_state(&next, es, FORMAT_EXPAND_NOJOBS|
	 FORMAT_EXPAND_NOCYCLE);
	next.flags &= ~FORMAT_EXPAND_TIME;

	expanded = format_expand1(&next, cmd);
	...
	if (force || (fj->job == NULL && fj->last != t)) {
		fj->job = job_run(expanded, 0, NULL, NULL, NULL,
		 server_client_get_cwd(ft->client, NULL), format_job_update,
		 format_job_complete, NULL, fj, JOB_NOWAIT, -1, -1);

Four things worth noticing:

The command is format-expanded first (format_expand1(&next, cmd)), so a job command can itself contain #{...} substitutions.
The expansion is done with FORMAT_EXPAND_NOJOBS, so jobs don’t recurse into more jobs.
Results are cached per client in a red-black tree keyed on the command string and the format tag, and the cache is refreshed at most once per second unless FORMAT_FORCE is set. A status line with #(date) doesn’t fork a shell sixty times a second.
job_run() with JOB_NOWAIT means the job runs in the background and the previous result is returned until the new one lands. That’s why a slow command in a status line shows stale output for a second rather than blocking the redraw.

That last point is genuinely nice design. The status line stays responsive even when your format is running curl.

The environment variable fallback

This is the subtle one. If a format key is not a known format and not an option, tmux falls back to looking it up as an environment variable (format.c):

 c
 
 
	if (~modifiers & FORMAT_TIMESTRING) {
		envent = NULL;
		if (ft->s != NULL)
			envent = environ_find(ft->s->environ, key);
		if (envent == NULL)
			envent = environ_find(global_environ, key);
		if (envent != NULL && envent->value != NULL) {
			found = xstrdup(envent->value);
			goto found;
		}
	}

So #{HOME} in a format expands to the environment variable HOME. The session environment is consulted first, then the global environment.

That means an environment variable can be printed into a status line, into a control-mode notification, or into the argument of run-shell:

tmux

set -g status-right '#(echo $SECRET)'

The environment variable’s value is inserted verbatim, with no escaping. Whatever ends up in the status line ends up on the user’s screen (and, if the client is a control-mode client, on the wire).

Re-expansion: the `E` and `T` modifiers

The E modifier expands the value again as a format (format.c):

 c
 
 
done:
	/* Expand again if required. */
	if (modifiers & FORMAT_EXPAND) {
		new = format_expand1(es, value);
		free(value);
		value = new;
	} else if (modifiers & FORMAT_EXPANDTIME) {
		format_copy_state(&next, es, FORMAT_EXPAND_TIME);
		new = format_expand1(&next, value);
		free(value);
		value = new;
	}

#{E:SOMEVAR} takes the value of SOMEVAR and parses it as a format string. #{T:SOMEVAR} does the same with time formats enabled.

This is the classic escalation path. If an attacker can set an environment variable whose value contains #{...} or #(cmd), and something expands that variable with the E modifier, the value becomes live format text — and #(cmd) is live shell execution.

The E modifier isn’t enabled by default for every consumer, but it is available to anyone who can write a format string. That includes anyone who can write a tmux.conf or a hook.

`${VAR}` in the command language

Formats aren’t the only expansion mechanism. The tmux command parser also expands environment variables, and it does so by raw string splicing. From cmd-parse.y:

 c
 
 
	envent = environ_find(global_environ, name);
	if (envent != NULL && envent->value != NULL) {
		value = envent->value;
		log_debug("%s: %s -> %s", __func__, name, value);
		yylex_append(buf, len, value, strlen(value));
	}

The value is appended to the token buffer as-is. It is not re-quoted, not re-escaped and not re-scanned. So a global environment variable whose value contains a quote, a semicolon or a space changes the meaning of the command being parsed.

set-environment -g writes to the global environment, and the global environment is what the parser reads. That’s a genuine injection path from “can set a global environment variable” to “can run arbitrary tmux commands, including run-shell”.

The parser’s quoting rules are subtle and have been fixed several times. cmd_template_replace() in cmd.c documents the intended behaviour:

 c
 
 
/*
 * Replace the first %% or any %idx in template by s. %% is intended for use in
 * single quotes, so ' is escaped. %%% and %idx% are for double quotes, so a
 * list of special characters is escaped. %idx is left unescaped.
 */

with the double-quote set "\"\\$;~" and single quotes doubled. The %% behaviour was tightened in commit a177d0f5 — “Change %% to escape single quotes … to avoid a single quote being able to terminate quoted sections of commands” — because a single quote in the substituted value could otherwise close a quoted section early.

Hooks: expand, then parse

Hooks take the union of formats and commands. hooks_parse() in hooks.c:

 c
 
 
/* Parse a hook command. */
static struct cmd_parse_result *
hooks_parse(struct hooks_data *hd, struct cmd_find_state *fs,
 const char *value)
{
	struct cmd_parse_result	*pr;
	struct format_tree		*ft;
	char			*expanded;

	if (!hd->expand)
		return (cmd_parse_from_string(value, NULL));

	ft = format_create_defaults(NULL, hd->client, fs->s, fs->wl, fs->wp);
	if (hd->formats != NULL)
		format_merge(ft, hd->formats);
	expanded = format_expand(ft, value);
	format_free(ft);

	pr = cmd_parse_from_string(expanded, NULL);
	free(expanded);
	return (pr);
}

The hook command text is format-expanded and then parsed as tmux commands. For monitor-based hooks, the expansion includes the monitored value — a window name or a pane title — which is attacker-influenced text if some other user can rename a window.

hooks.c builds the format tree with FORMAT_NOJOBS, so the expansion itself won’t run a shell job. But the result is still parsed as commands, so a monitored value containing ; or a newline that survives sanitisation is a problem.

This is why the sanitisation of names matters, and it’s the subject of How tmux Sanitises Window Names Against Injection.

The read-only escape hatch

For clients that are read-only (via server-access -r), shell jobs in formats are switched off entirely:

 c
 
 
	if (c != NULL && (c->flags & CLIENT_READONLY))
		ft->flags |= FORMAT_NOJOBS;

and format_expand1() honours the flag:

 c
 
			if ((ft->flags & FORMAT_NOJOBS) ||

so #(cmd) expands to nothing at all. This is the single most important mitigation for a shared tmux server: a read-only client cannot get code execution through the status line, through display-message, or through any format-consuming command.

Summary of the attack surface

Primitive	Where it comes from	Consequence
`#(cmd)`	any format string	shell execution as the server user
`#{VAR}`	environment variable	value injected verbatim into output
`#{E:VAR}`	environment variable	value reinterpreted as format, so `#(cmd)` inside it runs
`${VAR}` in the parser	global environment	raw splice into the command being parsed
hook expansion	monitored value	user text parsed as tmux commands
`%%` / `%1` substitution	command arguments	quoting subtleties, historically exploitable

Wrapping up

The unifying theme: tmux formats are code, and they execute where they are expanded.

Every mitigation lives in the same family — decide early whether the client is trusted, and refuse to expand untrusted text into a format or a command.

Two things to internalize. First, never let untrusted text reach a format that uses E or T; that modifier turns a data value into code. Second, if you’re running a shared tmux server, server-access -r is the single switch that turns off the worst of it.

tmux Stores Grid Cells in Five Bytes

Jay Hubbert — Wed, 22 Jul 2026 08:00:00 +0000

TL;DR: tmux splits a grid cell into two representations: a fat 32-byte in-memory form and a packed 5-byte stored form. The union makes the choice free — the same five bytes are either attributes, colours and a character, or an offset into a side table for the rare cells that need RGB, wide characters or hyperlinks.

A terminal grid cell isn’t small. In the “in-memory” representation it holds a UTF-8 character (up to four bytes), a foreground colour, a background colour, an underline colour, a set of attribute bits, a hyperlink id and some flags. That’s comfortably 32 bytes per cell.

Multiply by 80x24 and you get 61 KB per screen. Multiply by 10,000 lines of scrollback and 200 panes, and it’s gigabytes.

tmux’s answer is a split representation: the common case is packed into five bytes, and the rare case lives in a side table.

The two representations

The in-memory form (tmux.h) is the “fat” one:

 c
 
 
/* Grid cell data. */
struct grid_cell {
	struct utf8_data	data;
	u_short			attr;
	u_char			flags;
	int			fg;
	int			bg;
	int			us;
	u_int			link;
};

struct utf8_data alone is six bytes, and the three int colours are twelve. So the fat cell is around 32 bytes.

The stored form is the packed one:

 c
 
 
/* Grid cell entry. */
struct grid_cell_entry {
	union {
		u_int		offset;
		struct {
			u_char	attr;
			u_char	fg;
			u_char	bg;
			u_char	data;
		} data;
	};
	u_char			flags;
} __packed;

The union is the trick. The same five bytes are either:

data.attr (8 bits of attributes), data.fg (8-bit colour), data.bg (8-bit colour), data.data (the character), plus flags — the packed form, or
offset — an index into the line’s array of grid_extd_entry — the extended form.

__packed matters: without it the compiler would pad the struct to eight bytes and the whole optimisation would evaporate.

The extended form:

 c
 
 
/* Grid extended cell entry. */
struct grid_extd_entry {
	utf8_char		data;
	u_short			attr;
	u_char			flags;
	int			fg;
	int			bg;
	int			us;
	u_int			link;
} __packed;

has room for everything: RGB colours, wide characters, more than eight attribute bits, hyperlinks.

Deciding which form to use

The decision is made by grid_need_extended_cell():

 c
 
 
/* Check if a cell should be an extended cell. */
static int
grid_need_extended_cell(const struct grid_cell_entry *gce,
 const struct grid_cell *gc)
{
	if (gce->flags & GRID_FLAG_EXTENDED)
		return (1);
	if (gc->attr > 0xff)
		return (1);
	if (gc->data.size > 1 || gc->data.width > 1)
		return (1);
	if ((gc->fg & (COLOUR_FLAG_RGB|COLOUR_FLAG_THEME)) ||
	 (gc->bg & (COLOUR_FLAG_RGB|COLOUR_FLAG_THEME)))
		return (1);
	if (gc->us != 8) /* only supports 256 or RGB */
		return (1);
	if (gc->link != 0)
		return (1);
	if (gc->flags & GRID_FLAG_TAB)
		return (1);
	return (0);
}

So a cell is extended if it has:

more than eight attribute bits,
a multi-byte or double-width character,
an RGB or theme colour,
an underline colour other than the default,
a hyperlink,
or is a tab.

Everything else — plain ASCII, 8-bit colours, standard attributes — is packed.

For a typical terminal session that’s nearly every cell. The 256-colour palette fits in eight bits, and the eight standard attribute bits (bold, underline, reverse, and so on) fit in eight bits.

Note the first line: once a cell is extended, it stays extended. That simplifies the code enormously — you never have to convert back — at the cost of not being able to compact a cell that has become simple again.

256 colours in eight bits

The colour packing is slightly more subtle than “eight bits of colour”:

 c
 
 
/* Store cell in entry. */
static void
grid_store_cell(struct grid_cell_entry *gce, const struct grid_cell *gc,
 u_char c)
{
	gce->flags = (gc->flags & ~GRID_FLAG_CLEARED);

	gce->data.fg = gc->fg & 0xff;
	if (gc->fg & COLOUR_FLAG_256)
		gce->flags |= GRID_FLAG_FG256;

	gce->data.bg = gc->bg & 0xff;
	if (gc->bg & COLOUR_FLAG_256)
		gce->flags |= GRID_FLAG_BG256;

	gce->data.attr = gc->attr;
	gce->data.data = c;
}

The colour value is 0-255 in the byte, and the flags record whether it came from the 256-colour palette or the 16-colour one, because “bright black” means different things in the two palettes. The RGB flag lives in COLOUR_FLAG_RGB, which is above 8 bits and therefore forces the extended form.

Lazy line growth

Lines aren’t allocated at full width up front. grid_expand_line() grows them in geometric steps:

 c
 
 
/* Expand line to fit to cell. */
static void
grid_expand_line(struct grid *gd, u_int py, u_int sx, u_int bg)
{
	struct grid_line	*gl;
	u_int			 xx;

	gl = &gd->linedata[py];
	if (sx <= gl->cellsize)
		return;

	if (sx < gd->sx / 4)
		sx = gd->sx / 4;
	else if (sx < gd->sx / 2)
		sx = gd->sx / 2;
	else if (gd->sx > sx)
		sx = gd->sx;

	gl->celldata = xreallocarray(gl->celldata, sx,
	 sizeof *gl->celldata);
	...
	gl->cellsize = sx;
}

The sizes are 1/4 width, 1/2 width, full width. So a program that prints one character on a fresh line allocates a quarter of a line, not a whole one, and a program that prints a few characters doesn’t repeatedly realloc.

The grid_line struct tracks cellused and cellsize separately, so the trailing cells of a mostly-empty line don’t need to be stored at all.

This was a deliberate change; the CHANGES file records:

“Create every line as zero length and only expand it as data is written, rather than creating at full size immediately.”

Not leaking extended cells

Extended cells are allocated from a per-line array. When a cell is overwritten with something simple, the extended entry it used would normally be leaked — the line’s extended array would grow forever as a program repaints the same line with different colours.

grid_clear_cell() reuses the existing slot:

 c
 
 
/* Copy default into a cell. */
static void
grid_clear_cell(struct grid *gd, u_int px, u_int py, u_int bg, int moved)
{
	struct grid_line	*gl = &gd->linedata[py];
	struct grid_cell_entry	*gce = &gl->celldata[px];
	struct grid_extd_entry	*gee;
	u_int			 old_offset = gce->offset;
	int			 had_extd = (gce->flags & GRID_FLAG_EXTENDED);

	memcpy(gce, &grid_cleared_entry, sizeof *gce);
	if (!moved && had_extd && old_offset < gl->extdsize) {
		gce->flags |= GRID_FLAG_EXTENDED;
		gce->offset = old_offset;
		gee = grid_extended_cell(gl, gce, &grid_cleared_cell);
		if (bg != 8)
			gee->bg = bg;
	} else if (bg != 8) {
		...

Note old_offset being saved and restored: the cell keeps its extended form and its slot in the extended array, it just gets reset to the cleared state. The commit message for this was:

“Reuse extended entry when clearing RGB cell, to prevent memory growth.”

And the extended array itself is compacted when the line shrinks:

 c
 
 
/* Free up unused extended cells. */
static void
grid_compact_line(struct grid_line *gl)
{
	int			 new_extdsize = 0;
	...
	for (px = 0; px < gl->cellsize; px++) {
		gce = &gl->celldata[px];
		if (gce->flags & GRID_FLAG_EXTENDED)
			new_extdsize++;
	}
	...
	idx = 0;
	for (px = 0; px < gl->cellsize; px++) {
		gce = &gl->celldata[px];
		if (gce->flags & GRID_FLAG_EXTENDED) {
			gee = &gl->extddata[gce->offset];
			memcpy(&new_extddata[idx], gee, sizeof *gee);
			gce->offset = idx++;
		}
	}

	free(gl->extddata);
	gl->extddata = new_extddata;
	gl->extdsize = new_extdsize;
}

This is a mark-and-sweep compaction: count the live extended cells, allocate a new array of exactly that size, copy them over, and fix up the offsets. The old array is freed. The cell’s offset changes, which is why this can’t be done while the grid is being read by anything else.

History trimming

Scrollback is the other place memory grows without bound. When the history hits the limit, tmux frees the oldest 10% rather than one line at a time:

 c
 
 
/*
 * Collect lines from the history if at the limit. Free the top (oldest) 10%
 * and shift up.
 */
void
grid_collect_history(struct grid *gd, int all)

and the shift itself is a memmove() of the line array:

 c
 
 
void
grid_trim_history(struct grid *gd, u_int ny)
{
	u_int	remaining;

	grid_free_lines(gd, 0, ny);
	remaining = gd->hsize + gd->sy - ny;
	memmove(&gd->linedata[0], &gd->linedata[ny],
	 remaining * (sizeof *gd->linedata));
	memset(&gd->linedata[remaining], 0, ny * (sizeof *gd->linedata));
}

Trimming one line at a time would be O(n) per line of output, which is O(n²) over a full history. Trimming 10% at a time is O(n) per 10% of the history.

The CHANGES file dates this to 2007:

“Rather than shifting up one line at a time once the history is full, shift by 10% of the history each time. This is faster.”

The allocation helpers

All of this depends on allocation being cheap and safe. xmalloc.c provides xmalloc, xcalloc, xreallocarray, xrecallocarray and xmemdup, all of which abort the process on failure rather than returning NULL:

 c
 
 
void *
xcalloc(size_t nmemb, size_t size)
{
	void *ptr;

	if (size == 0 || nmemb == 0)
		fatalx("xcalloc: zero size");
	if (SIZE_MAX / nmemb < size)
		fatalx("xcalloc: nmemb * size > SIZE_MAX");
	ptr = calloc(nmemb, size);
	if (ptr == NULL)
		fatal("xcalloc: allocating %zu bytes", size * nmemb);
	return (ptr);
}

The overflow check is the interesting part: nmemb * size is computed in calloc() too, but the check has to happen first, in a form that can’t itself overflow.

Because allocation never returns NULL, no hot path has to check for it, and the xreallocarray() variants make the “array of n things” case safe by default.

The numbers

For an 80x24 pane of plain text:

Representation	Bytes per cell	Total
Fat `grid_cell`	~32	61 KB
Packed `grid_cell_entry`	5	9.6 KB

With 10,000 lines of scrollback per pane and 20 panes, the difference is about 1 GB versus 160 MB.

Wrapping up

The general technique here — a packed common case and an out-of-line rare case — is the same one used by Python’s compact dicts, PostgreSQL’s varlena headers, and the Linux kernel’s struct file_operations.

The key insight is that the in-memory representation used during manipulation and the stored representation used for retention don’t have to be the same.

tmux gets to have both, because the fat form is only materialised one cell at a time, on the stack, while parsing and drawing. The grid — the thing that lives for hours and grows without bound — is the packed one.

Tmux on Opensource internals

tmux Parses Escape Sequences Fast: Four Boring Optimisations That Matter

The parser: a state machine with tables

The collect-buffer optimisation

Binary search over the CSI table

Bounded buffers

The other direction: terminal key sequences

The escape timeout

UTF-8 and the width cache

Why the widths are so complicated

Wrapping up

tmux Splits the Terminal into Panes: A Tree, Not a Geometry Problem

The tree

The seven presets

Spreading the space

Serialisation: the JSON layout string

The old format

Parsing is not just parsing

Resizing

Window sizing policy

Wrapping up

tmux Sanitises Window Names Against Injection

The function

Why vis(3) and not a hand-rolled check

Where it is applied

The history

What is not defended

Wrapping up

Why tmux Needs Its Own Terminal Emulator

The reason in one sentence

What ncurses gives you

The four requirements ncurses cannot meet

1. Several independent screens

2. The terminal is not the target

3. The application and the multiplexer both think they own the screen

4. The multiplexer is itself a terminal user

What tmux implements instead

The parser

The screen model

The write path

The scrollback and reflow

The performance angle

The cost

Wrapping up

tmux Control Mode Is an Unauthenticated Command Channel

What control mode looks like

Reading commands

The reply framing

Where the protocol gets interesting: the raw sink

A note on window names

DoS protections

Using it responsibly

Wrapping up

tmux Runs Real ptys for Every Pane

Creating the pty

Why that matters: job control

The SIGTTIN problem

The outer terminal is a different story

Resizing: the storm problem

Not blocking the application

Background jobs without a pty

Wrapping up

tmux Batches Terminal Output: One Write() Per Event Loop Iteration

One buffer per client

One write() per iteration

The slow terminal problem

Deferring redraws until the buffer drains

Caching the terminal’s attribute state

Terminfo strings are resolved once

The raw mode handshake

Putting the numbers together

Wrapping up

tmux Works Around Terminal Bugs: Believe Nothing, Probe Everything

Layer 1 and 2: terminfo and overrides

Layer 3: named features

Layer 4: asking the terminal

The “is it VT100-like?” hack

Layer 5: the per-terminal table

Individual workarounds

The !am terminal

Why `vis(3)` and not a hand-rolled check

The `!am` terminal

One rough edge: the `-L` label

Re-expansion: the `E` and `T` modifiers

`${VAR}` in the command language