documentation
Everything you need to know about crystl.
Concepts
Gems & Shards
Organize projects as gems and manage terminal sessions as shards.
Approval Modes
Control how crystl handles Claude Code permission requests.
Isolated Sessions
Multitask with parallel Claude 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.
Features
Workspace
Split View
View multiple shards side by side to multitask within a single gem.
API Key Storage
Store API keys securely in macOS Keychain and auto-inject them into shell sessions.
MCP Servers
Manage a global catalog of MCP servers and sync them to projects automatically.
Terminal GPU Rendering (Cavrn)
Cavrn, crystl's default Metal GPU terminal renderer, with xterm.js as a fallback.
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.
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.
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.
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, 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.
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.
Starting a crystl Quest
Summon a party of agents and begin multi-agent collaboration.
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 model selection.
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 — its own agent, model, and persona — without starting a Quest. Launch from the summon-a-hero button next to the shard +, 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.