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). It’s read-only and free on every tier, and it never prints API-key values, only whether each key is set. So you can ask your agent “what’s my terminal renderer?” or “is remote access on?” and it can answer from the live config.

General

App-wide behavior, your data, and your membership.

• Default gems directory — where new gems are created (defaults to ~/Projects).
• Git remote base URL — prefix used to auto-fill the remote field when you create a gem (e.g. [email protected]:you/).
• Crystal Rail — show or hide the frosted rail, and pick its screen edge (left, right, or top).
• Sidebar mode — gem sidebar vs. tab-bar layout.
• Workbench — the slide-out task list per gem, with an option to auto-open it when an agent adds items.
• Reopen on startup and Resume agents — whether gems and shards come back on launch, and whether their agents respawn immediately, lazily on first visit, or not at all.
• Terminal surface — the rendering engine (cavrn, crystl’s Metal GPU renderer), plus the terminal 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.
• 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.
• Window opacity — the slider that shapes the glass finish, applied to every panel and window. Disabled when the background finish is solid.
• Tell agents about the crystl CLI — inject the CLI discovery primer into each gem’s agent docs so agents can drive crystl.
• Storage — timeline history stored per gem and shard, with controls for how much of it is shown.
• License — Guild membership status and activation.

Agents

Per-agent behavior, defaults, and the keys agents run on.

• Defaults — the default spawn agent, default approval mode, and the master switches for notifications and the approval / denial / ask-user panels.
• Schedules — persisted scheduled agent launches (a fresh agent in a gem at a set time, optionally repeating).
• Claude and Codex — enable each agent and set its options (effort level, default mode). Claude is enabled by default; Codex is opt-in.
• MCP Servers — a global catalog of MCP servers that sync into each gem’s .mcp.json.
• API Keys — provider keys (Anthropic, OpenAI, Google AI, OpenRouter) stored in the macOS Keychain and injected into every new terminal session. Values are never exposed outside the Keychain.
• System Prompts — a read-only view of the agent system prompts for reference.

Workspace

Configuration for the collaborative features.

• Quest — 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.
• File Library — reusable starter files, templates, skills, and rules for seeding new gems.

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 settings from an agent

crystl settings            # grouped, human-readable
crystl settings --json     # the raw snapshot object

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.