ANSI Escape Sequences — the Wire Protocol

Raw mode gave us a byte pipe with no kernel meddling. Now: what do the bytes mean? How does htop paint bars in the middle of the screen, how does vim turn a line yellow, how does anything ever un-print?

The answer is an in-band protocol: special byte sequences, mixed right into the output stream, that the terminal interprets as commands instead of printing. There is no second channel — no ioctl for "move the cursor", no side API for "make it red". The screen is programmed entirely through the same fd the text flows through. This design is why output can be piped, logged, replayed, and sent over ssh without anyone in the middle understanding it — and why cat-ing a binary file can wreck your terminal (you just fed it random commands).

A short history you actually need

Every terminal vendor of the 1970s invented its own control codes, and portable software drowned in the differences (the termcap database, and later terminfo, exist to catalogue that chaos — more below). ANSI standardized a common language in ANSI X3.64 (1979), which grew into ECMA-48 / ISO 6429. DEC's VT100 (1978) was the hit implementation, so the family is called "ANSI escape codes" and "VT100 sequences" interchangeably. Everything since — xterm, Linux console, tmux, kitty, iTerm2, Windows Terminal — is a VT100 descendant with extensions. Implement the VT100 core and you speak to fifty years of software.

The byte grammar

Codes 0x00–0x1F are the C0 control characters — the originals, each one a tiny command:

Byte	Name	Meaning
0x07	BEL	ring the bell
0x08	BS	cursor left one column (doesn't erase!)
0x09	HT	tab: cursor to next tab stop (every 8 by default)
0x0A	LF	cursor down one row
0x0D	CR	cursor to column 1
0x1B	ESC	the escape: the next bytes are a command

Multi-byte commands start with ESC (0x1B, "\x1b", sometimes written ^[). ESC followed by most single characters is a simple command (ESC 7 save cursor, ESC 8 restore, ESC c full reset). But the workhorse is ESC followed by [ — the Control Sequence Introducer (CSI) — which begins a parameterized command:

CSI  =  ESC [
full sequence  =  ESC [ <parameters> <intermediates> <final byte>

• Parameters (bytes 0x30–0x3F): decimal numbers separated by ;, e.g. 12;40. Empty slots are allowed and mean "default": ESC[;5H has an empty first parameter. A leading ? marks a private parameter space (DEC's extensions live there).
• Intermediates (0x20–0x2F): rare; you can ignore them for years.
• Final byte (0x40–0x7E): one character that names the command. The final byte is what dispatches — H is "cursor position" whether it has zero, one, or two parameters.

This grammar is fixed and machine-readable without understanding the command, which is what makes a clean parser possible (two lessons from now): you always know where a sequence ends.

The sequences that matter

Cursor movement:

ESC [ <r> ; <c> H    CUP   cursor to row r, column c (1-BASED! both default 1)
ESC [ <n> A          CUU   up n rows        (n defaults to 1)
ESC [ <n> B          CUD   down n
ESC [ <n> C          CUF   right n
ESC [ <n> D          CUB   left n

Row and column are 1-based: ESC[1;1H (or just ESC[H) is the top-left corner. Fifty years of off-by-one bugs live in that fact — your C code counts from 0, the wire counts from 1, and the conversion belongs in exactly one place in your program.

Erasing (these do not move the cursor):

ESC [ 0 J    ED    erase cursor -> end of screen   (0 = default)
ESC [ 1 J          erase start of screen -> cursor
ESC [ 2 J          erase entire screen
ESC [ 0 K    EL    erase cursor -> end of line     (0 = default)
ESC [ 1 K          erase start of line -> cursor
ESC [ 2 K          erase entire line

ESC[K after redrawing a line's content is the cheap way to clear stale tail characters — you'll use it in the renderer, it beats clearing the whole screen and repainting.

DEC private modes — set with final h, reset with l:

ESC [ ? 25 h / l     show / hide the cursor
ESC [ ? 1049 h / l   enter / leave the ALTERNATE SCREEN
ESC [ ? 2004 h / l   bracketed paste on / off

Hiding the cursor while repainting kills the ghostly flicker of a cursor teleporting through a redraw. The alternate screen is the trick behind vim and less feeling like "apps": a second framebuffer with no scrollback; enter it on startup, leave on exit, and the user's shell history reappears untouched.

Finally, ESC ] ... (note ], not [) starts an OSC — Operating System Command — string, terminated by BEL or ESC \. OSC 0 sets the window title: ESC ] 0 ; my title BEL. Your parser must at least skip these correctly, or one title-setting program will desync your whole stream.

Colors and attributes: SGR

The final byte m — Select Graphic Rendition — takes a list of attribute codes and is by far the most-sent sequence in practice:

Code	Effect
0	reset everything to default
1	bold
4	underline
7	reverse video (swap fg/bg — your status bar)
30–37	foreground: black, red, green, yellow, blue, magenta, cyan, white
39	default foreground
40–47 / 49	background versions of the same
90–97	bright foreground variants

Codes chain in one sequence: ESC[1;33;44m = bold yellow on blue. And SGR is stateful: it sets the current brush, which applies to everything printed until changed. Forget ESC[0m and your prompt inherits your last color — a bug you have certainly already seen in the wild.

Two modern extensions squeeze bigger palettes through the same door:

ESC [ 38 ; 5 ; <n> m         foreground from a 256-color palette
ESC [ 48 ; 5 ; <n> m         background, same palette
ESC [ 38 ; 2 ; <r> ; <g> ; <b> m    24-bit "truecolor" foreground
ESC [ 48 ; 2 ; <r> ; <g> ; <b> m    truecolor background

Note what 38;5;208 implies for parsers: parameters are no longer independent — 5 and 208 are arguments of 38. Keep that in mind when you write yours.

Where do sequences come from in practice? (terminfo)

Not every terminal supports every sequence, and historically they disagreed wildly. The terminfo database (query it with infocmp; the $TERM env var picks the entry) maps capability names to the bytes each terminal wants, and libraries like ncurses read it so programs don't hardcode. We will hardcode the VT100/xterm core — every terminal you'll meet this decade speaks it — but you should know why TERM=dumb make and ncurses exist, and what breaks when $TERM lies.

Try the protocol by hand right now — no code needed:

$ printf '\x1b[2J\x1b[10;20HHello\x1b[0m'
$ printf '\x1b[1;31mred and bold\x1b[0m plain\n'
$ printf '\x1b[?25l'; sleep 2; printf '\x1b[?25h'   # cursor vanishes

int n = ansi_cursor_move(buf, sizeof(buf), 5, 10);
/* buf now holds "\x1b[5;10H", n == 7 */

enum color_mode { COLOR_DEFAULT, COLOR_BASIC, COLOR_256, COLOR_RGB };

struct color {
    enum color_mode mode;
    unsigned char idx;      /* BASIC: 0-7, C256: 0-255 */
    unsigned char r, g, b;  /* RGB */
};

struct style {
    struct color fg, bg;
    unsigned bold : 1, underline : 1, reverse : 1;
};