Terminal capabilities

This reference is for applications that must select terminal-dependent image, link, clipboard, notification, input, or pixel behavior.

renderer.capabilities is a supported snapshot. The regular-expression helpers that classify response sequences and the native response parser are internal detection machinery. Do not build application policy on their patterns.

Read a changing snapshot#

createCliRenderer() returns after it sends startup queries. It does not wait for the terminal to answer every query. Thus, a false field can mean either not yet detected or unsupported.

import { CliRenderEvents, createCliRenderer, type TerminalCapabilities } from "@opentui/core"

const renderer = await createCliRenderer()

function applyCapabilities(capabilities: TerminalCapabilities | null) {
  if (!capabilities) return
  console.log(capabilities.terminal.name, capabilities.image_protocol)
}

applyCapabilities(renderer.capabilities)
renderer.on(CliRenderEvents.CAPABILITIES, applyCapabilities)

Read the current snapshot first, then handle events. A response can arrive before your listener is attached.

The capability handler stays active for the whole session. A recognized response updates renderer.capabilities whenever it arrives, including after startup: GNU screen, tmux passthrough, and OpenSSH ConPTY can forward some replies late. "capabilities" is emitted only when the capabilities change. Expect several events during startup and occasionally later. Do not wait for one specific count or treat the first event as final.

The renderer consumes these responses before handlers added with addInputHandler run. Use prependInputHandler to observe them. The startup window ends when the terminal answers the device attributes (DA1) request that follows the startup queries, or after five seconds without an answer. Then the input parser stops treating private replies as expected responses. Pixel-resolution and theme queries have separate lifecycles.

Public types#

type TerminalCapabilityState = "unknown" | "supported" | "unsupported"
type TerminalMultiplexer = "none" | "tmux" | "zellij" | "screen" | "unknown"
type ImageRenderProtocol = "auto" | "kitty" | "sixel" | "blocks"

interface TerminalInfo {
  name: string
  version: string
  from_xtversion: boolean
}

name and version can come from environment heuristics before an XTVERSION response. from_xtversion is true only when OpenTUI parsed that response. Native storage bounds terminal names to 64 bytes and versions to 32 bytes.

TerminalCapabilities inventory#

Input, output, and width#

Field Type Meaning
kitty_keyboard boolean Kitty keyboard protocol support was detected or inferred
rgb boolean 24-bit RGB output is available
ansi256 boolean ANSI 256-color output is available
unicode WidthMethod Active "unicode" or "wcwidth" method in the public snapshot
explicit_width boolean OSC 66 explicit-width text was detected or forced
scaled_text boolean Scaled-text support was detected
focus_tracking boolean Terminal focus reports are supported
sync boolean Synchronized-output mode is supported
bracketed_paste boolean Bracketed paste is enabled or assumed available
explicit_cursor_positioning boolean OpenTUI should use explicit cursor positioning for this terminal path

bracketed_paste defaults to true in native environment setup, even when a query reports no support. It is not a pure probe result.

Images and pixels#

Field Type Meaning
kitty_graphics boolean Kitty graphics support was detected or inferred
sixel boolean Sixel support was detected or inferred
image_protocol Optional ImageRenderProtocol Active image-protocol override or "auto"
sgr_pixels boolean SGR pixel-coordinate mouse mode was reported

sgr_pixels does not make higher-level mouse events pixel-based. The current higher-level mouse path uses terminal cells.

renderer.resolution is separate from TerminalCapabilities. It is null until a valid terminal window-size response arrives. A PixelResolution has numeric width and height in terminal pixels. OpenTUI requeries it after resize.

Read Image for protocol selection. Do not choose a protocol from one early false value.

Field Type Meaning
hyperlinks boolean OSC 8 hyperlink output is enabled
osc52 boolean OSC 52 clipboard support was detected or inferred
osc52_support TerminalCapabilityState Query result when OpenTUI can distinguish unknown, supported, and unsupported
notifications boolean A notification protocol was selected
program_status boolean The terminal answered the OSC 7501 program status query

The renderer emits OSC 8 sequences only when hyperlinks is true. Text still renders when it is false. Without OSC 8, the terminal detects URLs one row at a time, so a wrapped URL opens only the part on the clicked row.

OpenTUI enables hyperlinks for Ghostty, Kitty, WezTerm, Alacritty, foot, iTerm2, Terminology, xterm.js, VS Code, Zed, mintty, VTE 0.52.2 or newer, and Windows Terminal. TERM_PROGRAM, VTE_VERSION, and WT_SESSION count only outside tmux, Zellij, and GNU Screen. WT_SESSION also needs TERM unset, empty, or starting with xterm. Set FORCE_HYPERLINK to override detection.

Hyperlink URLs use a native slot with a maximum of 512 UTF-8 bytes. A longer URL fails link allocation and the text loses its hyperlink metadata.

osc52 and osc52_support answer different questions. Environment and terminal-family heuristics can set osc52 while osc52_support remains "unknown". Read Clipboard for operation results and remote policy.

notifications does not expose the selected OSC variant. Use renderer.triggerNotification() and its boolean result. Read Notifications for protocol and multiplexer behavior.

renderer.setProgramStatus() does not depend on program_status. Terminals ignore OSC 7501 reports they do not implement. Read Program status.

Session and terminal identity#

Field Type Meaning
remote boolean The renderer uses remote-session policy
multiplexer TerminalMultiplexer Detected tmux, Zellij, GNU Screen, no multiplexer, or unknown state
terminal TerminalInfo Terminal name, version, and XTVERSION source flag
color_scheme_updates boolean Mode 2031 color-scheme update reports are supported

The snapshot object is replaced after a response. Do not retain one object and expect its fields to mutate.

Remote streams and environment forwarding#

CliRendererConfig.remote has three practical states:

  • true forces remote policy.
  • false forces local policy, even when SSH variables exist.
  • Omitted uses native auto-detection for process output and memory output.

A custom stdout that uses the native span feed defaults to remote: true. OpenTUI cannot assume that the process host terminal is the stream’s real peer.

Auto-detection recognizes SSH_CONNECTION, SSH_CLIENT, SSH_TTY, and MOSH_CONNECTION. In an auto-detected remote session, OpenTUI applies only the color depth keys from the forwarded environment: a TERM that contains 256color enables ansi256, and a COLORTERM of truecolor or 24bit, or OPENTUI_FORCE_TRUECOLOR=1, enables rgb and ansi256. These keys describe the remote endpoint: sshd takes TERM from the client’s PTY request, and COLORTERM comes from the client when ssh is configured to send it, or from the server session itself, such as a shell rc file. OpenTUI ignores the other keys, such as TERM_PROGRAM, the multiplexer variables, and the other OPENTUI_* overrides. On the process host, they can describe the wrong terminal endpoint. The width overrides OPENTUI_FORCE_WCWIDTH, OPENTUI_FORCE_UNICODE, and OPENTUI_FORCE_NOZWJ are an exception: they configure the app, so OpenTUI applies them whenever they are in the forwarded environment. GNU Screen is the other exception. It answers no query, so OpenTUI detects it from STY, or from a TERM that starts with screen without TMUX. This covers ssh started inside Screen, which forwards Screen’s TERM, and Screen started on the server. A tmux XTVERSION reply still selects tmux. A TMUX that is not empty, or a TERM that starts with tmux, is only a hint: OpenTUI leaves out the startup graphics query, which tmux would show as the pane title before its XTVERSION reply arrives. This covers a tmux server started from an ssh login, whose panes inherit SSH_CONNECTION, and ssh started inside tmux, which forwards tmux’s TERM. The hint does not detect tmux: until the XTVERSION reply names it, clipboard framing and the width method stay as for an unidentified terminal. OpenTUI never sends the query later, so a terminal behind a stale TMUX gets Kitty graphics only when its XTVERSION reply names kitty or Ghostty. Others, such as WezTerm, keep Sixel but not Kitty graphics.

When COLORTERM does not enable rgb, OpenTUI asks the terminal. The startup queries include XTGETTCAP RGB and Tc, and a positive reply to either enables rgb. An XTVERSION reply from kitty, Ghostty, WezTerm, foot, XTerm, iTerm2, or tmux also enables rgb; tmux converts 24-bit colors for its client itself. These replies come through ssh from the terminal, so they work without COLORTERM.

Inside GNU Screen (STY, or a TERM that starts with screen without TMUX, also when ssh forwards it from inside Screen) OpenTUI sends neither query, and neither a reply nor COLORTERM enables rgb. Screen drops 24-bit colors unless its truecolor setting is on, and a COLORTERM inherited from the terminal outside Screen cannot tell. Screen gets 256-color output, also with a plain screen TERM. If you turn on truecolor in Screen, set OPENTUI_FORCE_TRUECOLOR=1. A tmux XTVERSION reply ends this rule, because Screen does not pass that query on.

If nothing enables rgb, a 256color TERM gives 256-color output. Alacritty and mosh, for example, answer none of these queries. To keep truecolor there, export COLORTERM=truecolor on the server, forward it with SendEnv COLORTERM on the client and AcceptEnv COLORTERM on the server, or pass it in environment. OPENTUI_FORCE_TRUECOLOR=1 (or true) enables rgb in every mode and inside Screen, forwarded or passed in the same ways. OpenTUI ignores other values.

forwardEnvKeys selects process environment names that OpenTUI sends to native detection. Explicit remote mode defaults to an empty list. Other modes default to the documented terminal, SSH, tmux, Zellij, width, graphics, notification, hyperlink, WSL, and Windows Terminal keys.

For a remote terminal, forward only values that describe the remote endpoint:

const renderer = await createCliRenderer({
  stdin: remoteInput,
  stdout: remoteOutput,
  remote: true,
  forwardEnvKeys: ["TERM", "COLORTERM", "OPENTUI_GRAPHICS"],
  width: 80,
  height: 24,
})

forwardEnvKeys reads the process environment, so it describes the remote endpoint only when the process runs inside that endpoint’s session. A server with many clients passes each client’s values in environment instead, for example environment: { TERM: pty.term, COLORTERM: "truecolor" }. These values replace forwarded values with the same name. When auto-detection finds an SSH login, OpenTUI applies only their color depth keys, the width overrides, GNU Screen detection, and the tmux hint, as it does for forwarded values. Set remote: true for the other values to take effect, as @opentui/ssh does.

Custom streams do not receive SIGWINCH. Call renderer.resize(width, height) when the remote transport reports a window change. Read SSH for the full session setup.

Multiplexers#

OpenTUI detects tmux from XTVERSION, TMUX, TERM_PROGRAM=tmux, or a TERM prefix. It detects Zellij from XTVERSION or Zellij environment keys. It detects GNU Screen from STY or a TERM prefix.

Detection changes feature policy:

  • tmux receives unwrapped probes and answers the ones it implements. OpenTUI does not probe the outer terminal through tmux passthrough because tmux does not route those replies to the pane that asked.
  • tmux skips Kitty and Sixel detection and enables focus tracking.
  • GNU Screen disables graphics queries and the 24-bit color queries, gets 256-color output unless OPENTUI_FORCE_TRUECOLOR=1 is set, and selects conservative width behavior.
  • Zellij accepts notification support only from an OSC 99 query or an explicit override.
  • Multiplexer detection can set explicit_cursor_positioning and unicode conservatively.

The terminal fields can describe the multiplexer rather than the outer emulator. Use multiplexer for routing policy.

Overrides#

Terminal detection reads these protocol controls:

Variable Native behavior
OPENTUI_GRAPHICS Exact lowercase false or 0 disables Kitty and Sixel queries. Exact lowercase true or 1 keeps detection enabled.
OPENTUI_IMAGE_PROTOCOL Selects auto, kitty, sixel, or blocks without case sensitivity
OPENTUI_FORCE_EXPLICIT_WIDTH true or 1 forces support. false or 0 disables support and the query.
OPENTUI_FORCE_TRUECOLOR 1 or true enables 24-bit color in every mode, also inside GNU Screen. Other values are ignored.
OPENTUI_FORCE_WCWIDTH Presence selects wcwidth
OPENTUI_FORCE_UNICODE Presence selects Unicode width mode
OPENTUI_FORCE_NOZWJ Presence selects a native no-ZWJ width mode
OPENTUI_NOTIFICATION_PROTOCOL Selects osc9, osc777, osc99, or a disabled value
OPENTUI_NOTIFICATIONS 0, false, or off disables notifications
FORCE_HYPERLINK 0, false, or off disables OSC 8 hyperlinks. Any other value, including an empty value, enables them.

Read Environment variables for the complete value and timing rules.

The native no-ZWJ mode is not represented in the public WidthMethod union or the terminal-capability decoder enum. The OPENTUI_FORCE_NOZWJ snapshot path is therefore unclear. Do not depend on capabilities.unicode under that override until the public type and decoder agree with native state.

Response trust#

Capability replies arrive on the renderer’s input stream. A byte source that can inject terminal response sequences can influence the snapshot and enable later protocol output.

Treat custom and remote streams as a trust boundary. Forward replies only from the terminal endpoint. Do not combine untrusted application data with the control-response channel. OpenTUI validates recognized shapes and bounds parsed numbers, but that validation does not authenticate the sender.

Test fixtures#

Use @opentui/core/testing instead of sending private escape replies in most tests:

import { createTerminalCapabilities, setRendererCapabilities } from "@opentui/core/testing"

const capabilities = createTerminalCapabilities({
  rgb: true,
  hyperlinks: true,
  osc52_support: "supported",
  terminal: { name: "fixture", version: "1.0" },
})

setRendererCapabilities(renderer, capabilities)

createTerminalCapabilities() defaults booleans to false, unicode to "unicode", osc52_support to "unknown", multiplexer to "none", image_protocol to "auto", and terminal strings to empty. Overrides merge the nested terminal object.

setRendererCapabilities() changes a test renderer’s stored snapshot. It does not emulate native protocol setup or terminal output. Read Testing for observable rendering tests.

Next#

  • Renderer owns renderer creation and custom streams.
  • Image selects an image protocol for normal display.
  • Clipboard defines OSC 52 fallback and operation results.
  • Notifications defines notification policy.
  • SSH configures remote sessions.
  • Troubleshooting routes terminal-detection failures.
Changes0.9.1, 0.9.0, 0.8.3
0.9.1
native: In an auto-detected remote session, TMUX or a TERM that starts with tmux holds back the startup Kitty graphics query, which tmux showed as the pane title. (#2143)
0.9.0
core: Theme and palette queries end at the DA1 reply instead of on timers. waitForThemeMode() resolves with null when no OSC 11 reply arrives, and getPalette() reports the default colors of a terminal that does not answer OSC 4. (#1969)
native: Inside GNU screen, OpenTUI ignores COLORTERM and WT_SESSION and writes 256-color SGR, because screen drops 24-bit colors by default. Set OPENTUI_FORCE_TRUECOLOR=1 when screen’s truecolor setting is on. (#1967, #1982)
native: WT_SESSION enables OSC 8 hyperlinks on every host OS when TERM is unset, empty, or starts with xterm and no multiplexer is present. So a Windows Terminal client gets clickable links from a Linux or macOS host when a remote session forwards WT_SESSION. (#1976)
native: In kitty, the OSC 66 startup probe no longer overwrites the top two history rows of a split-footer app. The main screen gets no drawing probe, and OpenTUI recognizes kitty 0.40+ and foot 1.21+ from their XTVERSION reply. (#2056)
native: Inside GNU screen, startup no longer prints +q4d73. A remote session detects screen from TERM, so OSC 52 copies are wrapped and emoji widths match. (#1945, #1961)
native: When a reply selects wcwidth, OpenTUI turns off mode 2027, and teardown restores the mode as it was before startup. Reported by @mmick66. (#1986)
native: On a Windows host, remote sessions ask the client terminal about 24-bit color and skip the ConPTY close teardown. (#1957, #1959)
native: An OSC 8 link target must be non-empty UTF-8 of at most 512 bytes with no control characters. Before, an ESC or BEL in a link target ended the sequence, and the terminal ran the rest as commands. Reported by @carsteneu, who also wrote the first fix. (#1996)
0.8.3
core: When COLORTERM does not enable 24-bit color, the renderer asks the terminal with XTGETTCAP RGB and Tc. A positive reply, or an XTVERSION reply from Ghostty, WezTerm, foot, XTerm, iTerm2, or tmux, enables rgb, also over SSH. (#1941)
core: OpenTUI chooses the width method from OPENTUI_FORCE_*, the multiplexer, the DECRPM 2027 reply, XTVERSION, and then the environment. Alacritty, xterm, GNOME Terminal, VS Code, and Zellij now get wcwidth, and tmux 3.6 and later gets unicode. (#1920)