Settings Overview

Settings opens from the app menu ( crystl → Settings, Cmd+,) into a Warp-style sidebar. Pages are grouped into General, Agents, Workspace, and Connect. This page is a map of where everything is.

An agent working inside crystl can read your current values, not just the list of what exists, with crystl settings (add --json for the raw object). The snapshot and settings get are free on every tier, and they never print API-key values, only whether each key is set. Guild members can use settings set to live-apply a small, explicit allowlist of controls. So you can ask your agent “what’s my terminal renderer?” or “turn tool activity notifications on,” and it can act from the live config.

General

App-wide behavior, your data, and your membership. The general page itself is split into four tabs across the top: appearance, terminal, gems, and startup. crystl remembers the tab you were last on, so reopening Settings drops you back where you left off. storage and license are beside general as their own sidebar entries.

appearance

• Crystal rail: show or hide the frosted rail, and pick its screen edge (left, right, or top).
• Background: pick one of 7 dark shades (graphite, the default, plus black, navy, forest, oxblood, plum, and espresso), or click the last dot, custom…, to pick any colour on the macOS colour wheel. Add a glass or solid finish. Every window and panel follows the choice live. See Appearance below.
• Window opacity: the slider that shapes the glass finish, applied to every panel and window. It is in the title bar, centered, not on this page. Dragging it on the solid finish switches you to glass and applies the new opacity.
• Terminal font: the typeface your terminals render in, picked from the monospaced fonts installed on your Mac.
• Terminal font size: 10 to 24 pt. Cmd + and Cmd - change the same setting.
• Terminal text: the colour of plain terminal text. Programs that pick their own colours keep them. reset puts the default back.

terminal

• Option as meta key and save session history: how the terminal treats ⌥, and whether shard history is written to disk.
• Allow terminal programs to set the clipboard (OSC 52): off by default. A per-gem permission is offered when a program is blocked.
• Open markdown files with: crystl’s own viewer inside the current gem, or your system file association.
• Terminal rendering: shows the active terminal surface (Prism), structured blocks, and the scrollback cap (500 / 1,000 / 2,000 / 5,000 / 10,000 rows, default 2,000; lower = less memory, applies to terminals opened after the change). Agent turns stay in history search (Cmd+Shift+F) whatever the cap.
• CRYSTL CLI: the manual controls for the crystl command on your PATH. crystl installs it on launch when it can, so this section is the override: a status line (yellow when the command won’t run from an outside terminal), one button that reads install, uninstall, repair, or how to fix depending on what’s at /usr/local/bin/crystl, and a cli docs → link. When the command isn’t available, a banner sits above the general page header on every one of its tabs.

gems

• Default gems directory: where new gems are created.
• Git remote base URL: prefix used to auto-fill the remote field when Initialize git repository is on while creating a gem (e.g. git@github.com:you/). That checkbox starts on for an ordinary new folder and off when the folder would be inside an existing repository.

startup

• Reopen gems & shards on startup and Resume agents: whether your work comes back on launch, and whether the agents respawn immediately, lazily on first visit, or not at all.
• Workbench: the slide-out task list, with an option to auto-open it when an agent adds items.

storage and license

• storage: everything crystl keeps on disk, what each store costs, and the controls to clear it: timeline history per gem, sequence run records, saved questlines and quest archives, and the two caches. See storage.
• license: Guild membership status and activation.

Which terminal renderer?

crystl renders terminals with Prism, its native Metal renderer, backed by the cavrn terminal engine and built for a window full of streaming agents. There’s no picker in Settings for this anymore — Prism is what you get. Structured blocks, indexed shell-command output, and click-to-expand tool calls need Prism.

xterm is still available as an advanced fallback. Prism switches to it automatically at runtime if it fails to initialize, and you can request it manually with crystl settings set terminal_surface xterm or a defaults write override. Terminals already open keep the renderer they started with. See terminal renderers for the exact tradeoffs.

Agents

Per-agent behavior, defaults, and the keys agents run on. Five sidebar entries: agents, schedules, MCP servers, providers & keys, and context.

The agents page holds agent configuration proper, on six tabs of its own, in the same underline strip the general page uses. Panels that offer to take you to an agent setting land on the right tab already selected, and crystl remembers which tab you were last on.

• defaults: LAUNCH COMMANDS (DEFAULT), three raw commands (one per model size) that run whenever nothing names an agent. Also AUTO-APPROVAL (DEFAULT), the fallback auto-approval mode for gems with no mode of their own, the notification switches (a master switch, plus needs you, agent finished, tool activity, messages to you, and other terminals) and their sounds, and tell agents about the crystl CLI (which injects the CLI discovery primer, about 11 KB and roughly 130 lines, into each gem’s agent docs so agents can drive crystl). It also writes a short section into ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md that says which tier you are on and where your identity file is. Switching it off removes that section from those two global files and leaves the rest of them as they are. It stops new primers but leaves blocks already written in your projects in place; crystl uninstall --primers removes those. While it is off, an agent in a gem without a primer does not know it is inside crystl or which commands exist, so it stops using crystl card, crystl copy, the workbench and the rest unless you tell it, and no agent is told your tier or where your identity file is. See the CLI docs. prose guard stops an agent’s crystl command when its inline text carries a backtick or $( ) the shell would run, and tells the agent to send it from a file or a pipe. It is on by default. See long text from a file or a pipe.
• agents: one row per callable agent, with small, standard, and large as properties of that agent. Bare seeded commands and their recognized aliases resolve to a native row. User-owned paths, arguments, leading environment assignments, wrappers, and full custom commands get distinct rows, and an open-model connection bound to a CLI appears as command@endpoint. Every size field accepts a complete start command or a bare model id. For a custom command, declare how a bare model id is passed (-m {model}, --model {model}, or MODEL={model}) with crystl agent profile set --model-via; crystl never guesses an unknown CLI’s model convention. Below them, ACCOUNTS lists each agent’s accounts, with buttons to change a label, remove an account, or add one. A multiple accounts? link beside the agent commands, here and on defaults, explains what an account is.
• claude, codex, and antigravity: enable each agent and set its options (effort level, default mode). All three are enabled by default. The claude tab also holds USAGE, the switch that lets crystl read your plan’s limits from Claude Code’s statusline. See usage.
• system prompts: a read-only view of the agent system prompts for reference.

The other four keep their own sidebar entries:

• schedules: persisted schedules (an agent prompt, or a shell command with no agent, run in a gem at a set time, optionally repeating, optionally rotating through a list).
• MCP servers: a global catalog of MCP servers that sync into each gem’s .mcp.json.
• providers & keys: hosted provider keys (Anthropic, OpenAI, Google AI, OpenRouter) stored in the macOS Keychain and injected into every new terminal session, plus your open-model connections below them. Values are never exposed outside the Keychain. This page was called api keys before.
• context: reusable starter kits, single-file templates, skills, and rules for seeding new gems, plus a read-only view of your installed plugins. Five tabs: starter kits, files, skills, plugins, rules. This page was called library before. See agent files.

Appearance

There’s no theme picker or light mode yet. crystl is built by one person, its founder and only developer, so a full theming system is a real chunk of time that has so far gone to the orchestration features instead. What exists today is a small set of appearance controls, and they are in three different places, so they’re gathered here.

Background shade and finish: settings, general > appearance. Seven dark presets and a custom… dot that opens the macOS colour wheel, so any colour works. Hover a swatch for its name:

Finish is glass (translucent, shaped by the opacity slider) or solid (fully opaque). The choice re-tints every window and panel live, no restart.

Window opacity: the small slider centered in the title bar, not on the Settings page. It only does anything on the glass finish; solid ignores it.

Terminal font: settings, general > appearance, under TERMINAL FONT, listing the monospaced fonts installed on your Mac. Nerd Fonts show up here too, so agent TUIs that need powerline or icon glyphs render as designed. To add one, install the .ttf or .otf through macOS Font Book, then reopen Settings for it to appear.

Terminal font size: under the font, TERMINAL FONT SIZE lists 10 to 24 pt. Cmd + / Cmd - / Cmd 0 change the same setting, see keyboard shortcuts.

Terminal text colour: TERMINAL TEXT is a colour well for plain terminal text, the text that sets no colour of its own. Programs that colour their own output keep their colours. A light background with dark text works: pick the background on the colour wheel, then a dark text colour here. reset puts the default back.

Per-gem color and icon: each gem carries its own accent color and icon, set in Gem Settings rather than globally. That color is what tints its rail tile, tab, and its panels. See Gems & shards.

Shard colors are not configurable: each crystal name has a fixed signature hue so a shard reads the same everywhere it appears.

Workspace

Configuration for the collaborative features.

• crystl quest covers your character (name, role, personality, stats), the parties of role-played agents you launch together, and quest scrollback: a separate scrollback default for quest party members (1,000 rows, so launching a full party stays light on memory). Solo hero shards follow the regular scrollback setting, and an explicit --scrollback on shard create overrides both.
• worktrees: integration targets for isolated (git-worktree-backed) shards.
• heroes: customize the named specialist personas: built-in defaults, your global custom heroes, and a gem’s committable local heroes.
• facet inserts: saved snippets bound to the one-click bar buttons in the terminal.
• formations: named collections of gems for quick context switching.
• key scan: the scan that looks for API keys committed into a project, the patterns it matches, and the per-pattern switches. See key scan.

Gem and shard settings

App Settings contains global defaults. Project-specific controls are behind the ⋮ menus on gem tabs and shard pills:

• Gem menu: history, the full three-tab Gem Settings panel, optimizer, recently closed shard recovery, and the per-gem approval shortcut.
• Gem Settings → general: auto-approval mode, the Guild-only Default Agent for the gem, conditional Git initialization, name, color, and icon.
• Gem Settings → agents: root agent files, Claude plugin and skill inclusion, MCP servers, and links to global Codex configuration.
• Gem Settings → worktrees: integration target, sealed-quest branching, and reset-to-global controls.
• Shard menu: rename, details, turns, isolated-branch merge/rebase actions when applicable, and close. There is no separate Shard Settings panel, and most runtime defaults are inherited from the gem.

See Gems & Shards → The gem menu for the complete, condition-aware inventory of both menus and every Gem Settings tab.

Connect

Reaching crystl and its agents from elsewhere.

• mobile: pairing for the companion app, plus allow phones on your network (free, LAN) and the relay for connecting from anywhere (Guild).
• remote: SSH options: auto-tunnel for agent approvals over SSH, diagnostics, and a manual bridge-address override.

Reading and changing settings from an agent

crystl settings                              # grouped, human-readable snapshot
crystl settings --json                       # raw snapshot object
crystl settings get terminal_surface         # one allowed value, free
crystl settings set terminal_surface prism   # live-apply a value, Guild

The snapshot groups values under general, agents, notifications, remote, and api_keys_present, plus your tier (guild or free). It reflects effective values, including defaults for anything you haven’t changed.

settings set is intentionally narrow. It accepts the same allowlist as settings get, validates the new value, and routes through the app’s live control path. It does not expose arbitrary preferences. See the CLI reference for every allowed key and value.

One key reads but never writes: terminal_surface_active. terminal_surface is the renderer you asked for; terminal_surface_active is the one shards were actually built with, so comparing them tells you whether a renderer preference really took effect or quietly fell back. It reads unknown until the first shard is built, since nothing has picked a renderer yet.