Architecture on Opensource internals

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

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

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.