documentation
Everything you need to know about crystl.
Basics
Getting Started
Install crystl and create your first gem.
Your agent can drive crystl
Your agent can read crystl's own docs, see what every shard is doing, and open gems and spawn workers for you. The fastest way to learn crystl is to ask the agent already sitting in it.
Updating crystl
How crystl updates itself, where the version and the update badge live, how to see what changed, and what to do when a release breaks something.
Concepts
Gems & Shards
Organize projects as gems and manage terminal sessions as shards.
Approval Modes
Auto-approval is off, in gem, or all. What each one lets an agent do, and why the gem is the ceiling.
Isolated Sessions
Multitask with parallel coding agents using git worktree-backed shards, locally or on remote servers.
Resurrecting Shards
Undo-close for recently closed shards. Bring back a shard you closed by accident, with its name, color, isolation, and agent session restored.
Model Sizes
Heroes ask for a model size (small, standard, or large) instead of a model id, and you teach crystl what each size launches. Two places decide it: the default launch commands, and each agent's own three. Set them in Settings or let your agent fill them in with crystl agent profile set.
NORTH-STAR.md
A file at the root of a project that says what is worth building there: what it is for, who it serves, and what has already been turned down.
Gem Types
A gem's type says what the project produces. It scopes which optimizer checks run, which starter kits you are offered, and how your agent drafts the direction file.
Features
Workspace
Split View
View multiple shards side by side to multitask within a single gem.
API Key Storage
Store provider API keys securely in macOS Keychain and auto-inject them into shell sessions, from the providers & keys settings page.
Key Scan
crystl checks the files git would commit for API keys, reports a path and a line number, and never prints a value.
MCP Servers
Manage a global catalog of MCP servers and sync them to projects automatically.
Terminal GPU Rendering (Cavrn)
Cavrn, crystl's terminal engine built for multi-agent workflows: it keeps a fleet of shards light and agent output structured, drawn on the GPU with Metal. Plus scrollback presets and width-immutable history.
Agent Activity Panel
One window showing what your agents are doing across every gem, who works for whom, and a classified record of the files they touched.
Crystal Rail
The frosted-glass bar for managing gems, approvals, and navigation.
Remote SSH Sessions
Use crystl approval cards with Claude Code running on remote machines over SSH.
Terminal Engine Internals
A deep look at cavrn, crystl's terminal engine: the byte-to-pixel pipeline, how it stays fair across many concurrent agent shards, its memory and reflow model, and why the GPU sits near-idle by design.
Terminal Renderers
Prism is crystl's default Metal terminal surface. xterm is an advanced fallback, no longer selectable in Settings.
Notifications
Floating glass panels for approvals, questions, denials, and activity notifications.
History Navigator
Browse, jump through, and search your agents' sessions: conversation and tool calls.
Tool Calls
Click a collapsed tool call in the terminal to see its full output, with a copy button.
Context Load Tracking
Monitor per-shard token usage, estimate how many turns remain, and see what every installed plugin and skill is costing you.
View Modes: Terminal, Split, Chat
Show any shard as a terminal, as a conversation beside the terminal, or as a conversation filling the window. One pill in the shard bar, Cmd + Y, and the terminal keeps running underneath.
Workbench
A slide-out task list in every project, backed by a plain WORKBENCH.md the agent reads and writes alongside you.
Settings
Every settings page in crystl: what each toggle controls, and how to read your current config from an agent.
Storage
What crystl keeps on disk, what each store costs you, and what you lose if you clear it.
Agents
Use Claude Code with crystl
Install Claude Code, sign in, launch it in a crystl shard, and see what crystl can do with it: approvals, history, resume, and model sizes.
Use Codex with crystl
Install OpenAI's Codex CLI, sign in, launch it in a crystl shard, and see what crystl can do with it, including the approval modes that map onto its own launch flags.
Use Antigravity CLI with crystl
Install Google's Antigravity CLI (agy), sign in, launch it in a crystl shard, and see what crystl can and cannot do with it, including why its approvals stay in its own terminal.
Use Kimi Code with crystl
Install Moonshot AI's Kimi Code CLI, log in, and run it in a crystl shard. Kimi gets real approval cards; transcript and resume are still unwired.
Hooks
What crystl installs into ~/.claude, why approval cards and turn-end status depend on it, how installs stay surgical, and how to remove it all.
Open Models
Open Models
Run Claude Code, Codex, and other coding agents on open models hosted on your hardware or by a managed service. Set them up once, orchestrate them alongside frontier agents, and cut token costs.
Use z.ai open models with crystl
Create a z.ai GLM Coding Plan account, generate an API key, connect its hosted open models to crystl, and start a Claude Code shard.
Use Ollama open models with crystl
Install Ollama, download a coding model, connect it to crystl, and start a Codex shard on your own hardware.
Use LM Studio open models with crystl
Install LM Studio, download and serve a model, connect it to crystl, and start a Claude Code shard.
Use vLLM open models with crystl
Install vLLM on a GPU server, serve a tool-capable model, connect it to crystl, and start a Codex shard.
Use llama.cpp open models with crystl
Install llama.cpp, download and serve a GGUF coding model, connect it to crystl, and start a Codex shard.
Customization
Formations
Save and restore named collections of gems for quick context switching when multitasking across projects.
Facet Inserts
Save and reuse prompts, commands, and shortcuts across all your gems.
Plugins & Skills
Scope plugins and skills per gem so each project only loads the agent context it actually needs.
Starter Files
Starter kits and single-file templates for CLAUDE.md, AGENTS.md, .mcp.json, and the files each kind of project needs.
Agent Instruction Files
Create, edit, and manage CLAUDE.md, rules, skills, and other agent config files from within crystl.
Automation
CLI & Scriptability API
Control crystl from the command line. Open gems, manage shards, schedule agents, approve permissions, and read terminal output programmatically.
CLI command tiers
Which crystl CLI commands are free on every tier, which need Guild, and what an agent should do instead on a free account.
Orchestration: which way to run more than one agent
A decision guide for running more than one agent: anoint or Ruler for one orchestrator, court for a standing lead, crystl quest for peers, Deus for meta-orchestration across every project.
Fanout: orchestrate parallel agents
Hand one Claude session a list of tasks and it becomes a manager: it maps each task to a project, spawns a worker for each, looks after them, and merges their finished work back in.
URL Scheme
Open projects and SSH sessions in crystl from other apps, scripts, Raycast, or web links using crystl:// URLs.
Vigil: the fan-out stall watch
crystl watches a fan-out for you. When the lead and every worker have gone quiet, it nudges the lead once or twice, and if nothing moves it raises one notification card and stops.
Court: the crown and the hand
A standing hierarchy you talk to through one front door. The crown holds the conversation, the hand orchestrates the work, and officers hold standing remits under it.
Scheduling
Run an agent or a plain shell command at a set time, once or on a cadence, and rotate through a list of tasks so each firing does the next one.
Sequences
Run a fixed pipeline of agent stages from a definition file, started by hand or by a schedule, file change, or polled URL.
Project Optimizer
crystl scores how well a project is set up for a coding agent, names the gaps, and tells you what each one costs.
New Gem Setup
The banner that offers to set up a brand-new gem: what it asks, what it installs first, and why it explains each step before taking it.
Quests
crystl quest
Multi-agent collaboration with parties, roles, and coordinated chat.
Quest Levels
Give a quest a questline, an ordered set of stages the whole party clears together, advancing only once every hero checks in.
Starting a crystl quest
Summon a party of agents and begin multi-agent collaboration.
Quest Master
Plan a quest by stating your goal. The Quest Master authors the levels your party moves through, suggests the heroes, and keeps watch while they work.
Quest Chat Panel
The chat interface for cross-agent messaging, DMs, and coordination.
Quest Coordination
How agents communicate, route messages, and share context.
Quest Heroes
Built-in hero roles with RPG stats, personalities, charters, and a model size that resolves through your own agent setup.
Local Project Heroes
Define heroes as JSON in a project's .crystl/heroes/ folder: guardrails that auto-join every party, version in git, and follow the project into every worktree.
Hero Shards
Summon a single hero as a standalone shard with its own agent, model, and persona, without starting a quest. Launch from the summon-a-hero row in the shard bar creation column or from a split pane, optionally isolated in its own git worktree.
Quest System Prompts
the full system prompt injected into each agent during a quest
Side Quest
Bridge two existing shards, across gems or across hosts, for an ad-hoc two-agent chat.
Mobile App
Account
FAQ
FAQ
Frequently asked questions about crystl: platform, agents, gems and shards, isolated worktrees, quest, scheduling, pricing, security, and more.
Troubleshooting
Fix the common failures: hook errors in every terminal, panels that stop appearing, a bridge that won't start, stale CLI docs, and what crystl doctor reports.
Scenarios
Scenarios: what do you want to do?
Task-first paths through crystl. Pick the thing you're trying to do and follow the steps, instead of reading a feature page and working out which parts apply to you.
Run your coding agent on your own hardware
Point Claude Code or Codex at a model server running on your own machine, so the prompts never leave your network.
Cut model costs with hosted open models
Run Claude Code against a hosted open model without your Anthropic key ever going near it.
Fan out cheap workers while your main agent leads
Hand one session a task list and let it run a team: it spawns a worker per task, attends to them, and merges the finished work back.
Parallel feature work without merge conflicts
Run two or more agents on the same repo at once, each in its own git worktree on its own branch, so their live edits never overwrite each other.
Run a multi-agent quest
Summon a party of agents that coordinate in a shared chat, with roles, optional branch isolation, and staged levels.
Run agents on a schedule
Run an agent prompt or a plain shell command at a time you choose, once or on a cadence, and rotate through a list so each firing does the next task.
Work on a repo on your home server over SSH
Run agents on a remote machine while approval cards, file drops, and worktrees still behave like they're local.
Only get interrupted when an agent needs you
Tune approval modes and notification panels so a screenful of agents stays quiet until one of them actually needs a human.
Supervise your agents from your phone
Pair the iPhone app to your Mac to watch sessions, answer questions, and approve tools while you're away from the keyboard.
Recover context after closing or losing a session
Find what an agent actually did, in the navigator, the timeline, or the CLI, and bring the agent itself back when you closed it by mistake.
Teach crystl your models once
Fill in what small, standard, and large launch for your own agents so heroes, quests, and scheduled runs land on the model you meant.
Review and merge a worker's branch safely
Read what an isolated shard did, then integrate its branch through machinery that never forces and never guesses.