Terminal Standards

Terminal Standards, Escape Sequences, and Capability Negotiation

Use this skill when code emits or parses terminal control sequences, depends on terminal features, or must behave across emulators, multiplexers, and Windows console hosts.

Standards hierarchy

Think in layers:

1. Baseline: printable text, carriage return, newline, backspace, tab. 2. ECMA-48 / ANSI / ISO 6429: CSI controls and SGR attributes. 3. DEC VT lineage: cursor movement, alternate keypad modes, device status patterns, private modes. 4. xterm conventions: alternate screen, mouse modes, focus events, bracketed paste, OSC extensions. 5. Modern emulator extensions: Kitty keyboard/graphics, iTerm2 images, sixel, OSC 8 hyperlinks, OSC 52 clipboard, theme queries. 6. Platform host behavior: Windows virtual terminal processing, ConPTY, tmux/screen filtering, SSH latency.

The further down this stack you go, the more you need detection, fallbacks, and cleanup.

Safer defaults

• Prefer framework abstractions and terminfo/capability libraries over hard-coded control sequences.
• Reset styles deliberately; do not rely on terminal defaults after complex SGR output.
• Treat unknown responses, missing responses, and blocked queries as normal.
• Never require clipboard, images, focus events, or extended keyboard protocols for core functionality.
• When enabling a mode, register a cleanup path before continuing.

Common sequences and caveats

See references/escape-sequence-field-guide.md for detailed tables.

Capability negotiation checklist

• Is stdout a TTY? If not, avoid cursor controls and interactive modes by default.
• Is TERM meaningful? Handle dumb, empty, and unknown values.
• Is the app inside tmux/screen? Assume some protocols are filtered or need passthrough.
• Is Windows VT processing enabled for classic console APIs?
• Does the library expose color level detection? Prefer it over ad hoc environment parsing.
• Are user overrides available: --color, --no-color, --plain, --ascii, --no-mouse?
• Are query timeouts bounded so the app does not hang waiting for terminal replies?

Cleanup contract

If enabling raw mode, alternate screen, mouse tracking, bracketed paste, focus events, cursor hiding, or keyboard protocols, verify cleanup on normal quit, Ctrl-C, panic, exception, fatal error, failed partial initialization, and test assertion failures.

Reference files

• references/escape-sequence-field-guide.md - ANSI/VT/xterm controls and cautions.
• references/capability-negotiation.md - Detection and fallback patterns across terminals.

Capability Negotiation Reference

Detection sources

Use multiple weak signals rather than one magic variable:

• TTY checks for stdin/stdout/stderr.
• TERM, COLORTERM, TERM_PROGRAM, WT_SESSION, TMUX, STY, SSH_TTY.
• Framework/library color and terminal feature detection.
• terminfo where available.
• Bounded terminal queries where safe.
• Explicit user flags and config, which should win over auto-detection.

User override precedence

1. Explicit CLI flags such as --color=always|auto|never, --plain, --tui, --no-tui, --ascii. 2. Environment variables such as NO_COLOR, CLICOLOR, CLICOLOR_FORCE, FORCE_COLOR, TERM=dumb. 3. TTY and terminal detection. 4. Conservative defaults.

Multiplexer considerations

Inside tmux or screen, feature claims may describe the multiplexer rather than the outer terminal. Some sequences are translated, blocked, or require passthrough. Test alternate screen, mouse, bracketed paste, clipboard, focus events, and truecolor under the multiplexer versions you claim to support.

Windows considerations

Modern Windows Terminal and ConPTY support broad VT behavior. Classic console hosts may require enabling virtual terminal processing. Avoid assuming Unix PTY semantics on Windows; ConPTY has different buffering and process-hosting behavior that matters for tests and embedding child TUIs.

Escape Sequence Field Guide

Naming and byte forms

Prefer 7-bit escape forms in application output. Many terminals accept 8-bit C1 controls, but UTF-8 byte streams, log processors, PTYs, and security filters commonly assume the ESC-prefixed form.

Practical CSI table

SGR rules and reset edge cases

Implementation pattern:

render(style, text): SGR(style) + sanitize(text) + SGR(reset_to_parent_or_0)

Do not concatenate independently styled fragments without knowing the active parent style. If a bold red label is followed by red normal text, use 22 instead of 0 when preserving the foreground matters. If style nesting is hard, emit 0 then reapply the parent style at every boundary.

DEC private modes and alternate screen variants

DEC private modes use CSI ? number h to set and CSI ? number l to reset.

For full-screen apps, use a guard that enters ?1049h, enables raw/input modes as needed, hides cursor only around rendering if desired, and reverses modes in opposite order. Multiplexers or user settings may inhibit alternate screen; your app should still quit cleanly.

OSC and DCS tables

OSC termination:

• BEL termination: ESC ] 0;title BEL is common for titles and older tools.
• ST termination: ESC ] 8;;https://example.invalid ESC \\ label ESC ] 8;; ESC \\ is safer for nested contexts and avoids accidental BEL bytes in payload handling.
• When parsing, accept both BEL and ST. When emitting OSC 8 or long structured payloads, prefer ST.

DCS examples:

Tmux DCS passthrough pattern for OSC 52:

# Inner OSC: ESC ] 52 ; c ; BASE64 ST
# tmux DCS wrapper doubles ESC bytes inside the payload.
ESC P tmux ; ESC ESC ] 52 ; c ; BASE64 ESC ESC \\ ESC \\

In code, prefer a library that understands tmux passthrough. If hand-rolling, unit-test the exact bytes and provide a --no-clipboard or --clipboard=never switch.

Query timeout cautions

Terminal queries are optional. Never block startup indefinitely waiting for CSI 6 n, OSC palette responses, Kitty keyboard negotiation, or DA replies.

Recommended pattern:

1. Start with conservative defaults from flags, TTY detection, terminfo, and environment hints. 2. Send a query only after entering a mode where you can read terminal input without stealing user keystrokes. 3. Wait tens to a few hundred milliseconds depending on context; make timeout configurable for remote links only if necessary. 4. Accept malformed, missing, delayed, or interleaved replies without crashing. 5. Cache the capability decision for the session; do not query every frame.

Delayed replies can arrive after the timeout and look like user input. Input parsers must route recognized reports separately and ignore stale replies where possible.

Terminfo and termcap examples

Terminfo describes the terminal named by TERM, which may be a multiplexer such as screen-256color or tmux-256color, not the outer emulator.

Useful capabilities:

Shell checks during debugging:

infocmp "$TERM" | less
printf '%s\n' "TERM=$TERM COLORTERM=${COLORTERM-} TMUX=${TMUX-}"
tput colors
tput smcup; printf 'alternate\n'; sleep 1; tput rmcup

Use terminfo through framework APIs where possible. Hard-coded xterm sequences are acceptable only for controlled, documented targets or progressive enhancements with fallbacks.

Cursor and screen rules

• Cursor movement is safe only when stdout is an interactive terminal under the app's control.
• Avoid absolute cursor positioning in normal scrollback unless implementing a known inline progress region.
• Hide cursor only when you can restore it.
• Alternate screen is appropriate for full-screen TUIs, not for short commands where users expect scrollback.
• Logs must not contain raw control sequences from untrusted data; render escapes visibly in debug output.

Keyboard protocols

Legacy terminal keyboard encoding is ambiguous: Esc can mean Escape or Alt-prefix; Ctrl combinations collide with control bytes; function keys vary. Modern protocols can disambiguate, but must be optional. If enabling Kitty keyboard protocol or xterm modified-key modes, push mode on entry, pop it on exit, and preserve ordinary shortcuts as fallbacks.

Graphics and hyperlinks

OSC 8 hyperlinks, sixel, Kitty graphics, and iTerm2 images improve UX in capable terminals but are not universal. Provide text fallbacks. Do not put critical state only in an image or hyperlink.