Settings

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 what lives where.

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 notification cards off,” 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 sit 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) with 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 lives in the title bar, centered, not on this page. Disabled when the background finish is solid.
• Terminal font: the typeface your terminals render in, picked from the monospaced fonts installed on your Mac.

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: the terminal surface picker, 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 you explicitly turn on Initialize git repository while creating a gem (e.g. [email protected]:you/). Git initialization is off by default.

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: timeline history stored per gem and shard, with controls for how much of it is shown, the timeline database’s size on disk, and a compact button that checkpoints and vacuums it to reclaim space a clear left behind.
• License: Guild membership status and activation.

Which terminal renderer?

Leave the terminal surface on Prism, the default. Prism is crystl’s native Metal renderer, backed by the cavrn terminal engine and built for a window full of streaming agents. xterm is the supported fallback for the rare case something forces you away from Prism. Structured blocks, indexed shell-command output, and click-to-expand tool calls need Prism. Either way, 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. Four sidebar entries: agents, schedules, MCP servers, and providers & keys.

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 the default approval mode, the master switches for notifications and the approval / denial / ask-user panels, the per-notification sounds, and tell agents about the crystl CLI (which injects the CLI discovery primer into each gem’s agent docs so agents can drive crystl).
• 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. Custom command rows and exact full-command rows also expose MODEL VIA, where you declare -m {model}, --model {model}, or MODEL={model} for bare model ids. crystl never guesses an unknown CLI’s model convention.
• claude, codex, and antigravity: enable each agent and set its options (effort level, default mode). Claude is enabled by default; the others are opt-in.
• system prompts: a read-only view of the agent system prompts for reference.

The other three keep their own sidebar entries:

• Schedules: persisted scheduled agent launches (a fresh agent in a gem at a set time, optionally repeating).
• 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.

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 live in three different places, so they’re gathered here.

Background shade and finish: Settings → general → appearance. Seven dark presets, hover a swatch for its name:

Preset
graphite	the default, neutral near-black
black	true black
navy · forest · oxblood · plum · espresso	tinted near-blacks, blue / green / red / purple / brown

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 → TERMINAL FONT, listing the monospaced fonts installed on your Mac. Nerd Fonts show up here too, so agent TUIs that lean on 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. Font size isn’t in Settings, it’s Cmd + / Cmd - / Cmd 0, see keyboard shortcuts.

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.

• 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 wins over 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.
• Library: reusable starter kits, single-file templates, skills, and rules for seeding new gems, on four tabs: starter kits, files, skills, rules.

Gem and shard settings

App Settings contains global defaults. Project-specific controls live 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: approval preset, Guild spawn-agent override, 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.