Terminal on Opensource internals

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

Terminal on Opensource internals

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

The PuTTY wrap flag

Cursor position after IL and DL

Bright colours on the Linux console

The Konsole scroll bug

Mouse mode reset

Bogus terminfo capabilities

Terminals that break when you set the title

The escape timeout is adaptive too

Wrapping up

The `!am` terminal