# Terminal Renderers

> Prism is crystl's default Metal terminal surface. xterm is an advanced fallback, no longer selectable in Settings.

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](#xterm) below).

## Prism

Prism is the default and recommended surface. It draws with Metal on top of crystl's [cavrn terminal engine](/docs/metal-rendering/), 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](/docs/tool-calls/)
- indexed shell commands and complete retained output through [`crystl commands`](/docs/cli/#commands-and-screen-command)
- 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:

```bash
crystl settings set terminal_surface xterm
```

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

Your terminal, shell, agents, [chat dock](/docs/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:

```bash
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](#xterm) above). See the [CLI reference](/docs/cli/#settings) for the full settings allowlist.

---
Source: https://crystl.dev/docs/terminal-renderers/