Terminal GPU Rendering (Cavrn)

Updated August 9, 2026

cavrn is crystl’s native terminal engine, built for orchestration: it keeps a fleet of agent sessions light and treats what agents print as structured data, not just pixels. It exists because crystl’s workload is unusual for a terminal: a single window can hold many shards streaming agent output at once, so cavrn is designed around exactly that: hidden shards cost almost nothing to render, the visible one repaints only the rows that change, and the things agents print (tables, diffs, TUIs) are first-class content rather than a stream of characters. Its default Prism surface draws on the GPU with Metal and is noticeably lighter under heavy agent output than a general-purpose terminal widget.

For a deep, under-the-hood tour of the engine (the byte-to-pixel pipeline, how it stays fair across many concurrent shards, and why the GPU sits near-idle by design), see terminal engine internals.

How it works

cavrn sends terminal cell and glyph-atlas data through a Metal GPU pipeline instead of relying on CPU drawing for every frame. The terminal still parses PTY output and maintains its scrollback buffer on the CPU, so GPU rendering is not a magic speed switch, but it takes the paint cost off the CPU when the screen is changing quickly. That matters most when several agents are streaming at once.

Width-immutable scrollback

cavrn treats scrollback as history: resizing the window does not rewrap the lines already written. Old lines keep the wrap they were written with, and only the live rows at the bottom reflow to the new width.

This is deliberate, not a bug. Terminals that rewrap history on every resize have to rewrite thousands of old lines each drag, which is where a whole class of resize glitches comes from: scattered table fragments, ghost rows, mangled diffs. Keeping history immutable keeps what an agent drew exactly as it drew it, and makes resizes fast and glitch-free. If you want prose to rewrap in a plain shell, the reflow policy is a hidden lever rather than a Settings control: defaults write com.crystl.app prismScrollbackLayout preserveHardLines (or the CRYSTL_PRISM_SCROLLBACK environment variable). See terminal engine internals for what each policy does.

Scrollback

The scrollback setting lives in Settings → general → terminal → TERMINAL RENDERING: how many rows of output each terminal keeps in its buffer. Pick 500, 1,000, 2,000 (the default), 5,000, or 10,000 rows. A lower cap means less memory per shard, which adds up when you have many shards open; a higher cap keeps more of a day-long session reachable by scrolling. Values are clamped to 200–10,000.

The setting applies to terminals opened after the change; existing shards keep the scrollback they started with. Scrollback only limits what you can scroll to: agent messages and commands stay in history search (Cmd+Shift+F) regardless.

Two related levers:

  • Per-shard override: crystl shard create --scrollback <N> caps one shard at creation, handy for keeping fanned-out workers light. Quest party members get their own lower default (1,000 rows, set in Settings → quest); solo hero shards follow the regular setting, and an explicit --scrollback wins over both.
  • Freeing memory on demand: crystl scrollback clear (or Cmd+K) clears a shard’s screen and retained scrollback and actually frees the buffer’s memory.

Fonts

A terminal font picker in Settings lists your installed monospaced fonts, including Nerd Fonts installed through Font Book, so agent TUIs that lean on powerline or icon glyphs render the way they were designed to.

Table copy

cavrn recognizes tables in terminal output, both box-drawing tables that TUIs draw and markdown tables agents print. Hovering a detected table shows a ⋯ button just to its right; click it to copy the table as raw text, CSV, or JSON, so tabular agent output goes straight into a spreadsheet or script instead of being drag-selected across wrapped lines.

Choosing a terminal surface

The terminal surface picker sits in Settings → general → terminal → TERMINAL RENDERING. Leave it on Prism, the default and recommended surface. Pick xterm only when you need the fallback. Expect to lose Prism-only features while you’re there: structured blocks, indexed shell-command output, click-to-expand tool calls, and width-immutable history. Terminals already open keep the renderer they started with, so the change lands on the next shard you create. See terminal renderers for the short comparison.

Availability

cavrn and all the scrollback controls are available on both Free and Guild tiers.