documentation
Everything you need to know about crystl.
Concepts
Gems & Shards
Organize projects as gems and manage terminal sessions as shards.
Approval Modes
Auto-approve 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.
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.
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 view of what your agents are doing across every gem, 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 panels 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
Choose Prism, crystl's default Metal terminal surface, or the xterm fallback in Settings.
Notifications
Floating glass panels for approvals, questions, denials, and activity notifications.
History Navigator
Browse, jump through, and search every Claude session: conversation and tool calls.
Tool Calls
Click a collapsed tool call in the terminal to see its full output, with a copy button.
Chat Dock
Read and drive the focused shard's agent conversation beside the terminal with Cmd + Y.
Context Load Tracking
Monitor per-shard token usage, estimate how many turns remain, and see what every installed plugin and skill is costing you.
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.
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
Reusable project templates for CLAUDE.md, AGENTS.md, .mcp.json, and any other file you want to seed new gems with.
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.
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.
Agent Scheduling
Schedule a fresh agent to launch at a set time (once, daily, or weekdays) with its own gem, prompt, agent, model, and approval mode.
Project Optimizer
Analyze your project's AI readiness and get prioritized recommendations for improving agent instructions.
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
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
Launch a fresh agent at a time you choose, once or on a cadence, with its own gem, prompt, agent, model, and approval mode.
Work on a repo on your home server over SSH
Run agents on a remote machine while approval panels, 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.