faq-index
kitWhich content goes here?
- How is the content best represented?
- How important is the content to the user?
- How much context or explanation does it need to be effective?
- How is it related to other content on the page?
Common questions
How do I open the Agent Activity Panel?
Click the diamond icon at the top of the crystal rail to see every agent across all open gems. To scope it to one project, click a gem's tile once to focus it, then click it again to open the panel for just that gem.
What file types can I create?
CLAUDE.md, CLAUDE.local.md, AGENTS.md, codex.md, GEMINI.md, .cursorrules, .windsurfrules, copilot-instructions.md. Plus Claude Code's extended config: rules, skills, and settings.
What makes Cavrn different from a normal terminal?
A normal terminal gives you scrollback: characters on a grid. Cavrn keeps a structured model of the session: every turn, tool call, and result as typed, timestamped records, tables detected as data. The output becomes something agents and crystl can read and act on, not just display.
Is there a GUI for Claude Code?
Yes, several. Anthropic ships a Claude Code desktop app for Mac and Windows and a web version at claude.ai/code, plus IDE extensions for VS Code and JetBrains. Community projects such as Claudia and claudecodeui wrap the CLI in their own interface. crystl is a native macOS app that keeps every session as a real terminal running the Claude Code CLI, and adds approval cards, parallel sessions, and per-session token tracking around it.
Does Claude Code have a session manager?
Not as a separate surface. Claude Code stores every session as a transcript under <code>~/.claude/projects/</code> and gives you flags to get back into one: <code>claude --continue</code> for the most recent session in the current directory, and <code>claude --resume</code> for a picker or a specific session ID. There is no view of what is running, what is blocked, or what anything cost.
What is the best UI for Claude Code?
It depends on what you need to see. If you run one session at a time, Claude Code's own terminal interface is enough. Once several sessions run at once, you need something that shows which one is working, which is waiting on approval, what each just ran, and what each has cost. crystl is a macOS app built around exactly those four questions, and every session inside it is a real Claude Code session.
What's the best terminal for Claude Code?
crystl is a macOS terminal built specifically for Claude Code. Every shard runs the Claude Code CLI, and crystl adds what a plain terminal can't: run multiple sessions in parallel, surface hook approvals as on-screen panels, manage CLAUDE.md files per project, and track token and context usage. It also works as a regular terminal for any command-line work.
Where does the binary live?
Inside Crystl.app at Contents/Helpers/crystl. The install action symlinks /usr/local/bin/crystl to that path; manual install is sudo ln -sfh /Applications/Crystl.app/Contents/Helpers/crystl /usr/local/bin/crystl.
Can I search through past sessions?
Yes. The search box spans all of a gem's sessions and matches both conversation text and tool calls: tool names, commands, file paths, and output. Click a result to open that session at the exact moment.
How does an agent put text in the copy bar?
Two ways. It runs crystl copy "<text>" with the text inline, or it pipes a command's output into it: <cmd> | crystl copy. The text appears in the bar under the terminal, ready for you to click Copy.
How many agents can be in a quest party?
You can summon as many agents as your machine can handle. The default party templates include 4 roles, but you can add more.
Do floating cards work with Codex?
Yes. Codex supports hooks, so approval cards and notifications work for Codex just like Claude Code. Antigravity CLI doesn't fully support hooks yet, so cards don't fire for Antigravity sessions.
What is a multitasking terminal for AI agents?
It's a terminal that lets you handle many different tasks and agents at once without getting lost in tabs and windows. crystl solves this in several ways. Every project is discoverable by name and a custom colored icon, and a dockside rail keeps them all in one place: click an icon and that project comes forward. Agentic hooks surface 'floating cards' for approvals, questions, and notifications that you can act on by clicking a button or typing a reply, without switching to that project at all. Orchestration makes multitasking easier still: assign an orchestrator agent to run subagents, or launch crystl quest to spawn a preselected party of agents that collaborate on a task together. And a per-project workbench keeps a shared task list your agents read and write alongside you, so nothing falls through the cracks.
How is a Hero Shard different from a quest?
A <a href='/features/crystl-quest/'>Quest</a> summons a party of heroes that coordinate as peers in a shared chat. A Hero Shard summons a single hero as one standalone shard: no party, no chat orchestration. Use a Hero Shard when you just need one specialist.
How many projects can I have open at once?
As many as you like, on every plan including the free one. You're limited only by what your machine can comfortably run.
If the tool already starts the agents, what's hard about running many?
Starting them is the easy part. They don't finish in parallel; they block in parallel, each on its own schedule, so at any moment some unknown subset is sitting idle waiting on you. Past a handful, the limiting factor isn't model speed or token budget; it's how fast you can tell which agent needs a decision right now.
How many isolated shards can I run at once?
As many as you like, on every plan including the free one. Run as many parallel sessions as your machine can handle.
What does the optimizer check?
Findings run across four weighted categories: content (what your instructions say), files (which instruction files exist and how they connect), code (source files that have grown too large), and setup (.claude/settings.json, plugin recommendations). Which checks apply depends on the project's type — a Code gem gets build/test/convention checks, a Research gem gets sources and a citation convention instead.
How many facet inserts can I have?
Your library is unlimited on every plan, including free. Each of the 3 facet buttons can hold up to 8 prompts in a priority list, giving you quick access to 24 prompts from 3 buttons; the rest of the library stays a click away in the menu.
Do I need to install anything on the remote?
No. When auto-tunnel is enabled, crystl installs hooks on the remote automatically via SSH RemoteCommand.
How do I schedule an agent?
Two ways: the Settings → Agents → Schedules panel, or the crystl CLI: crystl schedule add --gem <gem> --at "09:00" --every weekdays --prompt "...". Use crystl schedule list to see what's queued and crystl schedule cancel <id> to remove one.
Does it only find screenshots on my Desktop?
No. The screenshot bar uses macOS Spotlight metadata (kMDItemIsScreenCapture) to find screenshots anywhere on your machine: Desktop, Downloads, iCloud Drive, or any custom screenshot folder you've configured in macOS.
What is a sequence?
A recurring job written down once and automated end to end. It runs as a set of agent stages, each handed what the last one produced, and it can start itself. The definition lives at .crystl/sequences/<name>/sequence.json in your own repository.
What is a skill?
A markdown file that teaches your agent a specific behavior. When you type /skill-name, agents like Claude Code or Codex follow the instructions in that file.
Where is the workbench stored?
In a plain WORKBENCH.md at the project root, committed on purpose, so the workbench lives in the repo with everything else. It's standard GitHub-flavored markdown: ## headers are sections, - [ ] / - [x] are open and done tasks, and indented lines under a task are its description.
When does the turns-left estimate appear?
Once a shard has accumulated three or more turns with real token data. Three turns is the minimum for a meaningful burn rate, so before that the indicator stays hidden rather than showing a wild estimate from one outlier turn.
What's the difference between the all-gems and per-gem views?
The all-gems view lists every agent grouped by gem, with full token detail and a workspace-wide tokens-burned footer. The per-gem view condenses to just that gem's shards and their live state, handy when you only care about one project.
What is the block editor?
A two-column editor that breaks your file into logical sections (Build & Run, Architecture, Conventions, etc.). You can drag to reorder, click to edit inline, or toggle to raw text mode at any time.
What can read the metadata?
crystl itself (the history navigator, mobile rendering, detected-table copy) and any agent via the CLI. crystl screen --json returns the live grid plus shard state (agent, status, awaiting-input, last output); crystl history --json returns the full typed transcript: user turns, assistant text, and tool calls linked by id to their results.
What is the difference between a Claude Code GUI and the terminal?
The terminal gives you one text surface per session, and everything you need has to fit inside it in the order it happened. A GUI can put things beside each other: a list of every running session, an approval request that floats over whatever you are doing, a folded tool call you can expand, a token count in the status bar. crystl keeps the terminal and adds those surfaces, rather than replacing the CLI with a chat box.
How do I find a Claude Code session I lost?
If it was the last session in that directory, <code>claude --continue</code> gets it back. Otherwise run <code>claude --resume</code> for the interactive picker, which accepts a search term. The transcripts also sit on disk as JSONL at <code>~/.claude/projects/<project-slug>/<session-uuid>.jsonl</code>, so grep works when the picker does not. In crystl, <code>Cmd+Shift+F</code> searches every past conversation and command across every project at once.
Does Claude Code have a web UI?
Yes. Anthropic runs Claude Code on the web at claude.ai/code, alongside the CLI, a desktop app, and IDE extensions for VS Code and JetBrains. Community projects also wrap the CLI in a browser interface. crystl takes a different route: a native macOS app where each session is still the terminal CLI, with the supervision surfaces layered on top.
Can I use crystl instead of tmux to run Claude Code?
Yes, and it's built for it. tmux multiplexes terminal panes but knows nothing about your agents. crystl is agent-aware: it groups Claude Code sessions into projects, gives each isolated agent its own git worktree and branch, and floats approvals and questions as on-screen panels instead of burying them in a pane you have to switch to. You get the parallelism of a multiplexer plus controls tmux can't offer.
Does the CLI need a separate auth setup?
No. crystl writes a bearer token to ~/.crystl-bridge-token at launch (0600 permissions, regenerated each run). The CLI reads it automatically and sends Authorization: Bearer <token> on every request.
Does it include tool calls?
Yes. A Tools view lists every tool call with its input and result; click one to expand the full payload. Conversation and Tools are separate tabs so each stays clean.
Can I change the text before copying it?
Yes. The bar is editable. Tweak a value, fix a path, or trim a generated snippet, then click Copy. What you copy is what's in the bar at that moment, not whatever the agent originally sent.
Can agents message each other directly?
Yes. Agents use @mentions to target a specific shard. These appear as DM threads in the quest panel sidebar.
Can I approve actions from a different window?
Yes. Cards are non-activating, so they float on screen without stealing focus.
Does crystl only work with Claude Code?
No. Any CLI agent runs in crystl, since every shard is a full terminal session. The deeper integrations depend on what each agent exposes: Claude Code has the deepest integration, and Codex supports hooks too, so approval cards and notifications work for both. Antigravity CLI doesn't support hooks yet, so those features aren't available for Antigravity sessions, but everything else works.
How do I launch a Hero Shard?
In any gem, click the summon-a-hero button next to the shard <code>+</code> in the shard bar. Pick a hero from the grid and it opens as a new shard.
Can I rearrange gems in the crystal rail?
Yes. Drag gems to reorder them, and the Rail remembers your layout between sessions.
How do I know which agent needs me?
crystl surfaces it for you. A pending approval, a question, or a finished task reaches you in a floating panel, a session that changes color, a notification, or a push to your phone, across every open project. You don't go hunting session by session; the agent that needs a decision comes to you.
Do isolated shards work with any git repo?
Yes. They use standard git worktrees, so any git repository works.
How does the scoring work?
Content is weighted 3x, files and code 2x, and setup 1x, combined into one score out of 100: high (75+), medium (40-74), low (below 40). Every finding is also labeled structure (a starter kit can fix it) or substance (only you can). A check your project's type rules out costs nothing, so every type can reach 100 — a check crystl genuinely couldn't measure still counts against you, but it's capped so not knowing never costs more than the worst real answer would have.
Can I share facets between projects?
Yes. Facets are global, so they appear in every gem and shard.
Does file relay work without the auto-tunnel?
File relay requires the SSH ControlMaster socket, which the auto-tunnel sets up.
Can a schedule run a command instead of an agent?
Yes. Pick the command target in the schedule form, or pass --command instead of --prompt, and crystl runs one shell command in a fresh shard with no agent at all. That is the right choice when the task is already decided, like bash scripts/backup.sh: no model in the loop means it is faster, it spends no tokens, and it does the same thing every run. A command schedule takes no agent, no model, and no phone reminder.
How many screenshots does it show?
Up to 30 of your most recent screenshots, sorted newest first. The bar is horizontally scrollable, so you can scroll back through older captures.
What sort of work is worth automating this way?
Anything you redo on a rhythm and keep putting off. Filing a call transcript as a memory, turning it into tasks and a client record, triaging the overnight test failures, or sweeping a feed for what changed and writing it up. The job has to be describable in steps; it does not have to be code.
Can I create my own skills?
Yes. Add any .md file to your starters with a path like .claude/commands/my-skill.md. It works just like library skills.
How does the agent see it?
crystl adds a short note to your CLAUDE.md / AGENTS.md telling the agent that WORKBENCH.md is the project's editable workbench and how it's structured. From there the agent reads it to see priorities and edits the file directly to check items off or add new ones. No special tool required, just file edits.
How is the estimate calculated?
It's (window − used) ÷ burn rate, where burn rate is the shard's average tokens per turn so far. A shard reading large files burns faster and shows fewer turns left than one doing short exchanges.
Does it work with agents other than Claude Code?
Yes. The panel reflects live activity and token usage for any CLI agent running in a shard (Claude Code, Codex, and others), since it reads each shard's state and transcript, not a Claude-specific hook.
What are Claude Rules?
Modular .claude/rules/*.md files that Claude Code auto-discovers and loads each session. Rules can be scoped to specific paths so they only load when you're working in the relevant part of your project.
Is the Metal GPU rendering the main feature?
It's the supporting one. Metal keeps the terminal drawing fast under heavy output, but the point of Cavrn is the structured, agent-readable model underneath. Speed is table stakes; readable structure is the difference.
Is crystl a Claude Code GUI or a terminal?
Both. It is a native macOS terminal app, so every session is a real shell running the real Claude Code CLI with your CLAUDE.md, MCP servers, skills, plan mode, and slash commands unchanged. The GUI layer is what sits around the sessions: project tabs, the crystal rail, floating approval and question cards, split view, history search, and token tracking.
What happens to a Claude Code session when I close the terminal tab?
The transcript survives, the running process does not. You can resume the conversation later, but anything mid-flight stops. crystl keeps a short undo-close list per project, so <code>crystl resurrect</code> brings the shard back with its name, color, worktree isolation, and agent session restored.
How do I see which Claude Code agent is waiting for my approval?
Claude Code fires a hook when it wants permission to run a tool. crystl listens for it and floats an approval card showing the tool name, the working directory, and allow and deny buttons, tinted to the session that asked. When several requests queue up, an allow-all bar appears. Nothing needs to be in focus for the panel to reach you.
How do I run multiple Claude Code sessions at once?
In crystl, each project is a <em>gem</em> that holds multiple terminal <em>shards</em>: open as many Claude Code sessions as you want and run them side by side. Isolated shards each get their own git worktree and branch, so many agents can work the same repo simultaneously without stepping on each other.
Can I drive the bridge directly from curl or another language?
Yes. The CLI is a thin wrapper around http://127.0.0.1:19280/api/v1/. Endpoints, JSON shapes, and curl examples are in the CLI docs. Local loopback requests use the bridge token directly; non-loopback mutating requests require remote access to be enabled.
Does it work with Codex or Antigravity CLI?
Not yet. The navigator reads Claude Code's transcript format; Codex and Antigravity CLI record their history differently, so opening the navigator on one of those shards shows a Claude-only notice. crystl history replay is likewise Claude-only for now. The timeline, meaning global search (Cmd+Shift+F) and crystl history search, is agent-neutral: Claude, Codex, and Antigravity conversations all ingest, and shell commands are recorded for every shard.
What are the tabs for?
The copy bar holds up to 10 numbered tabs, so an agent emitting several snippets can stage them all at once. A plain crystl copy appends a new tab; --tab N overwrites tab N in place; --label "<title>" names the active tab's chip. Tabs only show once there are two or more.
What heroes are in the default catalog?
15 core heroes ship built in: Wizard (UI/UX), Ranger (Frontend), Rogue (Backend), Paladin (Researcher), Druid (Planner), Bard (Reviewer), Monk (QA), Healer (Context Health), Seeker (Debugging), Sentinel (Security), Dwarf (DevOps), and more. Syncing from crystl.dev in Settings → Heroes expands the catalog to the full roster, currently 30. Each has default stats, a personality, and a charter. <a href='/library/heroes/'>Browse all heroes in the Library</a>.
What's the difference between Smart and Auto mode?
Smart mode automatically approves read-only tools like file reads and searches, but still asks you before Claude edits files or runs commands. Auto mode lets Claude work without any approval prompts.
Do I need crystl if I already run Claude Code in a terminal?
Probably not, if one agent on one project at a time is all you do. crystl is for the point where you want more than that. Several agents running at once, each on its own branch. Notifications telling you which one is stuck and what it needs. A searchable record of every session, kept on your own machine. Schedules that run work while you're away from the desk. The friction it removes mostly shows up once you stop working one session at a time.
What does the hero bring to the shard?
Its own agent, model, and persona: the role, personality, stat modifiers, and system prompt the hero is configured with. The shard starts already set up as that specialist.
What happens to my shards when I close a gem?
Agent sessions autosave continuously. When you restart crystl, every session is restored exactly where you left off: context, conversation, and all. Closing a gem also saves the session history so you can browse past sessions any time.
Can I run different models from different companies at once?
Yes. Claude Code, Codex, and other CLI agents run side by side in one view and one chat, so you can put the right model on each job. Integration depth varies: the richest surfacing (approval cards via hooks) is Claude Code-first, Codex partial, others at terminal level. Every agent still shows on the rail, and crystl flags any of them the moment it's blocked.
What happens if two agents edit the same file?
They can. Each edits a separate working copy on its own branch, so neither overwrites the other's live file. If they change the same lines, git surfaces a conflict when you integrate the branches.
What can I fix directly from the optimizer?
Most structural gaps have a one-click action. Some create a file or insert a block; others — oversized files, a settings.json that won't parse, an import loop, missing permission rules, a credential in a public file — hand a scoped prompt straight to the agent already running in that gem. A couple, like a CLAUDE.local.md git would commit, get fixed with one line crystl writes to .gitignore itself. Substance gaps and the direction-file finding hand your agent a drafting prompt instead (the create north star button). For everything else, the export button generates a report you can hand to your agent.
What's the difference between a prompt and a command?
Prompts send text to your agent's input. Commands execute directly in the shell. Shortcuts trigger crystl actions.
Do approval cards appear locally?
Yes. Claude on the remote posts to localhost:19280, which the SSH tunnel redirects to your Mac.
Can one schedule do a different thing each day?
Yes. Turn on "rotate through a list" (or repeat --prompt / --command on the CLI) and the schedule holds an ordered list. Each firing takes the next entry and wraps at the end, so five prompts on weekdays give a different task each weekday. Up to 31 entries, prompts or commands, not a mix. Rotation counts positions rather than weekdays, so a missed run or a timing edit can shift which entry lands on which day; the detail view always shows which one fires next.
What happens when I drag a thumbnail into the terminal?
crystl pastes the shell-escaped file path into the terminal input. If Claude Code is running, it reads the image file and can analyze, describe, or act on it. For remote SSH sessions, crystl uploads the file first, then pastes the remote path.
How is a sequence different from fanout or a scheduled agent?
Fanout spreads one task across many agents working at once. A schedule runs one payload on a timer, a prompt or a command, with no stages and no gates. A sequence automates a whole job: stages in order, each one handed the last one's output, each one checked before the next starts.
Are skills project-specific?
You can add a skill file to your starter files so it's written into every new gem, and you can also insert skills into existing gems from the gem settings panel.
Does the drawer update when the agent edits the file?
Yes. The drawer watches WORKBENCH.md and re-renders the moment it changes, whether the agent wrote it, you edited it in another editor, or a git operation touched it. You and the agent always see the same list.
What happens when I disable a plugin or skill?
For Claude, you can disable it for just this gem or for every gem and Claude session globally, and crystl injects /reload-plugins so the change takes effect mid-session. For Codex, disables land in ~/.codex/config.toml globally and you restart the codex process to apply them.
How does it know an agent is idle versus working?
It tracks each shard's live status and how long it's held it, so a shard mid-turn shows as working while one waiting on you shows idle with the elapsed time.
What does the line count indicator do?
When editing CLAUDE.md, the editor footer shows a live count: green under 150 lines, yellow at 150 to 200, red over 200. Claude Code recommends staying under 200 lines for best performance.
Do I have to turn it on?
No. Cavrn is the default surface for new shards. Existing shards keep the engine they were created with, so close and reopen one to move it onto Cavrn. xterm.js stays available as a fallback in Settings → Terminal Rendering.
Does a Claude Code GUI work on Windows or Linux?
Anthropic's own desktop app covers Mac and Windows, and browser-based community GUIs run anywhere you can run a browser and the CLI. crystl is macOS only. It is a native Swift app and it uses macOS-specific features such as the Keychain for API key storage.
How many Claude Code sessions can I manage at once?
The limit is attention and machine resources, not the tool. Roughly three to five sessions is where most people stop being able to review the output honestly. <code>crystl status</code> reports app memory and system memory pressure so you can size a fan-out before it hurts. See <a href="/blog/how-many-agents-can-you-run/">how many agents can you actually run</a>.
Can a UI show how many tokens Claude Code has used?
crystl records input and output tokens for every turn from the Stop hook, per session. After three turns it can compute a burn rate, and the status bar shows an estimate of how many turns fit in the remaining context window. The project optimizer also shows what each installed plugin and skill costs you before a session even starts.
How do I keep track of multiple Claude Code agents?
crystl shows every session at a glance: which agents are working, which are waiting on you, and what each one needs. Approval requests and questions float as glass panels color-coded by project, so you answer the right agent without hunting through windows, and token tracking shows how much context each session has left.
Does the agent snippet edit my instruction files every time?
Only when the marker-bracketed section would actually change. Re-opening with no diff is a no-op so git mtimes stay clean. The section can be removed to opt out one gem at a time, or you can flip the General settings toggle to opt out everywhere.
Can I read history from the command line?
Yes. crystl history prints a navigation index of a shard's transcript: one line per turn or tool call with a preview, plus a session summary (total tokens, tool calls, models, active time) on top. Fetch a whole row with --row <seq> or the durable --ref, filter with --index --tool <name> / --index --status ok|error|pending / --tools-only / --limit, or get every body with --all. Per-turn model, token usage, and duration come back with a fetched row, with --all, and in --json. Handy for an agent to review what happened earlier, or to judge a sibling worker's cost and context. --json still emits the full response. Claude Code shards only, for now.
Does the copy bar shrink my terminal?
No. The window grows taller to make room, with the top edge fixed, so the terminal keeps its size. The bar is half-width and pinned to the left under the terminal, not stretched by the sidebar or workbench chrome.
Do I need worktree isolation to use quest?
No. Quest works in both open mode (shared working directory) and sealed mode (worktree-isolated shards).
Can I set different sounds for different card types?
Yes. Settings > General > Sounds has separate pickers for approval, notification, denied, and question cards.
Why was crystl built?
Every feature started as a problem that came up running agents across half a dozen projects in a day. Switching tabs just to find out which agent was waiting. Writing the same long catch-up prompt at the start of every session. Two agents editing the same file and overwriting each other. Work that needed to happen at 6am without anyone watching it. None of it was on a roadmap; each one was a day where the friction got annoying enough to build something. The full list is on the <a href="/about/">about page</a>.
Can a Hero Shard run isolated?
Yes. Toggle <strong>isolated (own git worktree)</strong> when you summon, and the hero gets its own worktree and branch, the same isolation as any <a href='/features/parallel-sessions/'>isolated shard</a>.
Can two gems point to the same directory?
Yes. This can be useful for separate workspaces with different shard configurations for the same project.
What happens if I restart or my machine reboots?
Agent sessions autosave and restore when you relaunch, so a reboot or an overnight OS update doesn't tear down the work you've been shepherding. A fleet of long-running agents becomes ongoing work you can step away from, not a fragile session you're afraid to interrupt.
What if my project needs a custom setup step?
Add a setupCommand to .crystl/project.json. crystl runs it after dependency installation.
What if my project isn't code?
Set its type — Code, Research, Content, Records, Personal, Orchestration, or General — from the optimizer, gem settings, or the New Gem panel. The type is saved in NORTH-STAR.md and scopes which checks run, so a notes-and-finances gem is never asked for a build command.
Can I import facets from the Prompt Library?
Yes. The library has 200+ inserts organized by category. Click to import any of them.
Can I use the tunnel with multiple remotes at once?
Yes. Each SSH session gets its own ControlMaster socket. crystl tracks them independently.
What recurrence options are there?
Once (a one-off at a specific date and time), daily, weekdays (Monday–Friday), or a longer anchored cadence: weekly, monthly, quarterly, or yearly. Times are interpreted in the IANA time zone you set, with daylight saving handled for you.
Can I keep the bar visible permanently?
Yes. Toggle the bar on with ⇧⌘S or View > screenshot bar, and it stays visible, even after restarting crystl. Toggle it off the same way when you don't need it.
What can start a sequence?
Four triggers are implemented today: manual, a calendar schedule at a wall-clock time, a change to a watched file path, and a polled URL whose content changed. Watched paths are literal prefixes rather than globs, and a poll response has to validate against a JSON Schema you declare before the run starts.
Do I need Guild for skills?
You can create and use your own skills for free. The Skills Library catalog requires a Guild membership to browse and import.
What happens to lines the drawer doesn't understand?
They're preserved verbatim. The parser only recognizes section headers and task lines; everything else (prose, notes, blank lines) round-trips through the drawer unchanged, so a hand-edit or an agent edit never gets clobbered.
What does the panel track per turn?
Input tokens (prompt, history, tools, and file contents sent in) and output tokens (text, tool calls, and thinking generated). Each Stop hook appends a TurnMetric to the shard's session log; if the payload lacks token data, crystl falls back to parsing the transcript.
Where do the token numbers come from?
Each row shows the shard's context load, output, and estimated turns left from its transcript, and the footer shows tokens burned today and over the past seven days. For a per-turn breakdown of what each plugin and skill costs, see Context Load Tracking.
Does this work over SSH?
Yes. File creation, template writing, rule setup, and the full block editor all work on remote projects over SSH.
Does it work with any agent?
Yes. Cavrn captures whatever runs in the shard: Claude Code, Codex, or a plain shell. The structured model is built from the output itself, so it doesn't depend on the agent.
Can a GUI run several Claude Code sessions at once?
In crystl, yes. A project holds as many sessions as you want, and an isolated session gets its own git worktree and branch with dependencies installed, so several agents can work the same repository at the same time without overwriting each other. Each session tab shows how many commits its branch is ahead of the base.
Is a session manager the same thing as a Claude Code UI?
Related, different job. A <a href="/claude-code-ui/">UI</a> renders the conversation nicely. A session manager tracks sessions as objects you can list, search, resume, and account for. crystl does both, but the second one is the part that scales past one agent. The longer argument is in <a href="/blog/what-a-claude-code-gui-should-do/">what a Claude Code GUI should actually do</a>.
Is there a UI for running several Claude Code sessions at once?
Yes. In crystl a project is a gem and each session inside it is a shard, so you can open as many Claude Code sessions in a project as you want. Isolated shards each get their own git worktree and branch, which is what lets several agents work the same repository at the same time without overwriting each other.
Does it work over SSH?
Yes. SSH shards can route notifications and CLI bridge calls back to your Mac. If the default reverse tunnel conflicts with the remote host, `crystl ssh bridge-address <host:port>` sets a direct bridge address for the next SSH connection.
Does it work for remote sessions?
Yes. A remote (SSH) shard's transcript is fetched over the existing connection and read with the same navigator and CLI.
Is the copy bar free?
Yes, on every tier. It's a deliberate hook, like feedback. It's still loopback-gated, so a paired phone needs remote access enabled to use it, but there's no Guild membership required on your Mac.
Can I save custom party configurations?
Yes. Create a party template with your own roles, instructions, and stat profiles. Reuse it across projects.
Do question cards work over SSH?
Yes. All card types work over SSH when the auto-tunnel is enabled.
Can I use crystl for regular terminal work?
Yes. Every shard is a full terminal session. You can use crystl as your daily terminal for any command-line work: git, npm, docker, ssh, whatever you need. The AI-specific features are there when you want them.
Where do the heroes come from?
Your hero roster (the same one quest uses), plus any local project heroes defined in <code>.crystl/heroes/</code>. <a href='/library/heroes/'>Browse the hero catalog in the Library</a>.
Does crystl only work with Claude Code?
crystl is built around Claude Code, but it also has early support for OpenAI Codex. Features like approval cards rely on hooks that Claude Code provides.
Can the agents coordinate with each other?
Two ways. With Roundtable orchestration (crystl quest), a party of agents share a chat room and coordinate as peers (@mentioning, handing off, DMing) across projects and even across the local/remote boundary. And through the crystl CLI, an agent can spawn and drive its own independent workers, complementary to the subagents an engine like Claude Code spawns inside its own process.
What happens to a shard's branch after merging?
crystl cleans up the worktree and branch automatically after a successful merge.
Does it work with monorepos?
Yes. The optimizer reads whatever your agent actually reads: it follows an @-import or symlink chain from CLAUDE.md, including one that leads to AGENTS.md. It doesn't penalize a monorepo for not duplicating CLAUDE.md into every subpackage, since Claude Code already reads the root file from anywhere in the tree.
How do I configure which facets appear?
Click the gear icon next to the facet bar, or go to Settings > Facet Inserts. Drag prompts within a slot to reorder the priority list.
What if port 19280 is already in use on the remote?
The first tunnel binds the port. Subsequent connections see 'address already in use' but this is harmless.
What can I configure per schedule?
For an agent prompt, the same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, an optional phone reminder, and an optional isolated worktree. For a command, the gem, the command itself, and the isolated worktree option. You can also give any schedule a name so it's easy to find later.
Does the bar update in real time?
Yes. The Spotlight query runs in live-update mode, so new screenshots appear in the bar within a few seconds of being taken. No refresh needed.
What stops a stage from producing garbage for the next one?
Its accept gate. A stage can require that files exist, that they are non-empty, or that they match a JSON schema. If a stage promised a file and did not write it, the stage fails and the run stops rather than handing the next stage an empty input.
Does it work with Codex and Antigravity CLI?
Yes. The workbench is just a markdown file plus a note in your agent config, so any CLI agent that can read and write files works the same way: Claude Code, Codex, Antigravity CLI, or anything else you run in a shard.
Does this work with Codex?
Yes, with fewer scopes. crystl scans ~/.codex/plugins/cache and ~/.agents/skills for Codex shards. Codex has no per-project plugin scope and no hot-reload, so disables are global and need a codex restart, where Claude disables can be gem-scoped and apply live.
Do I lose Claude Code features by using a GUI?
Not in crystl, because nothing is reimplemented. The CLI runs as it always does, so plan mode, slash commands, hooks, subagents, MCP servers, skills, and approval modes all behave the same. Wrappers that rebuild the interface around an API instead of the CLI are the ones to check on this, feature by feature.
Does crystl work with agents other than Claude Code?
Yes. Sessions in crystl are terminal sessions, so Codex and Antigravity CLI run alongside Claude Code in the same window. Timeline search and undo-close cover all of them, and undo-close resumes each agent with its own resume mechanism. The history navigator reads Claude Code transcripts specifically, because the other agents record history in different formats.
Does a UI for Claude Code work with other agents?
In crystl, yes. Every shard is a full terminal session, so any CLI agent runs in it. The panel features depend on what each agent exposes: Claude Code has the deepest integration, Codex supports hooks so approvals and notifications work there too, and Antigravity CLI does not support hooks yet, so those panels are unavailable for its sessions.
What is the timeline database?
A single local SQLite file (~/.config/crystl/history.db) where crystl keeps its own searchable index of agent conversations and shell commands. It powers Cmd+Shift+F, crystl history search, and the usage metrics. It's an index, never the source of truth: it's built from your transcripts and can always be rebuilt, and it never leaves your machine.
What are Quest Levels?
Levels give a quest a questline: an ordered set of stages the whole party works through together. Each level has an objective, and the party only advances once every hero checks in: done, blocked (with a reason), or nothing to do. A levels tab tracks the current stage, who you're waiting on, and the whole arc. See the <a href='/docs/quest-levels/'>Quest Levels docs</a>.
What is the CLAUDE.md manager?
crystl lets you store and name different CLAUDE.md starter files. When you open a project, you can insert the right starter file into the directory, useful if you maintain different instruction sets for different types of work.
Can my agent summon hero shards for me?
Yes. With the <a href='/features/cli/'>crystl CLI</a> enabled (a Guild feature), ask your agent to summon specific heroes on specific models and it spawns the shards for you, no panel needed. The exact commands live in the <a href='/docs/cli/'>CLI reference</a>.
What does anointing an orchestrator actually do?
The anoint button (a crown) briefs a shard's agent on the worker protocol and marks it with a castle icon. Workers it spawns wear a dot in the lead's crystal color, so siblings group visually. The chat dock (Cmd+Y) grows a workers tab with a live roster, workers push a report to the lead the moment they finish or get blocked (no polling), and a worker parked on an in-terminal prompt is flagged ⏸ awaiting input in crystl status, and the lead can block on it with crystl wait awaiting|idle.
Does it work over SSH?
Yes. The optimizer reads remote project files through crystl's SSH connection. Health scores, gap detection, and file creation all work on remote machines; plugin recommendations are skipped there since that state lives on your Mac.
How do I know whether a scheduled command worked?
Every command run reports an outcome: succeeded, failed with its exit code, no start seen, or unknown. "Unknown" means the command ran and crystl could not see how it went, so never read it as success. A failed run raises a card naming the command that ran and keeps its shard open so you can read the scrollback.
What happens when a stage finds nothing to do?
It reports crystl stage nothing, which is a success: the run keeps going. That is different from crystl stage blocked, which means the stage needs a person, so the run parks until you deal with it.
Can history be edited or deleted?
The transcripts the navigator reads are read-only; crystl never modifies or deletes them. The timeline index is fully deletable: Settings → Storage shows what's stored per project with scoped clearing (per gem, older-than, or everything), and crystl history clear does the same from the CLI. Clearing the index never touches your conversations, files, or projects. You only lose the ability to search that history in crystl.
Can a levelled quest deadlock if one agent gets stuck?
No. A level clears on check-ins, not successes. A stuck agent reports 'blocked' with a reason and the party still advances. crystl ships built-in questlines, and you can author your own per project in .crystl/questlines/.
Why did my new shard open in a different directory than my last one?
Every shard starts at its gem's project directory. Running cd in one shard only moves that shard; the next shard you create still starts at the gem root, so a project's shards stay predictable no matter where any one of them has wandered. crystl prints a hint in the new shard when this happens. If you do want a shard to start where you are, right-click (or control-click) the shard button. And if you start an agent in a sub-project (a git repo inside your gem), crystl offers to open that folder as its own gem, a suggestion you can always dismiss.
Is it free?
Watching is free on every tier: list sessions, read screens, stream events. The CLI control verbs (spawn a shard, send input, approve, merge) need a Guild membership.
How often should I run it?
After any major project change: new dependencies, restructured directories, or onboarding a new team member. The re-analyze button refreshes instantly, and a brand-new gem offers to run it for you.
Is scheduling free?
Yes. Up to 3 schedules on every tier, agent or command, rotating or not. A rotating schedule counts as one however many payloads it holds. Create, list, and cancel them from the desktop, CLI, or phone. Past three, a Guild membership lifts the cap.
Can different stages use different models?
Yes. Each stage picks its own agent and size, so the expensive parsing stage can run on a standard model while the later stages run on a small one. Sizes map to whatever you taught crystl, including an open model on your own hardware.
Where is history stored?
The transcripts the navigator reads are your agents' own, under ~/.claude on your machine. crystl additionally keeps the timeline index at ~/.config/crystl/history.db, plus per-project bookkeeping in .crystl (session-id map, scrollback snapshots). Everything stays local; nothing is uploaded.
Where did the isolation button go?
Its jobs moved closer to the things they act on. Creating an isolated shard now happens with the isolated-shard button in the shard bar (or the File menu). Merging and rebasing live on each shard's tab: a shard with unmerged commits shows a small ↑N badge you can click, and every action names the branch, target, and commit count so you know exactly what will move. A 'branches' button appears in the shard bar only when orphaned worktree branches exist, listing parked work from closed shards so you can reattach, merge, or discard it.
Are sequences free?
Writing and validating a definition is free on every tier, since it is a file in your own repository, and so is reading the catalog and the record of past runs. Running a sequence, and any schedule, file, or poll trigger that runs one for you, needs a Guild membership.
Is crystl free?
The free plan includes isolated shards & parallel sessions, floating cards, the agent activity panel, split view, history navigator, token tracking, workbench, project optimizer, agent file editor, screenshot & copy bars, MCP servers, API key storage, remote development over SSH, Metal-accelerated GPU rendering, facet inserts, and scheduling, agent or command, up to 3 schedules. The Guild plan ($170/year) adds the Prompt Library integration, formations (with session restore), CLI orchestration, unlimited scheduling, and priority support.
Are sequences finished?
They are an early preview. The shape of a definition file may still change between releases, so treat one you write today as something you may need to adjust later.
Does crystl work on Linux or Windows?
crystl is macOS only. It's a native Swift app and it uses macOS-specific features like the Keychain for secure API key storage.
Before you get started
Questions we hear most from new garden clients
If you don't see yours here, ask — every plan starts with a conversation, not a form.
How do I open the Agent Activity Panel?
Click the diamond icon at the top of the crystal rail to see every agent across all open gems. To scope it to one project, click a gem's tile once to focus it, then click it again to open the panel for just that gem.
What file types can I create?
CLAUDE.md, CLAUDE.local.md, AGENTS.md, codex.md, GEMINI.md, .cursorrules, .windsurfrules, copilot-instructions.md. Plus Claude Code's extended config: rules, skills, and settings.
What makes Cavrn different from a normal terminal?
A normal terminal gives you scrollback: characters on a grid. Cavrn keeps a structured model of the session: every turn, tool call, and result as typed, timestamped records, tables detected as data. The output becomes something agents and crystl can read and act on, not just display.
Is there a GUI for Claude Code?
Yes, several. Anthropic ships a Claude Code desktop app for Mac and Windows and a web version at claude.ai/code, plus IDE extensions for VS Code and JetBrains. Community projects such as Claudia and claudecodeui wrap the CLI in their own interface. crystl is a native macOS app that keeps every session as a real terminal running the Claude Code CLI, and adds approval cards, parallel sessions, and per-session token tracking around it.
Does Claude Code have a session manager?
Not as a separate surface. Claude Code stores every session as a transcript under <code>~/.claude/projects/</code> and gives you flags to get back into one: <code>claude --continue</code> for the most recent session in the current directory, and <code>claude --resume</code> for a picker or a specific session ID. There is no view of what is running, what is blocked, or what anything cost.
What is the best UI for Claude Code?
It depends on what you need to see. If you run one session at a time, Claude Code's own terminal interface is enough. Once several sessions run at once, you need something that shows which one is working, which is waiting on approval, what each just ran, and what each has cost. crystl is a macOS app built around exactly those four questions, and every session inside it is a real Claude Code session.
What's the best terminal for Claude Code?
crystl is a macOS terminal built specifically for Claude Code. Every shard runs the Claude Code CLI, and crystl adds what a plain terminal can't: run multiple sessions in parallel, surface hook approvals as on-screen panels, manage CLAUDE.md files per project, and track token and context usage. It also works as a regular terminal for any command-line work.
Where does the binary live?
Inside Crystl.app at Contents/Helpers/crystl. The install action symlinks /usr/local/bin/crystl to that path; manual install is sudo ln -sfh /Applications/Crystl.app/Contents/Helpers/crystl /usr/local/bin/crystl.
Can I search through past sessions?
Yes. The search box spans all of a gem's sessions and matches both conversation text and tool calls: tool names, commands, file paths, and output. Click a result to open that session at the exact moment.
How does an agent put text in the copy bar?
Two ways. It runs crystl copy "<text>" with the text inline, or it pipes a command's output into it: <cmd> | crystl copy. The text appears in the bar under the terminal, ready for you to click Copy.
How many agents can be in a quest party?
You can summon as many agents as your machine can handle. The default party templates include 4 roles, but you can add more.
Do floating cards work with Codex?
Yes. Codex supports hooks, so approval cards and notifications work for Codex just like Claude Code. Antigravity CLI doesn't fully support hooks yet, so cards don't fire for Antigravity sessions.
What is a multitasking terminal for AI agents?
It's a terminal that lets you handle many different tasks and agents at once without getting lost in tabs and windows. crystl solves this in several ways. Every project is discoverable by name and a custom colored icon, and a dockside rail keeps them all in one place: click an icon and that project comes forward. Agentic hooks surface 'floating cards' for approvals, questions, and notifications that you can act on by clicking a button or typing a reply, without switching to that project at all. Orchestration makes multitasking easier still: assign an orchestrator agent to run subagents, or launch crystl quest to spawn a preselected party of agents that collaborate on a task together. And a per-project workbench keeps a shared task list your agents read and write alongside you, so nothing falls through the cracks.
How is a Hero Shard different from a quest?
A <a href='/features/crystl-quest/'>Quest</a> summons a party of heroes that coordinate as peers in a shared chat. A Hero Shard summons a single hero as one standalone shard: no party, no chat orchestration. Use a Hero Shard when you just need one specialist.
How many projects can I have open at once?
As many as you like, on every plan including the free one. You're limited only by what your machine can comfortably run.
If the tool already starts the agents, what's hard about running many?
Starting them is the easy part. They don't finish in parallel; they block in parallel, each on its own schedule, so at any moment some unknown subset is sitting idle waiting on you. Past a handful, the limiting factor isn't model speed or token budget; it's how fast you can tell which agent needs a decision right now.
How many isolated shards can I run at once?
As many as you like, on every plan including the free one. Run as many parallel sessions as your machine can handle.
What does the optimizer check?
Findings run across four weighted categories: content (what your instructions say), files (which instruction files exist and how they connect), code (source files that have grown too large), and setup (.claude/settings.json, plugin recommendations). Which checks apply depends on the project's type — a Code gem gets build/test/convention checks, a Research gem gets sources and a citation convention instead.
How many facet inserts can I have?
Your library is unlimited on every plan, including free. Each of the 3 facet buttons can hold up to 8 prompts in a priority list, giving you quick access to 24 prompts from 3 buttons; the rest of the library stays a click away in the menu.
Do I need to install anything on the remote?
No. When auto-tunnel is enabled, crystl installs hooks on the remote automatically via SSH RemoteCommand.
How do I schedule an agent?
Two ways: the Settings → Agents → Schedules panel, or the crystl CLI: crystl schedule add --gem <gem> --at "09:00" --every weekdays --prompt "...". Use crystl schedule list to see what's queued and crystl schedule cancel <id> to remove one.
Does it only find screenshots on my Desktop?
No. The screenshot bar uses macOS Spotlight metadata (kMDItemIsScreenCapture) to find screenshots anywhere on your machine: Desktop, Downloads, iCloud Drive, or any custom screenshot folder you've configured in macOS.
What is a sequence?
A recurring job written down once and automated end to end. It runs as a set of agent stages, each handed what the last one produced, and it can start itself. The definition lives at .crystl/sequences/<name>/sequence.json in your own repository.
What is a skill?
A markdown file that teaches your agent a specific behavior. When you type /skill-name, agents like Claude Code or Codex follow the instructions in that file.
Where is the workbench stored?
In a plain WORKBENCH.md at the project root, committed on purpose, so the workbench lives in the repo with everything else. It's standard GitHub-flavored markdown: ## headers are sections, - [ ] / - [x] are open and done tasks, and indented lines under a task are its description.
When does the turns-left estimate appear?
Once a shard has accumulated three or more turns with real token data. Three turns is the minimum for a meaningful burn rate, so before that the indicator stays hidden rather than showing a wild estimate from one outlier turn.
What's the difference between the all-gems and per-gem views?
The all-gems view lists every agent grouped by gem, with full token detail and a workspace-wide tokens-burned footer. The per-gem view condenses to just that gem's shards and their live state, handy when you only care about one project.
What is the block editor?
A two-column editor that breaks your file into logical sections (Build & Run, Architecture, Conventions, etc.). You can drag to reorder, click to edit inline, or toggle to raw text mode at any time.
What can read the metadata?
crystl itself (the history navigator, mobile rendering, detected-table copy) and any agent via the CLI. crystl screen --json returns the live grid plus shard state (agent, status, awaiting-input, last output); crystl history --json returns the full typed transcript: user turns, assistant text, and tool calls linked by id to their results.
What is the difference between a Claude Code GUI and the terminal?
The terminal gives you one text surface per session, and everything you need has to fit inside it in the order it happened. A GUI can put things beside each other: a list of every running session, an approval request that floats over whatever you are doing, a folded tool call you can expand, a token count in the status bar. crystl keeps the terminal and adds those surfaces, rather than replacing the CLI with a chat box.
How do I find a Claude Code session I lost?
If it was the last session in that directory, <code>claude --continue</code> gets it back. Otherwise run <code>claude --resume</code> for the interactive picker, which accepts a search term. The transcripts also sit on disk as JSONL at <code>~/.claude/projects/<project-slug>/<session-uuid>.jsonl</code>, so grep works when the picker does not. In crystl, <code>Cmd+Shift+F</code> searches every past conversation and command across every project at once.
Does Claude Code have a web UI?
Yes. Anthropic runs Claude Code on the web at claude.ai/code, alongside the CLI, a desktop app, and IDE extensions for VS Code and JetBrains. Community projects also wrap the CLI in a browser interface. crystl takes a different route: a native macOS app where each session is still the terminal CLI, with the supervision surfaces layered on top.
Can I use crystl instead of tmux to run Claude Code?
Yes, and it's built for it. tmux multiplexes terminal panes but knows nothing about your agents. crystl is agent-aware: it groups Claude Code sessions into projects, gives each isolated agent its own git worktree and branch, and floats approvals and questions as on-screen panels instead of burying them in a pane you have to switch to. You get the parallelism of a multiplexer plus controls tmux can't offer.
Does the CLI need a separate auth setup?
No. crystl writes a bearer token to ~/.crystl-bridge-token at launch (0600 permissions, regenerated each run). The CLI reads it automatically and sends Authorization: Bearer <token> on every request.
Does it include tool calls?
Yes. A Tools view lists every tool call with its input and result; click one to expand the full payload. Conversation and Tools are separate tabs so each stays clean.
Can I change the text before copying it?
Yes. The bar is editable. Tweak a value, fix a path, or trim a generated snippet, then click Copy. What you copy is what's in the bar at that moment, not whatever the agent originally sent.
Can agents message each other directly?
Yes. Agents use @mentions to target a specific shard. These appear as DM threads in the quest panel sidebar.
Can I approve actions from a different window?
Yes. Cards are non-activating, so they float on screen without stealing focus.
Does crystl only work with Claude Code?
No. Any CLI agent runs in crystl, since every shard is a full terminal session. The deeper integrations depend on what each agent exposes: Claude Code has the deepest integration, and Codex supports hooks too, so approval cards and notifications work for both. Antigravity CLI doesn't support hooks yet, so those features aren't available for Antigravity sessions, but everything else works.
How do I launch a Hero Shard?
In any gem, click the summon-a-hero button next to the shard <code>+</code> in the shard bar. Pick a hero from the grid and it opens as a new shard.
Can I rearrange gems in the crystal rail?
Yes. Drag gems to reorder them, and the Rail remembers your layout between sessions.
How do I know which agent needs me?
crystl surfaces it for you. A pending approval, a question, or a finished task reaches you in a floating panel, a session that changes color, a notification, or a push to your phone, across every open project. You don't go hunting session by session; the agent that needs a decision comes to you.
Do isolated shards work with any git repo?
Yes. They use standard git worktrees, so any git repository works.
How does the scoring work?
Content is weighted 3x, files and code 2x, and setup 1x, combined into one score out of 100: high (75+), medium (40-74), low (below 40). Every finding is also labeled structure (a starter kit can fix it) or substance (only you can). A check your project's type rules out costs nothing, so every type can reach 100 — a check crystl genuinely couldn't measure still counts against you, but it's capped so not knowing never costs more than the worst real answer would have.
Can I share facets between projects?
Yes. Facets are global, so they appear in every gem and shard.
Does file relay work without the auto-tunnel?
File relay requires the SSH ControlMaster socket, which the auto-tunnel sets up.
Can a schedule run a command instead of an agent?
Yes. Pick the command target in the schedule form, or pass --command instead of --prompt, and crystl runs one shell command in a fresh shard with no agent at all. That is the right choice when the task is already decided, like bash scripts/backup.sh: no model in the loop means it is faster, it spends no tokens, and it does the same thing every run. A command schedule takes no agent, no model, and no phone reminder.
How many screenshots does it show?
Up to 30 of your most recent screenshots, sorted newest first. The bar is horizontally scrollable, so you can scroll back through older captures.
What sort of work is worth automating this way?
Anything you redo on a rhythm and keep putting off. Filing a call transcript as a memory, turning it into tasks and a client record, triaging the overnight test failures, or sweeping a feed for what changed and writing it up. The job has to be describable in steps; it does not have to be code.
Can I create my own skills?
Yes. Add any .md file to your starters with a path like .claude/commands/my-skill.md. It works just like library skills.
How does the agent see it?
crystl adds a short note to your CLAUDE.md / AGENTS.md telling the agent that WORKBENCH.md is the project's editable workbench and how it's structured. From there the agent reads it to see priorities and edits the file directly to check items off or add new ones. No special tool required, just file edits.
How is the estimate calculated?
It's (window − used) ÷ burn rate, where burn rate is the shard's average tokens per turn so far. A shard reading large files burns faster and shows fewer turns left than one doing short exchanges.
Does it work with agents other than Claude Code?
Yes. The panel reflects live activity and token usage for any CLI agent running in a shard (Claude Code, Codex, and others), since it reads each shard's state and transcript, not a Claude-specific hook.
What are Claude Rules?
Modular .claude/rules/*.md files that Claude Code auto-discovers and loads each session. Rules can be scoped to specific paths so they only load when you're working in the relevant part of your project.
Is the Metal GPU rendering the main feature?
It's the supporting one. Metal keeps the terminal drawing fast under heavy output, but the point of Cavrn is the structured, agent-readable model underneath. Speed is table stakes; readable structure is the difference.
Is crystl a Claude Code GUI or a terminal?
Both. It is a native macOS terminal app, so every session is a real shell running the real Claude Code CLI with your CLAUDE.md, MCP servers, skills, plan mode, and slash commands unchanged. The GUI layer is what sits around the sessions: project tabs, the crystal rail, floating approval and question cards, split view, history search, and token tracking.
What happens to a Claude Code session when I close the terminal tab?
The transcript survives, the running process does not. You can resume the conversation later, but anything mid-flight stops. crystl keeps a short undo-close list per project, so <code>crystl resurrect</code> brings the shard back with its name, color, worktree isolation, and agent session restored.
How do I see which Claude Code agent is waiting for my approval?
Claude Code fires a hook when it wants permission to run a tool. crystl listens for it and floats an approval card showing the tool name, the working directory, and allow and deny buttons, tinted to the session that asked. When several requests queue up, an allow-all bar appears. Nothing needs to be in focus for the panel to reach you.
How do I run multiple Claude Code sessions at once?
In crystl, each project is a <em>gem</em> that holds multiple terminal <em>shards</em>: open as many Claude Code sessions as you want and run them side by side. Isolated shards each get their own git worktree and branch, so many agents can work the same repo simultaneously without stepping on each other.
Can I drive the bridge directly from curl or another language?
Yes. The CLI is a thin wrapper around http://127.0.0.1:19280/api/v1/. Endpoints, JSON shapes, and curl examples are in the CLI docs. Local loopback requests use the bridge token directly; non-loopback mutating requests require remote access to be enabled.
Does it work with Codex or Antigravity CLI?
Not yet. The navigator reads Claude Code's transcript format; Codex and Antigravity CLI record their history differently, so opening the navigator on one of those shards shows a Claude-only notice. crystl history replay is likewise Claude-only for now. The timeline, meaning global search (Cmd+Shift+F) and crystl history search, is agent-neutral: Claude, Codex, and Antigravity conversations all ingest, and shell commands are recorded for every shard.
What are the tabs for?
The copy bar holds up to 10 numbered tabs, so an agent emitting several snippets can stage them all at once. A plain crystl copy appends a new tab; --tab N overwrites tab N in place; --label "<title>" names the active tab's chip. Tabs only show once there are two or more.
What heroes are in the default catalog?
15 core heroes ship built in: Wizard (UI/UX), Ranger (Frontend), Rogue (Backend), Paladin (Researcher), Druid (Planner), Bard (Reviewer), Monk (QA), Healer (Context Health), Seeker (Debugging), Sentinel (Security), Dwarf (DevOps), and more. Syncing from crystl.dev in Settings → Heroes expands the catalog to the full roster, currently 30. Each has default stats, a personality, and a charter. <a href='/library/heroes/'>Browse all heroes in the Library</a>.
What's the difference between Smart and Auto mode?
Smart mode automatically approves read-only tools like file reads and searches, but still asks you before Claude edits files or runs commands. Auto mode lets Claude work without any approval prompts.
Do I need crystl if I already run Claude Code in a terminal?
Probably not, if one agent on one project at a time is all you do. crystl is for the point where you want more than that. Several agents running at once, each on its own branch. Notifications telling you which one is stuck and what it needs. A searchable record of every session, kept on your own machine. Schedules that run work while you're away from the desk. The friction it removes mostly shows up once you stop working one session at a time.
What does the hero bring to the shard?
Its own agent, model, and persona: the role, personality, stat modifiers, and system prompt the hero is configured with. The shard starts already set up as that specialist.
What happens to my shards when I close a gem?
Agent sessions autosave continuously. When you restart crystl, every session is restored exactly where you left off: context, conversation, and all. Closing a gem also saves the session history so you can browse past sessions any time.
Can I run different models from different companies at once?
Yes. Claude Code, Codex, and other CLI agents run side by side in one view and one chat, so you can put the right model on each job. Integration depth varies: the richest surfacing (approval cards via hooks) is Claude Code-first, Codex partial, others at terminal level. Every agent still shows on the rail, and crystl flags any of them the moment it's blocked.
What happens if two agents edit the same file?
They can. Each edits a separate working copy on its own branch, so neither overwrites the other's live file. If they change the same lines, git surfaces a conflict when you integrate the branches.
What can I fix directly from the optimizer?
Most structural gaps have a one-click action. Some create a file or insert a block; others — oversized files, a settings.json that won't parse, an import loop, missing permission rules, a credential in a public file — hand a scoped prompt straight to the agent already running in that gem. A couple, like a CLAUDE.local.md git would commit, get fixed with one line crystl writes to .gitignore itself. Substance gaps and the direction-file finding hand your agent a drafting prompt instead (the create north star button). For everything else, the export button generates a report you can hand to your agent.
What's the difference between a prompt and a command?
Prompts send text to your agent's input. Commands execute directly in the shell. Shortcuts trigger crystl actions.
Do approval cards appear locally?
Yes. Claude on the remote posts to localhost:19280, which the SSH tunnel redirects to your Mac.
Can one schedule do a different thing each day?
Yes. Turn on "rotate through a list" (or repeat --prompt / --command on the CLI) and the schedule holds an ordered list. Each firing takes the next entry and wraps at the end, so five prompts on weekdays give a different task each weekday. Up to 31 entries, prompts or commands, not a mix. Rotation counts positions rather than weekdays, so a missed run or a timing edit can shift which entry lands on which day; the detail view always shows which one fires next.
What happens when I drag a thumbnail into the terminal?
crystl pastes the shell-escaped file path into the terminal input. If Claude Code is running, it reads the image file and can analyze, describe, or act on it. For remote SSH sessions, crystl uploads the file first, then pastes the remote path.
How is a sequence different from fanout or a scheduled agent?
Fanout spreads one task across many agents working at once. A schedule runs one payload on a timer, a prompt or a command, with no stages and no gates. A sequence automates a whole job: stages in order, each one handed the last one's output, each one checked before the next starts.
Are skills project-specific?
You can add a skill file to your starter files so it's written into every new gem, and you can also insert skills into existing gems from the gem settings panel.
Does the drawer update when the agent edits the file?
Yes. The drawer watches WORKBENCH.md and re-renders the moment it changes, whether the agent wrote it, you edited it in another editor, or a git operation touched it. You and the agent always see the same list.
What happens when I disable a plugin or skill?
For Claude, you can disable it for just this gem or for every gem and Claude session globally, and crystl injects /reload-plugins so the change takes effect mid-session. For Codex, disables land in ~/.codex/config.toml globally and you restart the codex process to apply them.
How does it know an agent is idle versus working?
It tracks each shard's live status and how long it's held it, so a shard mid-turn shows as working while one waiting on you shows idle with the elapsed time.
What does the line count indicator do?
When editing CLAUDE.md, the editor footer shows a live count: green under 150 lines, yellow at 150 to 200, red over 200. Claude Code recommends staying under 200 lines for best performance.
Do I have to turn it on?
No. Cavrn is the default surface for new shards. Existing shards keep the engine they were created with, so close and reopen one to move it onto Cavrn. xterm.js stays available as a fallback in Settings → Terminal Rendering.
Does a Claude Code GUI work on Windows or Linux?
Anthropic's own desktop app covers Mac and Windows, and browser-based community GUIs run anywhere you can run a browser and the CLI. crystl is macOS only. It is a native Swift app and it uses macOS-specific features such as the Keychain for API key storage.
How many Claude Code sessions can I manage at once?
The limit is attention and machine resources, not the tool. Roughly three to five sessions is where most people stop being able to review the output honestly. <code>crystl status</code> reports app memory and system memory pressure so you can size a fan-out before it hurts. See <a href="/blog/how-many-agents-can-you-run/">how many agents can you actually run</a>.
Can a UI show how many tokens Claude Code has used?
crystl records input and output tokens for every turn from the Stop hook, per session. After three turns it can compute a burn rate, and the status bar shows an estimate of how many turns fit in the remaining context window. The project optimizer also shows what each installed plugin and skill costs you before a session even starts.
How do I keep track of multiple Claude Code agents?
crystl shows every session at a glance: which agents are working, which are waiting on you, and what each one needs. Approval requests and questions float as glass panels color-coded by project, so you answer the right agent without hunting through windows, and token tracking shows how much context each session has left.
Does the agent snippet edit my instruction files every time?
Only when the marker-bracketed section would actually change. Re-opening with no diff is a no-op so git mtimes stay clean. The section can be removed to opt out one gem at a time, or you can flip the General settings toggle to opt out everywhere.
Can I read history from the command line?
Yes. crystl history prints a navigation index of a shard's transcript: one line per turn or tool call with a preview, plus a session summary (total tokens, tool calls, models, active time) on top. Fetch a whole row with --row <seq> or the durable --ref, filter with --index --tool <name> / --index --status ok|error|pending / --tools-only / --limit, or get every body with --all. Per-turn model, token usage, and duration come back with a fetched row, with --all, and in --json. Handy for an agent to review what happened earlier, or to judge a sibling worker's cost and context. --json still emits the full response. Claude Code shards only, for now.
Does the copy bar shrink my terminal?
No. The window grows taller to make room, with the top edge fixed, so the terminal keeps its size. The bar is half-width and pinned to the left under the terminal, not stretched by the sidebar or workbench chrome.
Do I need worktree isolation to use quest?
No. Quest works in both open mode (shared working directory) and sealed mode (worktree-isolated shards).
Can I set different sounds for different card types?
Yes. Settings > General > Sounds has separate pickers for approval, notification, denied, and question cards.
Why was crystl built?
Every feature started as a problem that came up running agents across half a dozen projects in a day. Switching tabs just to find out which agent was waiting. Writing the same long catch-up prompt at the start of every session. Two agents editing the same file and overwriting each other. Work that needed to happen at 6am without anyone watching it. None of it was on a roadmap; each one was a day where the friction got annoying enough to build something. The full list is on the <a href="/about/">about page</a>.
Can a Hero Shard run isolated?
Yes. Toggle <strong>isolated (own git worktree)</strong> when you summon, and the hero gets its own worktree and branch, the same isolation as any <a href='/features/parallel-sessions/'>isolated shard</a>.
Can two gems point to the same directory?
Yes. This can be useful for separate workspaces with different shard configurations for the same project.
What happens if I restart or my machine reboots?
Agent sessions autosave and restore when you relaunch, so a reboot or an overnight OS update doesn't tear down the work you've been shepherding. A fleet of long-running agents becomes ongoing work you can step away from, not a fragile session you're afraid to interrupt.
What if my project needs a custom setup step?
Add a setupCommand to .crystl/project.json. crystl runs it after dependency installation.
What if my project isn't code?
Set its type — Code, Research, Content, Records, Personal, Orchestration, or General — from the optimizer, gem settings, or the New Gem panel. The type is saved in NORTH-STAR.md and scopes which checks run, so a notes-and-finances gem is never asked for a build command.
Can I import facets from the Prompt Library?
Yes. The library has 200+ inserts organized by category. Click to import any of them.
Can I use the tunnel with multiple remotes at once?
Yes. Each SSH session gets its own ControlMaster socket. crystl tracks them independently.
What recurrence options are there?
Once (a one-off at a specific date and time), daily, weekdays (Monday–Friday), or a longer anchored cadence: weekly, monthly, quarterly, or yearly. Times are interpreted in the IANA time zone you set, with daylight saving handled for you.
Can I keep the bar visible permanently?
Yes. Toggle the bar on with ⇧⌘S or View > screenshot bar, and it stays visible, even after restarting crystl. Toggle it off the same way when you don't need it.
What can start a sequence?
Four triggers are implemented today: manual, a calendar schedule at a wall-clock time, a change to a watched file path, and a polled URL whose content changed. Watched paths are literal prefixes rather than globs, and a poll response has to validate against a JSON Schema you declare before the run starts.
Do I need Guild for skills?
You can create and use your own skills for free. The Skills Library catalog requires a Guild membership to browse and import.
What happens to lines the drawer doesn't understand?
They're preserved verbatim. The parser only recognizes section headers and task lines; everything else (prose, notes, blank lines) round-trips through the drawer unchanged, so a hand-edit or an agent edit never gets clobbered.
What does the panel track per turn?
Input tokens (prompt, history, tools, and file contents sent in) and output tokens (text, tool calls, and thinking generated). Each Stop hook appends a TurnMetric to the shard's session log; if the payload lacks token data, crystl falls back to parsing the transcript.
Where do the token numbers come from?
Each row shows the shard's context load, output, and estimated turns left from its transcript, and the footer shows tokens burned today and over the past seven days. For a per-turn breakdown of what each plugin and skill costs, see Context Load Tracking.
Does this work over SSH?
Yes. File creation, template writing, rule setup, and the full block editor all work on remote projects over SSH.
Does it work with any agent?
Yes. Cavrn captures whatever runs in the shard: Claude Code, Codex, or a plain shell. The structured model is built from the output itself, so it doesn't depend on the agent.
Can a GUI run several Claude Code sessions at once?
In crystl, yes. A project holds as many sessions as you want, and an isolated session gets its own git worktree and branch with dependencies installed, so several agents can work the same repository at the same time without overwriting each other. Each session tab shows how many commits its branch is ahead of the base.
Is a session manager the same thing as a Claude Code UI?
Related, different job. A <a href="/claude-code-ui/">UI</a> renders the conversation nicely. A session manager tracks sessions as objects you can list, search, resume, and account for. crystl does both, but the second one is the part that scales past one agent. The longer argument is in <a href="/blog/what-a-claude-code-gui-should-do/">what a Claude Code GUI should actually do</a>.
Is there a UI for running several Claude Code sessions at once?
Yes. In crystl a project is a gem and each session inside it is a shard, so you can open as many Claude Code sessions in a project as you want. Isolated shards each get their own git worktree and branch, which is what lets several agents work the same repository at the same time without overwriting each other.
Does it work over SSH?
Yes. SSH shards can route notifications and CLI bridge calls back to your Mac. If the default reverse tunnel conflicts with the remote host, `crystl ssh bridge-address <host:port>` sets a direct bridge address for the next SSH connection.
Does it work for remote sessions?
Yes. A remote (SSH) shard's transcript is fetched over the existing connection and read with the same navigator and CLI.
Is the copy bar free?
Yes, on every tier. It's a deliberate hook, like feedback. It's still loopback-gated, so a paired phone needs remote access enabled to use it, but there's no Guild membership required on your Mac.
Can I save custom party configurations?
Yes. Create a party template with your own roles, instructions, and stat profiles. Reuse it across projects.
Do question cards work over SSH?
Yes. All card types work over SSH when the auto-tunnel is enabled.
Can I use crystl for regular terminal work?
Yes. Every shard is a full terminal session. You can use crystl as your daily terminal for any command-line work: git, npm, docker, ssh, whatever you need. The AI-specific features are there when you want them.
Where do the heroes come from?
Your hero roster (the same one quest uses), plus any local project heroes defined in <code>.crystl/heroes/</code>. <a href='/library/heroes/'>Browse the hero catalog in the Library</a>.
Does crystl only work with Claude Code?
crystl is built around Claude Code, but it also has early support for OpenAI Codex. Features like approval cards rely on hooks that Claude Code provides.
Can the agents coordinate with each other?
Two ways. With Roundtable orchestration (crystl quest), a party of agents share a chat room and coordinate as peers (@mentioning, handing off, DMing) across projects and even across the local/remote boundary. And through the crystl CLI, an agent can spawn and drive its own independent workers, complementary to the subagents an engine like Claude Code spawns inside its own process.
What happens to a shard's branch after merging?
crystl cleans up the worktree and branch automatically after a successful merge.
Does it work with monorepos?
Yes. The optimizer reads whatever your agent actually reads: it follows an @-import or symlink chain from CLAUDE.md, including one that leads to AGENTS.md. It doesn't penalize a monorepo for not duplicating CLAUDE.md into every subpackage, since Claude Code already reads the root file from anywhere in the tree.
How do I configure which facets appear?
Click the gear icon next to the facet bar, or go to Settings > Facet Inserts. Drag prompts within a slot to reorder the priority list.
What if port 19280 is already in use on the remote?
The first tunnel binds the port. Subsequent connections see 'address already in use' but this is harmless.
What can I configure per schedule?
For an agent prompt, the same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, an optional phone reminder, and an optional isolated worktree. For a command, the gem, the command itself, and the isolated worktree option. You can also give any schedule a name so it's easy to find later.
Does the bar update in real time?
Yes. The Spotlight query runs in live-update mode, so new screenshots appear in the bar within a few seconds of being taken. No refresh needed.
What stops a stage from producing garbage for the next one?
Its accept gate. A stage can require that files exist, that they are non-empty, or that they match a JSON schema. If a stage promised a file and did not write it, the stage fails and the run stops rather than handing the next stage an empty input.
Does it work with Codex and Antigravity CLI?
Yes. The workbench is just a markdown file plus a note in your agent config, so any CLI agent that can read and write files works the same way: Claude Code, Codex, Antigravity CLI, or anything else you run in a shard.
Does this work with Codex?
Yes, with fewer scopes. crystl scans ~/.codex/plugins/cache and ~/.agents/skills for Codex shards. Codex has no per-project plugin scope and no hot-reload, so disables are global and need a codex restart, where Claude disables can be gem-scoped and apply live.
Do I lose Claude Code features by using a GUI?
Not in crystl, because nothing is reimplemented. The CLI runs as it always does, so plan mode, slash commands, hooks, subagents, MCP servers, skills, and approval modes all behave the same. Wrappers that rebuild the interface around an API instead of the CLI are the ones to check on this, feature by feature.
Does crystl work with agents other than Claude Code?
Yes. Sessions in crystl are terminal sessions, so Codex and Antigravity CLI run alongside Claude Code in the same window. Timeline search and undo-close cover all of them, and undo-close resumes each agent with its own resume mechanism. The history navigator reads Claude Code transcripts specifically, because the other agents record history in different formats.
Does a UI for Claude Code work with other agents?
In crystl, yes. Every shard is a full terminal session, so any CLI agent runs in it. The panel features depend on what each agent exposes: Claude Code has the deepest integration, Codex supports hooks so approvals and notifications work there too, and Antigravity CLI does not support hooks yet, so those panels are unavailable for its sessions.
What is the timeline database?
A single local SQLite file (~/.config/crystl/history.db) where crystl keeps its own searchable index of agent conversations and shell commands. It powers Cmd+Shift+F, crystl history search, and the usage metrics. It's an index, never the source of truth: it's built from your transcripts and can always be rebuilt, and it never leaves your machine.
What are Quest Levels?
Levels give a quest a questline: an ordered set of stages the whole party works through together. Each level has an objective, and the party only advances once every hero checks in: done, blocked (with a reason), or nothing to do. A levels tab tracks the current stage, who you're waiting on, and the whole arc. See the <a href='/docs/quest-levels/'>Quest Levels docs</a>.
What is the CLAUDE.md manager?
crystl lets you store and name different CLAUDE.md starter files. When you open a project, you can insert the right starter file into the directory, useful if you maintain different instruction sets for different types of work.
Can my agent summon hero shards for me?
Yes. With the <a href='/features/cli/'>crystl CLI</a> enabled (a Guild feature), ask your agent to summon specific heroes on specific models and it spawns the shards for you, no panel needed. The exact commands live in the <a href='/docs/cli/'>CLI reference</a>.
What does anointing an orchestrator actually do?
The anoint button (a crown) briefs a shard's agent on the worker protocol and marks it with a castle icon. Workers it spawns wear a dot in the lead's crystal color, so siblings group visually. The chat dock (Cmd+Y) grows a workers tab with a live roster, workers push a report to the lead the moment they finish or get blocked (no polling), and a worker parked on an in-terminal prompt is flagged ⏸ awaiting input in crystl status, and the lead can block on it with crystl wait awaiting|idle.
Does it work over SSH?
Yes. The optimizer reads remote project files through crystl's SSH connection. Health scores, gap detection, and file creation all work on remote machines; plugin recommendations are skipped there since that state lives on your Mac.
How do I know whether a scheduled command worked?
Every command run reports an outcome: succeeded, failed with its exit code, no start seen, or unknown. "Unknown" means the command ran and crystl could not see how it went, so never read it as success. A failed run raises a card naming the command that ran and keeps its shard open so you can read the scrollback.
What happens when a stage finds nothing to do?
It reports crystl stage nothing, which is a success: the run keeps going. That is different from crystl stage blocked, which means the stage needs a person, so the run parks until you deal with it.
Can history be edited or deleted?
The transcripts the navigator reads are read-only; crystl never modifies or deletes them. The timeline index is fully deletable: Settings → Storage shows what's stored per project with scoped clearing (per gem, older-than, or everything), and crystl history clear does the same from the CLI. Clearing the index never touches your conversations, files, or projects. You only lose the ability to search that history in crystl.
Can a levelled quest deadlock if one agent gets stuck?
No. A level clears on check-ins, not successes. A stuck agent reports 'blocked' with a reason and the party still advances. crystl ships built-in questlines, and you can author your own per project in .crystl/questlines/.
Why did my new shard open in a different directory than my last one?
Every shard starts at its gem's project directory. Running cd in one shard only moves that shard; the next shard you create still starts at the gem root, so a project's shards stay predictable no matter where any one of them has wandered. crystl prints a hint in the new shard when this happens. If you do want a shard to start where you are, right-click (or control-click) the shard button. And if you start an agent in a sub-project (a git repo inside your gem), crystl offers to open that folder as its own gem, a suggestion you can always dismiss.
Is it free?
Watching is free on every tier: list sessions, read screens, stream events. The CLI control verbs (spawn a shard, send input, approve, merge) need a Guild membership.
How often should I run it?
After any major project change: new dependencies, restructured directories, or onboarding a new team member. The re-analyze button refreshes instantly, and a brand-new gem offers to run it for you.
Is scheduling free?
Yes. Up to 3 schedules on every tier, agent or command, rotating or not. A rotating schedule counts as one however many payloads it holds. Create, list, and cancel them from the desktop, CLI, or phone. Past three, a Guild membership lifts the cap.
Can different stages use different models?
Yes. Each stage picks its own agent and size, so the expensive parsing stage can run on a standard model while the later stages run on a small one. Sizes map to whatever you taught crystl, including an open model on your own hardware.
Where is history stored?
The transcripts the navigator reads are your agents' own, under ~/.claude on your machine. crystl additionally keeps the timeline index at ~/.config/crystl/history.db, plus per-project bookkeeping in .crystl (session-id map, scrollback snapshots). Everything stays local; nothing is uploaded.
Where did the isolation button go?
Its jobs moved closer to the things they act on. Creating an isolated shard now happens with the isolated-shard button in the shard bar (or the File menu). Merging and rebasing live on each shard's tab: a shard with unmerged commits shows a small ↑N badge you can click, and every action names the branch, target, and commit count so you know exactly what will move. A 'branches' button appears in the shard bar only when orphaned worktree branches exist, listing parked work from closed shards so you can reattach, merge, or discard it.
Are sequences free?
Writing and validating a definition is free on every tier, since it is a file in your own repository, and so is reading the catalog and the record of past runs. Running a sequence, and any schedule, file, or poll trigger that runs one for you, needs a Guild membership.
Is crystl free?
The free plan includes isolated shards & parallel sessions, floating cards, the agent activity panel, split view, history navigator, token tracking, workbench, project optimizer, agent file editor, screenshot & copy bars, MCP servers, API key storage, remote development over SSH, Metal-accelerated GPU rendering, facet inserts, and scheduling, agent or command, up to 3 schedules. The Guild plan ($170/year) adds the Prompt Library integration, formations (with session restore), CLI orchestration, unlimited scheduling, and priority support.
Are sequences finished?
They are an early preview. The shape of a definition file may still change between releases, so treat one you write today as something you may need to adjust later.
Does crystl work on Linux or Windows?
crystl is macOS only. It's a native Swift app and it uses macOS-specific features like the Keychain for secure API key storage.