Terminal graphics

Your terminal decides the picture

TDE draws into a grid of character cells. A cell carries one glyph and two colours — that is all the terminal protocol gives it. Real pixels only appear when the host terminal implements a graphics extension, and TDE has no way to add one.

So the fidelity of a rendered web page, a PDF page, an image preview or the design system's rounded corners is not a TDE setting. It is a property of the terminal you launched TDE in. Pick a good one and everything gets sharper for free.

Recommended: kitty or Ghostty. Both implement the tier that works everywhere in the desktop, and both draw the Unicode block mosaics TDE falls back to without needing a font that has them.

The four tiers

TDE degrades in four steps, best first.

1. Kitty graphics with Unicode placeholders

The image is transmitted once and then placed through the cell grid: TDE emits placeholder cells that encode an image id and a raster row and column, and the terminal fills them in. Because the pixels live in the grid, they clip to the window rect and respect z-order automatically.

That is what makes this tier qualitatively different, not just prettier. It works with the window tiled, floating, partly covered by another window, or scrolled — no special case. It is also the tier the design system's pixel decoration (rounded corners, inset chips, hairlines, shadows) is emitted for.

Supported by kitty and Ghostty. WezTerm is deliberately excluded: its placeholder support is still incomplete.

2. Legacy kitty graphics, or sixel

Real pixels, drawn as a floating overlay on top of the screen.

Neither protocol can clip to a region or honour z-order, so an overlay painted at the wrong moment would spill over the desktop. TDE therefore only paints this tier when the window is focused and maximized, and never in the overview or with a wizard open. Everything else falls back to blocks underneath.

Sixel quantizes to a 256-colour palette (TDE reduces each channel to 3 bits, then keeps only the registers actually used) and ignores alpha — every pixel is treated as opaque.

3. iTerm2 inline images

The OSC 1337 File= protocol, where the payload is a complete PNG rather than raw pixels. Detected from the environment only, since it has no query. Supported by iTerm2, WezTerm, VS Code's terminal, rio and Konsole 22.04+.

4. Block cells

The universal fallback, and the only tier that never fails. TDE downsamples the raster and picks a Unicode block glyph per cell with a foreground/background colour split:

Octant glyphs live in a block many fonts do not carry, so TDE only defaults to them on terminals known to draw those glyphs procedurally — kitty, Ghostty, foot and rio, detected from TERM, TERM_PROGRAM or KITTY_WINDOW_ID. Everywhere else the default is sextants.

Override it explicitly when you know better:

TDE_BLOCKS=octant tde
TDE_BLOCKS=sextant tde

Accepted values are half, quadrant/quad, sextant/sext/6 and octant/oct/8.

How TDE works out what you have

Detection runs once at startup, in three passes.

1. Environment sniffing. Free and never blocks:

2. Cell pixel size. TDE asks the kernel for the window's pixel dimensions (TIOCGWINSZ) and divides by the cell grid. Knowing the real pixel box lets it downscale an image to exactly the pixels the target cells cover instead of shipping it at native resolution and letting the terminal rescale.

3. A live escape-sequence handshake, but only when the first two passes left a gap — no graphics protocol detected, or a cell size of zero. This is what catches VTE-based terminals (GNOME Terminal, elementary Terminal) that export a plain xterm-256color but do support sixel, and hosts whose TIOCGWINSZ reports zero pixels.

The probe writes four queries in one burst and reads one reply:

CSI ? 2026 $ p     synchronized output (DEC mode 2026)
APC _G … a=q …     kitty graphics — side-effect-free query
CSI 14 t           XTWINOPS: text-area size in pixels
CSI c              DA1 — attribute 4 means sixel

DA1 goes last on purpose: every terminal answers it, so its reply reliably ends the read. The whole thing is bounded at 300 ms, runs in raw mode before the event reader takes stdin, and is non-blocking — a terminal that answers only some of the queries can never wedge startup. Parsing is defensive: partial or garbage input sets nothing rather than guessing.

Over SSH, your local terminal is what counts

This is the single most common source of confusion. When you ssh into a machine and run TDE there, the escape sequences travel end to end: the process on the server writes them, and the terminal emulator on your laptop draws them.

• The remote machine's TERM, its fonts and its GPU are irrelevant.
• Run kitty or Ghostty locally and a remote TDE gets full-quality images.
• Run TDE from a terminal with no graphics support and no amount of remote configuration will produce pixels.
• TERM is the signal TDE trusts most for block-mode detection precisely because it propagates over SSH, where TERM_PROGRAM does not.

Multiplexers are the exception worth calling out: tmux and screen sit between the two ends and may not forward graphics sequences or answer the pixel-size query.

What actually uses this

If your terminal advertises no graphics protocol at all, TDE skips the encoding work entirely rather than burning cycles producing an escape sequence nobody will draw.

Related

• Browser — render modes and how they interact with these tiers.
• Themes — Tonal Slate, Editorial Paper and the full palette catalog.
• Design system — the hybrid cells-plus-decoration model.