Terminal Renderers

Updated August 16, 2026

crystl draws terminals with Prism, its Metal-based surface. Settings no longer offers a picker — Settings → general → terminal → TERMINAL RENDERING just shows Prism. xterm still exists as an advanced fallback: Prism switches to it automatically if it fails to initialize, and it’s reachable manually through the CLI or a defaults write override (see xterm below).

Prism

Prism is the default and recommended surface. It draws with Metal on top of crystl’s cavrn terminal engine, so it can keep many streaming shards light while preserving structured information about what ran.

Prism is also where the richer terminal features live:

  • structured blocks and width-immutable scrollback
  • clickable collapsed tool-call rows
  • indexed shell commands and complete retained output through crystl commands
  • command-to-command navigation in scrollback

xterm

xterm is an advanced fallback, not a Settings toggle. Prism switches to it automatically at runtime if it fails to initialize, so most people never need to touch it directly.

If you’re troubleshooting a renderer-specific problem, it’s reachable manually:

crystl settings set terminal_surface xterm

or, outside a shard, defaults write com.crystl.app terminalSurface xterm.

Your terminal, shell, agents, chat dock, and transcript history still work on xterm. Prism-only structure and interactions are unavailable until you switch back.

When the change applies

A change to terminal_surface applies to terminals opened after you change it. Already-open shards keep the surface they started with, so you can finish their work without a renderer swap underneath them.

You can inspect the current choice for free from a shard:

crystl settings get terminal_surface        # what you asked for
crystl settings get terminal_surface_active # what shards actually got

terminal_surface_active is read-only, and it’s the one to check when a renderer choice doesn’t seem to have landed. It reads unknown until the first shard is built, since nothing has picked a surface yet. The bridge reports the same pair on GET /health as terminalSurface.requested and terminalSurface.active.

Guild members can set it from the CLI too, with crystl settings set terminal_surface prism (or xterm, see xterm above). See the CLI reference for the full settings allowlist.