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 'action panels' 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.

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 panels 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.

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.

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.

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.

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.

The free plan includes isolated shards & parallel sessions, action panels, 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, and facet inserts. The Guild plan ($170/year) adds the Prompt Library integration, formations (with session restore), CLI orchestration, agent scheduling, and priority support.

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.

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.

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.

How do I run multiple Claude Code sessions at once?

In crystl, each project is a gem that holds multiple terminal shards — 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.

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.

Do action panels work with Codex?

Not yet. Approval panels and notifications use Claude Code hooks, which Codex doesn't support.

Can I approve actions from a different window?

Yes. Panels are non-activating, so they float on screen without stealing focus.

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.

Can I set different sounds for different panel types?

Yes. Settings > General > Sounds has separate pickers for approval, notification, denied, and question panels.

Do question panels work over SSH?

Yes. All panel types work over SSH when the auto-tunnel is enabled.

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'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.

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.

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.

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 totals 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.

How do I schedule an agent?

Two ways: the Settings → Agents → Schedules panel, or the crystl CLI — crystl schedule add --gem --at "09:00" --every weekdays --prompt "...". Use crystl schedule list to see what's queued and crystl schedule cancel to remove one.

What recurrence options are there?

Once (a one-off at a specific date and time), daily, or weekdays (Monday–Friday). Times are interpreted in the IANA time zone you set, with daylight saving handled for you.

What can I configure per schedule?

The same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, and an optional isolated worktree. You can also give the schedule a name so it's easy to find later.

Listing schedules is free on every tier. Creating and cancelling a schedule is a Guild action, like other commands that change state.

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 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 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.

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.

Does this work over SSH?

Yes. File creation, template writing, rule setup, and the full block editor all work on remote projects over SSH.

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.

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.

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.

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 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.

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.

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 on every request.

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 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.

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 ` sets a direct bridge address for the next SSH connection.

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.

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.

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 — 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.

Can I read history from the command line?

Yes. crystl history prints a shard's transcript (turns and tool calls), with each turn's model, token usage, and duration and a session summary (total tokens, tool calls, models, active time) on top. Handy for an agent to review what happened earlier — or to judge a sibling worker's cost and context. --json emits the full metadata. Claude Code shards only, for now.

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.

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.

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.

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.

How does an agent put text in the copy bar?

Two ways. It runs crystl copy "" with the text inline, or it pipes a command's output into it: | crystl copy. The text appears in the bar under the terminal, ready for you to click Copy.

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.

frequently asked questions

Everything people ask about crystl, gathered from across the site. Jump to a topic, or follow the link on each section to its full feature page.

General

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 'action panels' 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.
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 panels 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.
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.
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.
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.
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.
Is crystl free?: The free plan includes isolated shards & parallel sessions, action panels, 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, and facet inserts. The Guild plan ($170/year) adds the Prompt Library integration, formations (with session restore), CLI orchestration, agent scheduling, and priority support.
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.

Claude Code

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.
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.
How do I run multiple Claude Code sessions at once?: In crystl, each project is a gem that holds multiple terminal shards — 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.
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.

more about claude code →

Action panels

Do action panels work with Codex?: Not yet. Approval panels and notifications use Claude Code hooks, which Codex doesn't support.
Can I approve actions from a different window?: Yes. Panels are non-activating, so they float on screen without stealing focus.
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.
Can I set different sounds for different panel types?: Yes. Settings > General > Sounds has separate pickers for approval, notification, denied, and question panels.
Do question panels work over SSH?: Yes. All panel types work over SSH when the auto-tunnel is enabled.

more about action panels →

Agent activity panel

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'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.
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.
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.
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 totals 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.

more about agent activity panel →

Schedule agents

How do I schedule an agent?: Two ways: the Settings → Agents → Schedules panel, or the crystl CLI — crystl schedule add --gem --at "09:00" --every weekdays --prompt "...". Use crystl schedule list to see what's queued and crystl schedule cancel to remove one.
What recurrence options are there?: Once (a one-off at a specific date and time), daily, or weekdays (Monday–Friday). Times are interpreted in the IANA time zone you set, with daylight saving handled for you.
What can I configure per schedule?: The same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, and an optional isolated worktree. You can also give the schedule a name so it's easy to find later.
Is scheduling free?: Listing schedules is free on every tier. Creating and cancelling a schedule is a Guild action, like other commands that change state.

more about schedule agents →

Agent file editor

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 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 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.
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.
Does this work over SSH?: Yes. File creation, template writing, rule setup, and the full block editor all work on remote projects over SSH.

more about agent file editor →

Cavrn

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.
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.
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.
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 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.

more about cavrn →

crystl CLI

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.
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 on every request.
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 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.
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 ` sets a direct bridge address for the next SSH connection.

more about crystl cli →

History navigator

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.
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.
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 — 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.
Can I read history from the command line?: Yes. crystl history prints a shard's transcript (turns and tool calls), with each turn's model, token usage, and duration and a session summary (total tokens, tool calls, models, active time) on top. Handy for an agent to review what happened earlier — or to judge a sibling worker's cost and context. --json emits the full metadata. Claude Code shards only, for now.
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.
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.
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.
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.

more about history navigator →

copy bar

How does an agent put text in the copy bar?: Two ways. It runs crystl copy "" with the text inline, or it pipes a command's output into it: | crystl copy. The text appears in the bar under the terminal, ready for you to click Copy.
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.
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 "" names the active tab's chip. Tabs only show once there are two or more.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does the copy bar shrink my terminal?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Is the copy bar free?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/copy-bar/" data-astro-cid-6kmwghhu>more about copy bar →</a> </section><section id="crystl-quest" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>crystl quest</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How many agents can be in a quest party?</dt> <dd data-astro-cid-z6gx6xcw>You can summon as many agents as your machine can handle. The default party templates include 4 roles, but you can add more.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can agents message each other directly?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Agents use @mentions to target a specific shard. These appear as DM threads in the quest panel sidebar.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What heroes are in the default catalog?</dt> <dd data-astro-cid-z6gx6xcw>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 — and 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>.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Do I need worktree isolation to use quest?</dt> <dd data-astro-cid-z6gx6xcw>No. Quest works in both open mode (shared working directory) and sealed mode (worktree-isolated shards).</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I save custom party configurations?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Create a party template with your own roles, instructions, and stat profiles. Reuse it across projects.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What are Quest Levels?</dt> <dd data-astro-cid-z6gx6xcw>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>.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can a levelled quest deadlock if one agent gets stuck?</dt> <dd data-astro-cid-z6gx6xcw>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/.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/crystl-quest/" data-astro-cid-6kmwghhu>more about crystl quest →</a> </section><section id="hero-shards" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Hero Shards</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How is a Hero Shard different from a quest?</dt> <dd data-astro-cid-z6gx6xcw>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. Reach for a Hero Shard when you just need one specialist.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How do I launch a Hero Shard?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What does the hero bring to the shard?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can a Hero Shard run isolated?</dt> <dd data-astro-cid-z6gx6xcw>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>.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Where do the heroes come from?</dt> <dd data-astro-cid-z6gx6xcw>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>.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can my agent summon hero shards for me?</dt> <dd data-astro-cid-z6gx6xcw>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>.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/hero-shards/" data-astro-cid-6kmwghhu>more about hero shards →</a> </section><section id="gems-shards" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Gems & shards</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How many projects can I have open at once?</dt> <dd data-astro-cid-z6gx6xcw>As many as you like, on every plan including the free one. You're limited only by what your machine can comfortably run.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I rearrange gems in the Crystal Rail?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Drag gems to reorder them, and the Rail remembers your layout between sessions.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens to my shards when I close a gem?</dt> <dd data-astro-cid-z6gx6xcw>Claude 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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can two gems point to the same directory?</dt> <dd data-astro-cid-z6gx6xcw>Yes. This can be useful for separate workspaces with different shard configurations for the same project.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does crystl only work with Claude Code?</dt> <dd data-astro-cid-z6gx6xcw>crystl is built around Claude Code, but it also has early support for OpenAI Codex. Features like approval panels rely on hooks that Claude Code provides.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/multitasking/" data-astro-cid-6kmwghhu>more about gems & shards →</a> </section><section id="agent-orchestration" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Agent orchestration</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>If the tool already starts the agents, what's hard about running many?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How do I know which agent needs me?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I run different models from different companies at once?</dt> <dd data-astro-cid-z6gx6xcw>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 panels via hooks) is Claude Code-first, Codex partial, others at terminal level — but every agent shows on the rail, and crystl flags any of them the moment it's blocked.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens if I restart or my machine reboots?</dt> <dd data-astro-cid-z6gx6xcw>Claude 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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can the agents coordinate with each other?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What does anointing an orchestrator actually do?</dt> <dd data-astro-cid-z6gx6xcw>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 — the lead can block on it with crystl wait awaiting|idle.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Is it free?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/orchestration/" data-astro-cid-6kmwghhu>more about agent orchestration →</a> </section><section id="parallel-sessions" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Parallel sessions</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How many isolated shards can I run at once?</dt> <dd data-astro-cid-z6gx6xcw>As many as you like, on every plan including the free one. Run as many parallel sessions as your machine can handle.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Do isolated shards work with any git repo?</dt> <dd data-astro-cid-z6gx6xcw>Yes. They use standard git worktrees, so any git repository works.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens if two agents edit the same file?</dt> <dd data-astro-cid-z6gx6xcw>They can't. Each isolated shard works on its own branch in its own worktree.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What if my project needs a custom setup step?</dt> <dd data-astro-cid-z6gx6xcw>Add a setupCommand to .crystl/project.json. crystl runs it after dependency installation.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens to a shard's branch after merging?</dt> <dd data-astro-cid-z6gx6xcw>crystl cleans up the worktree and branch automatically after a successful merge.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/parallel-sessions/" data-astro-cid-6kmwghhu>more about parallel sessions →</a> </section><section id="project-optimizer" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Project optimizer</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What does the optimizer check?</dt> <dd data-astro-cid-z6gx6xcw>35+ signals across six categories: file presence (CLAUDE.md, .claudeignore, etc.), content quality (Build & Run section, architecture docs, file size limits), code organization (files over 500 or 1000 lines), project setup (skills, rules, MCP servers, hooks), cross-file consistency (stale paths, config conflicts), and stack-specific recommendations.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How does the scoring work?</dt> <dd data-astro-cid-z6gx6xcw>Each gap subtracts points from a base score of 100, weighted by severity. Content is weighted 3x, files and code 2x, and setup 1x. The result is classified as high (75+), medium (40-74), or low (below 40).</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What can I fix directly from the optimizer?</dt> <dd data-astro-cid-z6gx6xcw>Most gaps have a one-click action: create a missing file, add a section to CLAUDE.md, or open a file in the block editor. For everything else, the export button generates a report you can hand to Claude Code.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does it work with monorepos?</dt> <dd data-astro-cid-z6gx6xcw>Yes. The optimizer detects subpackages and checks for CLAUDE.md files in each one. It also checks for path-scoped rules in .claude/rules/.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does it work over SSH?</dt> <dd data-astro-cid-z6gx6xcw>Yes. The optimizer reads remote project files through crystl's SSH connection. Health scores, gap detection, and file creation all work on remote machines.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How often should I run it?</dt> <dd data-astro-cid-z6gx6xcw>After any major project change: new dependencies, restructured directories, or onboarding a new team member. The re-analyze button refreshes instantly.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/project-optimizer/" data-astro-cid-6kmwghhu>more about project optimizer →</a> </section><section id="prompt-integration" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Prompt integration</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How many facet inserts can I have?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I share facets between projects?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Facets are global, so they appear in every gem and shard.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What's the difference between a prompt and a command?</dt> <dd data-astro-cid-z6gx6xcw>Prompts send text to Claude's input. Commands execute directly in the shell. Shortcuts trigger crystl actions.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I import facets from the Prompt Library?</dt> <dd data-astro-cid-z6gx6xcw>Yes. The library has 200+ inserts organized by category. Click to import any of them.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How do I configure which facets appear?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/prompt-integration/" data-astro-cid-6kmwghhu>more about prompt integration →</a> </section><section id="remote-development" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Remote development</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Do I need to install anything on the remote?</dt> <dd data-astro-cid-z6gx6xcw>No. When auto-tunnel is enabled, crystl installs hooks on the remote automatically via SSH RemoteCommand.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does file relay work without the auto-tunnel?</dt> <dd data-astro-cid-z6gx6xcw>File relay requires the SSH ControlMaster socket, which the auto-tunnel sets up.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Do approval panels appear locally?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Claude on the remote posts to localhost:19280, which the SSH tunnel redirects to your Mac.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I use the tunnel with multiple remotes at once?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Each SSH session gets its own ControlMaster socket. crystl tracks them independently.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What if port 19280 is already in use on the remote?</dt> <dd data-astro-cid-z6gx6xcw>The first tunnel binds the port. Subsequent connections see 'address already in use' but this is harmless.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/remote-development/" data-astro-cid-6kmwghhu>more about remote development →</a> </section><section id="screenshot-bar" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>screenshot bar</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does it only find screenshots on my Desktop?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How many screenshots does it show?</dt> <dd data-astro-cid-z6gx6xcw>Up to 30 of your most recent screenshots, sorted newest first. The bar is horizontally scrollable, so you can scroll back through older captures.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens when I drag a thumbnail into the terminal?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I keep the bar visible permanently?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does the bar update in real time?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/screenshot-bar/" data-astro-cid-6kmwghhu>more about screenshot bar →</a> </section><section id="skills-library" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Skills library</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What is a skill?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Can I create my own skills?</dt> <dd data-astro-cid-z6gx6xcw>Yes. Add any .md file to your starters with a path like .claude/commands/my-skill.md. It works just like library skills.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Are skills project-specific?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Do I need Guild for skills?</dt> <dd data-astro-cid-z6gx6xcw>You can create and use your own skills for free. The Skills Library catalog requires a Guild membership to browse and import.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/skills-library/" data-astro-cid-6kmwghhu>more about skills library →</a> </section><section id="token-tracking" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>token tracking</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>When does the turns-left estimate appear?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How is the estimate calculated?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens when I disable a plugin or skill?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What does the panel track per turn?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does this work with Codex?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/token-tracking/" data-astro-cid-6kmwghhu>more about token tracking →</a> </section><section id="workbench" class="faq-group" data-astro-cid-6kmwghhu> <section class="faq" data-astro-cid-z6gx6xcw> <h2 data-astro-cid-z6gx6xcw>Workbench</h2> <dl class="faq-list" data-astro-cid-z6gx6xcw> <div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Where is the workbench stored?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>How does the agent see it?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does the drawer update when the agent edits the file?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>What happens to lines the drawer doesn't understand?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div><div class="faq-item" data-astro-cid-z6gx6xcw> <dt data-astro-cid-z6gx6xcw>Does it work with Codex and Antigravity CLI?</dt> <dd data-astro-cid-z6gx6xcw>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.</dd> </div> </dl> </section> <a class="faq-group-link" href="/features/workbench/" data-astro-cid-6kmwghhu>more about workbench →</a> </section> </article> </main> <footer class="glass-footer" data-astro-cid-5hce7sga> <div class="footer-grid" data-astro-cid-5hce7sga> <div class="footer-col" data-astro-cid-5hce7sga> <span class="footer-heading" data-astro-cid-5hce7sga>features</span> <a href="/features/multitasking/" data-astro-cid-5hce7sga>gems & shards</a> <a href="/features/orchestration/" data-astro-cid-5hce7sga>agent orchestration</a> <a href="/features/parallel-sessions/" data-astro-cid-5hce7sga>parallel sessions</a> <a href="/features/crystl-quest/" data-astro-cid-5hce7sga>crystl quest</a> <a href="/features/hero-shards/" data-astro-cid-5hce7sga>hero shards</a> <a href="/features/schedule-agents/" data-astro-cid-5hce7sga>schedule agents</a> <a href="/features/action-panels/" data-astro-cid-5hce7sga>action panels</a> <a href="/features/agent-activity-panel/" data-astro-cid-5hce7sga>agent activity panel</a> <a href="/features/conversation-history/" data-astro-cid-5hce7sga>history navigator</a> <a href="/features/workbench/" data-astro-cid-5hce7sga>workbench</a> <a href="/features/markdown-editor/" data-astro-cid-5hce7sga>markdown editor</a> <a href="/features/prompt-integration/" data-astro-cid-5hce7sga>facet inserts</a> <a href="/features/remote-development/" data-astro-cid-5hce7sga>remote development</a> <a href="/features/mobile/" data-astro-cid-5hce7sga>crystl on iphone</a> </div> <div class="footer-col" data-astro-cid-5hce7sga> <span class="footer-heading" data-astro-cid-5hce7sga>resources</span> <a href="/docs/" data-astro-cid-5hce7sga>docs</a> <a href="/guides/" data-astro-cid-5hce7sga>guides</a> <a href="/library/" data-astro-cid-5hce7sga>library</a> <a href="/blog/" data-astro-cid-5hce7sga>blog</a> <a href="/changelog/" data-astro-cid-5hce7sga>changelog</a> <a href="/faq/" data-astro-cid-5hce7sga>faq</a> <a href="/multitasking-terminal-for-claude-code/" data-astro-cid-5hce7sga>for claude code</a> <a href="/multitasking-terminal-for-codex/" data-astro-cid-5hce7sga>for codex</a> <a href="/multitasking-terminal-for-antigravity-cli/" data-astro-cid-5hce7sga>for antigravity cli</a> </div> <div class="footer-col" data-astro-cid-5hce7sga> <span class="footer-heading" data-astro-cid-5hce7sga>company</span> <a href="/about/" data-astro-cid-5hce7sga>about</a> <a href="/pricing/" data-astro-cid-5hce7sga>pricing</a> <a href="/press/" data-astro-cid-5hce7sga>press</a> <a href="/affiliates/" data-astro-cid-5hce7sga>refer & earn</a> <a href="/login/" id="footer-sign-in" data-astro-cid-5hce7sga>sign in</a> <a href="/dashboard/" id="footer-account" style="display:none;" data-astro-cid-5hce7sga>dashboard</a> </div> <div class="footer-col" data-astro-cid-5hce7sga> <span class="footer-heading" data-astro-cid-5hce7sga>support</span> <a href="/contact/" data-astro-cid-5hce7sga>contact</a> <a href="/bug-report/" data-astro-cid-5hce7sga>report a bug</a> <a href="/community/" data-astro-cid-5hce7sga>join us on slack</a> <div class="footer-atlas" data-astro-cid-5hce7sga> <a href="https://theindieatlas.com/" target="_blank" rel="noopener noreferrer" class="footer-atlas-link" aria-label="The Indie Atlas" data-astro-cid-5hce7sga> <img src="/indie-atlas-logo.png" alt="The Indie Atlas" width="400" height="160" loading="lazy" data-astro-cid-5hce7sga> </a> <p class="footer-atlas-text" data-astro-cid-5hce7sga>discover indie software or list your indie project. <a href="https://theindieatlas.com/" target="_blank" rel="noopener noreferrer" data-astro-cid-5hce7sga>explore.</a></p> </div> </div> </div> <div class="footer-bottom" data-astro-cid-5hce7sga> <div class="footer-legal" data-astro-cid-5hce7sga> <a href="/privacy/" data-astro-cid-5hce7sga>privacy policy</a> <span class="footer-dot" data-astro-cid-5hce7sga>·</span> <a href="/terms/" data-astro-cid-5hce7sga>terms & conditions</a> <span class="footer-dot" data-astro-cid-5hce7sga>·</span> <a href="/acknowledgments/" data-astro-cid-5hce7sga>acknowledgments</a> <span class="footer-dot" data-astro-cid-5hce7sga>·</span> <button type="button" class="footer-cookie-btn" onclick="window.klaro && window.klaro.show()" data-astro-cid-5hce7sga>cookie preferences</button> </div> <div class="footer-badge" data-astro-cid-5hce7sga> <a href="https://tools.launchllama.co?utm_source=badge&utm_medium=referral" target="_blank" rel="noopener noreferrer" data-astro-cid-5hce7sga> <img src="https://speaktechenglish.com/wp-content/uploads/2026/04/Screenshot_2026-04-09_at_17.40.44-removebg-preview.png" alt="Featured on Launch Llama" width="200" height="50" loading="lazy" data-astro-cid-5hce7sga> </a> </div> <p data-astro-cid-5hce7sga>© 2026 crystl.</p> </div> </footer> <div id="search-overlay" class="search-overlay" hidden data-astro-cid-xao2j2xx> <div class="search-backdrop" id="search-backdrop" data-astro-cid-xao2j2xx></div> <div class="search-modal glass" role="dialog" aria-modal="true" aria-label="Search the site" data-astro-cid-xao2j2xx> <div class="search-input-row" data-astro-cid-xao2j2xx> <svg class="search-icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" data-astro-cid-xao2j2xx><circle cx="11" cy="11" r="8" data-astro-cid-xao2j2xx></circle><path d="m21 21-4.3-4.3" data-astro-cid-xao2j2xx></path></svg> <input id="search-input" class="search-input" type="text" placeholder="Search docs, guides, skills, prompts…" autocomplete="off" autocapitalize="off" spellcheck="false" aria-label="Search query" aria-controls="search-results" data-astro-cid-xao2j2xx> <kbd class="search-esc" data-astro-cid-xao2j2xx>esc</kbd> </div> <div class="search-results" id="search-results" role="listbox" aria-label="Search results" data-astro-cid-xao2j2xx></div> <div class="search-footer" data-astro-cid-xao2j2xx> <span data-astro-cid-xao2j2xx><kbd data-astro-cid-xao2j2xx>↑</kbd><kbd data-astro-cid-xao2j2xx>↓</kbd> navigate</span> <span data-astro-cid-xao2j2xx><kbd data-astro-cid-xao2j2xx>↵</kbd> open</span> <span data-astro-cid-xao2j2xx><kbd data-astro-cid-xao2j2xx>esc</kbd> close</span> </div> </div> </div> <script type="module" src="/_astro/SearchPalette.astro_astro_type_script_index_0_lang.BTReRcVk.js"></script>  <script> (function () { function reveal(el) { el.classList.add('is-visible'); el.addEventListener('animationend', function () { el.style.willChange = 'auto'; }, { once: true }); } function els() { return document.querySelectorAll('.reveal-up:not(.is-visible)'); } if (!('IntersectionObserver' in window)) { els().forEach(reveal); return; } var io = new IntersectionObserver(function (entries) { var i = 0; entries.forEach(function (e) { if (e.isIntersecting) { e.target.style.animationDelay = (i * 90) + 'ms'; reveal(e.target); io.unobserve(e.target); i++; } }); }, { threshold: 0.1, rootMargin: '0px 0px -120px 0px' }); function init() { els().forEach(function (el) { io.observe(el); }); } if (document.readyState !== 'loading') init(); else document.addEventListener('DOMContentLoaded', init); })(); </script> </body> </html> <script type="application/ld+json">{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"What is a multitasking terminal for AI agents?","acceptedAnswer":{"@type":"Answer","text":"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 'action panels' 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."}},{"@type":"Question","name":"Does crystl only work with Claude Code?","acceptedAnswer":{"@type":"Answer","text":"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 panels 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."}},{"@type":"Question","name":"Can I use crystl for regular terminal work?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What is the CLAUDE.md manager?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Why did my new shard open in a different directory than my last one?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Where did the isolation button go?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Is crystl free?","acceptedAnswer":{"@type":"Answer","text":"The free plan includes isolated shards & parallel sessions, action panels, 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, and facet inserts. The Guild plan ($170/year) adds the Prompt Library integration, formations (with session restore), CLI orchestration, agent scheduling, and priority support."}},{"@type":"Question","name":"Does crystl work on Linux or Windows?","acceptedAnswer":{"@type":"Answer","text":"crystl is macOS only. It's a native Swift app and it uses macOS-specific features like the Keychain for secure API key storage."}},{"@type":"Question","name":"What's the best terminal for Claude Code?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I use crystl instead of tmux to run Claude Code?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How do I run multiple Claude Code sessions at once?","acceptedAnswer":{"@type":"Answer","text":"In crystl, each project is a gem that holds multiple terminal shards — 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."}},{"@type":"Question","name":"How do I keep track of multiple Claude Code agents?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Do action panels work with Codex?","acceptedAnswer":{"@type":"Answer","text":"Not yet. Approval panels and notifications use Claude Code hooks, which Codex doesn't support."}},{"@type":"Question","name":"Can I approve actions from a different window?","acceptedAnswer":{"@type":"Answer","text":"Yes. Panels are non-activating, so they float on screen without stealing focus."}},{"@type":"Question","name":"What's the difference between Smart and Auto mode?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I set different sounds for different panel types?","acceptedAnswer":{"@type":"Answer","text":"Yes. Settings > General > Sounds has separate pickers for approval, notification, denied, and question panels."}},{"@type":"Question","name":"Do question panels work over SSH?","acceptedAnswer":{"@type":"Answer","text":"Yes. All panel types work over SSH when the auto-tunnel is enabled."}},{"@type":"Question","name":"How do I open the Agent Activity Panel?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What's the difference between the all-gems and per-gem views?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does it work with agents other than Claude Code?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How does it know an agent is idle versus working?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Where do the token numbers come from?","acceptedAnswer":{"@type":"Answer","text":"Each row shows the shard's context load, output, and estimated turns left from its transcript, and the footer totals 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."}},{"@type":"Question","name":"How do I schedule an agent?","acceptedAnswer":{"@type":"Answer","text":"Two ways: the Settings → Agents → Schedules panel, or the crystl CLI — crystl schedule add --gem --at \"09:00\" --every weekdays --prompt \"...\". Use crystl schedule list to see what's queued and crystl schedule cancel to remove one."}},{"@type":"Question","name":"What recurrence options are there?","acceptedAnswer":{"@type":"Answer","text":"Once (a one-off at a specific date and time), daily, or weekdays (Monday–Friday). Times are interpreted in the IANA time zone you set, with daylight saving handled for you."}},{"@type":"Question","name":"What can I configure per schedule?","acceptedAnswer":{"@type":"Answer","text":"The same choices as launching a shard by hand: target gem, task prompt, agent (Claude, Codex, and others), model, approval mode, and an optional isolated worktree. You can also give the schedule a name so it's easy to find later."}},{"@type":"Question","name":"Is scheduling free?","acceptedAnswer":{"@type":"Answer","text":"Listing schedules is free on every tier. Creating and cancelling a schedule is a Guild action, like other commands that change state."}},{"@type":"Question","name":"What file types can I create?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What is the block editor?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What are Claude Rules?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What does the line count indicator do?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does this work over SSH?","acceptedAnswer":{"@type":"Answer","text":"Yes. File creation, template writing, rule setup, and the full block editor all work on remote projects over SSH."}},{"@type":"Question","name":"What makes Cavrn different from a normal terminal?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What can read the metadata?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Is the Metal GPU rendering the main feature?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Do I have to turn it on?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does it work with any agent?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Where does the binary live?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does the CLI need a separate auth setup?","acceptedAnswer":{"@type":"Answer","text":"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 on every request."}},{"@type":"Question","name":"Can I drive the bridge directly from curl or another language?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does the agent snippet edit my instruction files every time?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does it work over SSH?","acceptedAnswer":{"@type":"Answer","text":"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 ` sets a direct bridge address for the next SSH connection."}},{"@type":"Question","name":"Can I search through past sessions?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does it include tool calls?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does it work with Codex or Antigravity CLI?","acceptedAnswer":{"@type":"Answer","text":"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 — 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."}},{"@type":"Question","name":"Can I read history from the command line?","acceptedAnswer":{"@type":"Answer","text":"Yes. crystl history prints a shard's transcript (turns and tool calls), with each turn's model, token usage, and duration and a session summary (total tokens, tool calls, models, active time) on top. Handy for an agent to review what happened earlier — or to judge a sibling worker's cost and context. --json emits the full metadata. Claude Code shards only, for now."}},{"@type":"Question","name":"Does it work for remote sessions?","acceptedAnswer":{"@type":"Answer","text":"Yes. A remote (SSH) shard's transcript is fetched over the existing connection and read with the same navigator and CLI."}},{"@type":"Question","name":"What is the timeline database?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can history be edited or deleted?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Where is history stored?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How does an agent put text in the copy bar?","acceptedAnswer":{"@type":"Answer","text":"Two ways. It runs crystl copy \"\" with the text inline, or it pipes a command's output into it: | crystl copy. The text appears in the bar under the terminal, ready for you to click Copy."}},{"@type":"Question","name":"Can I change the text before copying it?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What are the tabs for?","acceptedAnswer":{"@type":"Answer","text":"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 \"\" names the active tab's chip. Tabs only show once there are two or more."}},{"@type":"Question","name":"Does the copy bar shrink my terminal?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Is the copy bar free?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How many agents can be in a quest party?","acceptedAnswer":{"@type":"Answer","text":"You can summon as many agents as your machine can handle. The default party templates include 4 roles, but you can add more."}},{"@type":"Question","name":"Can agents message each other directly?","acceptedAnswer":{"@type":"Answer","text":"Yes. Agents use @mentions to target a specific shard. These appear as DM threads in the quest panel sidebar."}},{"@type":"Question","name":"What heroes are in the default catalog?","acceptedAnswer":{"@type":"Answer","text":"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 — and 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. Browse all heroes in the Library."}},{"@type":"Question","name":"Do I need worktree isolation to use quest?","acceptedAnswer":{"@type":"Answer","text":"No. Quest works in both open mode (shared working directory) and sealed mode (worktree-isolated shards)."}},{"@type":"Question","name":"Can I save custom party configurations?","acceptedAnswer":{"@type":"Answer","text":"Yes. Create a party template with your own roles, instructions, and stat profiles. Reuse it across projects."}},{"@type":"Question","name":"What are Quest Levels?","acceptedAnswer":{"@type":"Answer","text":"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 Quest Levels docs."}},{"@type":"Question","name":"Can a levelled quest deadlock if one agent gets stuck?","acceptedAnswer":{"@type":"Answer","text":"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/."}},{"@type":"Question","name":"How is a Hero Shard different from a quest?","acceptedAnswer":{"@type":"Answer","text":"A Quest 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. Reach for a Hero Shard when you just need one specialist."}},{"@type":"Question","name":"How do I launch a Hero Shard?","acceptedAnswer":{"@type":"Answer","text":"In any gem, click the summon-a-hero button next to the shard + in the shard bar. Pick a hero from the grid and it opens as a new shard."}},{"@type":"Question","name":"What does the hero bring to the shard?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can a Hero Shard run isolated?","acceptedAnswer":{"@type":"Answer","text":"Yes. Toggle isolated (own git worktree) when you summon, and the hero gets its own worktree and branch — the same isolation as any isolated shard."}},{"@type":"Question","name":"Where do the heroes come from?","acceptedAnswer":{"@type":"Answer","text":"Your hero roster — the same one quest uses — plus any local project heroes defined in .crystl/heroes/. Browse the hero catalog in the Library."}},{"@type":"Question","name":"Can my agent summon hero shards for me?","acceptedAnswer":{"@type":"Answer","text":"Yes. With the crystl CLI 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 CLI reference."}},{"@type":"Question","name":"How many projects can I have open at once?","acceptedAnswer":{"@type":"Answer","text":"As many as you like, on every plan including the free one. You're limited only by what your machine can comfortably run."}},{"@type":"Question","name":"Can I rearrange gems in the Crystal Rail?","acceptedAnswer":{"@type":"Answer","text":"Yes. Drag gems to reorder them, and the Rail remembers your layout between sessions."}},{"@type":"Question","name":"What happens to my shards when I close a gem?","acceptedAnswer":{"@type":"Answer","text":"Claude 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."}},{"@type":"Question","name":"Can two gems point to the same directory?","acceptedAnswer":{"@type":"Answer","text":"Yes. This can be useful for separate workspaces with different shard configurations for the same project."}},{"@type":"Question","name":"Does crystl only work with Claude Code?","acceptedAnswer":{"@type":"Answer","text":"crystl is built around Claude Code, but it also has early support for OpenAI Codex. Features like approval panels rely on hooks that Claude Code provides."}},{"@type":"Question","name":"If the tool already starts the agents, what's hard about running many?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How do I know which agent needs me?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I run different models from different companies at once?","acceptedAnswer":{"@type":"Answer","text":"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 panels via hooks) is Claude Code-first, Codex partial, others at terminal level — but every agent shows on the rail, and crystl flags any of them the moment it's blocked."}},{"@type":"Question","name":"What happens if I restart or my machine reboots?","acceptedAnswer":{"@type":"Answer","text":"Claude 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."}},{"@type":"Question","name":"Can the agents coordinate with each other?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What does anointing an orchestrator actually do?","acceptedAnswer":{"@type":"Answer","text":"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 — the lead can block on it with crystl wait awaiting|idle."}},{"@type":"Question","name":"Is it free?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How many isolated shards can I run at once?","acceptedAnswer":{"@type":"Answer","text":"As many as you like, on every plan including the free one. Run as many parallel sessions as your machine can handle."}},{"@type":"Question","name":"Do isolated shards work with any git repo?","acceptedAnswer":{"@type":"Answer","text":"Yes. They use standard git worktrees, so any git repository works."}},{"@type":"Question","name":"What happens if two agents edit the same file?","acceptedAnswer":{"@type":"Answer","text":"They can't. Each isolated shard works on its own branch in its own worktree."}},{"@type":"Question","name":"What if my project needs a custom setup step?","acceptedAnswer":{"@type":"Answer","text":"Add a setupCommand to .crystl/project.json. crystl runs it after dependency installation."}},{"@type":"Question","name":"What happens to a shard's branch after merging?","acceptedAnswer":{"@type":"Answer","text":"crystl cleans up the worktree and branch automatically after a successful merge."}},{"@type":"Question","name":"What does the optimizer check?","acceptedAnswer":{"@type":"Answer","text":"35+ signals across six categories: file presence (CLAUDE.md, .claudeignore, etc.), content quality (Build & Run section, architecture docs, file size limits), code organization (files over 500 or 1000 lines), project setup (skills, rules, MCP servers, hooks), cross-file consistency (stale paths, config conflicts), and stack-specific recommendations."}},{"@type":"Question","name":"How does the scoring work?","acceptedAnswer":{"@type":"Answer","text":"Each gap subtracts points from a base score of 100, weighted by severity. Content is weighted 3x, files and code 2x, and setup 1x. The result is classified as high (75+), medium (40-74), or low (below 40)."}},{"@type":"Question","name":"What can I fix directly from the optimizer?","acceptedAnswer":{"@type":"Answer","text":"Most gaps have a one-click action: create a missing file, add a section to CLAUDE.md, or open a file in the block editor. For everything else, the export button generates a report you can hand to Claude Code."}},{"@type":"Question","name":"Does it work with monorepos?","acceptedAnswer":{"@type":"Answer","text":"Yes. The optimizer detects subpackages and checks for CLAUDE.md files in each one. It also checks for path-scoped rules in .claude/rules/."}},{"@type":"Question","name":"Does it work over SSH?","acceptedAnswer":{"@type":"Answer","text":"Yes. The optimizer reads remote project files through crystl's SSH connection. Health scores, gap detection, and file creation all work on remote machines."}},{"@type":"Question","name":"How often should I run it?","acceptedAnswer":{"@type":"Answer","text":"After any major project change: new dependencies, restructured directories, or onboarding a new team member. The re-analyze button refreshes instantly."}},{"@type":"Question","name":"How many facet inserts can I have?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I share facets between projects?","acceptedAnswer":{"@type":"Answer","text":"Yes. Facets are global, so they appear in every gem and shard."}},{"@type":"Question","name":"What's the difference between a prompt and a command?","acceptedAnswer":{"@type":"Answer","text":"Prompts send text to Claude's input. Commands execute directly in the shell. Shortcuts trigger crystl actions."}},{"@type":"Question","name":"Can I import facets from the Prompt Library?","acceptedAnswer":{"@type":"Answer","text":"Yes. The library has 200+ inserts organized by category. Click to import any of them."}},{"@type":"Question","name":"How do I configure which facets appear?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Do I need to install anything on the remote?","acceptedAnswer":{"@type":"Answer","text":"No. When auto-tunnel is enabled, crystl installs hooks on the remote automatically via SSH RemoteCommand."}},{"@type":"Question","name":"Does file relay work without the auto-tunnel?","acceptedAnswer":{"@type":"Answer","text":"File relay requires the SSH ControlMaster socket, which the auto-tunnel sets up."}},{"@type":"Question","name":"Do approval panels appear locally?","acceptedAnswer":{"@type":"Answer","text":"Yes. Claude on the remote posts to localhost:19280, which the SSH tunnel redirects to your Mac."}},{"@type":"Question","name":"Can I use the tunnel with multiple remotes at once?","acceptedAnswer":{"@type":"Answer","text":"Yes. Each SSH session gets its own ControlMaster socket. crystl tracks them independently."}},{"@type":"Question","name":"What if port 19280 is already in use on the remote?","acceptedAnswer":{"@type":"Answer","text":"The first tunnel binds the port. Subsequent connections see 'address already in use' but this is harmless."}},{"@type":"Question","name":"Does it only find screenshots on my Desktop?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How many screenshots does it show?","acceptedAnswer":{"@type":"Answer","text":"Up to 30 of your most recent screenshots, sorted newest first. The bar is horizontally scrollable, so you can scroll back through older captures."}},{"@type":"Question","name":"What happens when I drag a thumbnail into the terminal?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I keep the bar visible permanently?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does the bar update in real time?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What is a skill?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Can I create my own skills?","acceptedAnswer":{"@type":"Answer","text":"Yes. Add any .md file to your starters with a path like .claude/commands/my-skill.md. It works just like library skills."}},{"@type":"Question","name":"Are skills project-specific?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Do I need Guild for skills?","acceptedAnswer":{"@type":"Answer","text":"You can create and use your own skills for free. The Skills Library catalog requires a Guild membership to browse and import."}},{"@type":"Question","name":"When does the turns-left estimate appear?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How is the estimate calculated?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What happens when I disable a plugin or skill?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What does the panel track per turn?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does this work with Codex?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Where is the workbench stored?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"How does the agent see it?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does the drawer update when the agent edits the file?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"What happens to lines the drawer doesn't understand?","acceptedAnswer":{"@type":"Answer","text":"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."}},{"@type":"Question","name":"Does it work with Codex and Antigravity CLI?","acceptedAnswer":{"@type":"Answer","text":"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."}}]}</script>