A CLI your agents can use

guild membership

A built-in `crystl` CLI that puts every part of the GUI on your shell path, and on the path of every agent running inside a crystl shard.

works withany CLI agentclaude codecodexantigravity cli · partialkimi code · partial
$ crystl gems
* sigmacontent      [diamond (Claude)]
  /Users/chris/Nextcloud/sigmacontent
  crystl            [diamond (Claude), opal]
  /Users/chris/Nextcloud/crystl

$ crystl shard create --gem crystl --crystal-name jade --prompt "add tests"
Created jade in crystl
  /Users/chris/Nextcloud/crystl
  $ claude 'add tests'

$ crystl wait pending --timeout 30
Bash (id=42, gem=crystl, shard=jade)

$ crystl approve 42
Decision sent

The crystl CLI ships inside Crystl.app and installs itself. crystl keeps its command linked at /usr/local/bin/crystl, checking on every launch and writing the link silently when it can; when that needs an admin password it may offer to install it instead, on a card you can dismiss for good (with notifications off, the card is skipped and Settings is the way in). Agents in your local shards have the command whether or not it was ever installed. Manual controls live in Settings → general → terminal → CRYSTL CLI. It talks to the running crystl over a loopback HTTP bridge using the bearer token at ~/.crystl-bridge-token; no environment variables to wire up.

Same surface as the GUI, plus a few primitives the GUI can't expose: an SSE event stream (crystl events), no-polling waits for approvals, questions, notifications, awaiting input, and idle agents (crystl wait), and shard creation that an orchestrator agent can call from inside a sibling shard. The surface keeps growing with the app: crystl doctor (diagnostics), resurrect (undo-close), shard rename (label your workers), gauntlet (a release-readiness crew), sidequest (pair two shards in a 1:1 chat, even across gems), hero/party, workbench, and history with per-turn token & model metadata. When you open a project, crystl seeds a reference primer into the gem's agent instruction files so any agent in any shard discovers it can coordinate with the rest of your workspace. It's a real chunk of context, about 11 KB and roughly 130 lines, and you can switch it off in settings.

Why it matters

No install step, every shell

crystl keeps its command linked at /usr/local/bin/crystl, writing it on launch, silently when it can and by offering when it needs a password. Agents in local shards get it either way.

Agents coordinate across shards

crystl gems, shards, screen, send, and shard create let one agent inspect or drive a sibling shard. Orchestrators fan work out and watch it land without leaving the terminal.

Block on real events, not polls

crystl events streams the bridge's SSE log as JSON lines. crystl wait can block on approvals, ask-user prompts, notifications, awaiting-input states, or idle transitions. Ideal for scripts and agent workflows.

Discoverable to agents

On each gem open, crystl keeps a marker-bracketed CLI section in supported agent instruction files. It's idempotent, can seed the file when needed, and can be disabled in Settings → agents → defaults.

Dive deeper in the CLI docs →

Ready to try it?

Create a free account and download crystl for macOS.

get started getting started guide →

Frequently asked questions

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.
Book of Spells
the crystl guild

Crystl's Book of Spells

Master crystl with a grimoire of powerful prompts. Summon heroes, assemble a party, revive shards, and complete epic quests.

open the book →

More features

Gems & Shards

Gems, shards, and the crystal rail keep every project one click away.

Action Panels

See what every agent is doing at a glance.

Agent Activity Panel

One live view of every agent across all your gems: who's working, who's idle, and where tokens are going.

Schedule Agents

Launch a fresh agent at a set time (once, daily, or weekdays). Pick the gem, agent, model, and prompt; crystl fires it on schedule.

Parallel Sessions

Run multiple Claude instances on the same repo in separate git worktrees.

Hero Shards

Summon a single hero as a shard (its own agent, model, and persona) without a quest party.

History Navigator

Browse, jump through, and search every session: conversation and tool calls.

Token Tracking

Track token burn per shard, estimate turns left, and reclaim context window by disabling heavy plugins and skills.

Workbench

A slide-out task list in every project, backed by a WORKBENCH.md the agent reads and writes with you.

Markdown Editor

Render and edit any .md in a side panel. Toggle it from the workbench, and let agents open docs for you from the CLI.

Prompt Integration

Facet Inserts give you one-click access to saved prompts, commands, and shortcuts.

Agent File Editor

Create, edit, and manage CLAUDE.md, rules, skills, and agent config files with a block editor, file chooser, and project optimizer.

Project Optimizer

Scan your project for gaps in agent configuration (missing files, incomplete docs, oversized code, and setup issues) with one-click fixes.

Skills Library

Browse and import agentic skills that teach agents like Claude Code or Codex new tricks: code review, testing, deployment, and more.

Cavrn

The terminal as structured data: every turn, tool call, result, and table captured as agent-readable metadata. Drawn fast on the GPU with Metal.

Remote Development

Full crystl integration over SSH: approval panels, file relay, and click-to-open on remote machines.

Open Models

Run open models locally or hosted, orchestrate them with frontier agents, and cut token costs.

Agent Orchestration

One agent spawns, supervises, and merges the work of many: a control room for a team of coding agents.

crystl quest

Assemble a party of specialized agents. Each brings unique skills, coordinates in shared chat, and executes in parallel.

Screenshot Bar

Drag recent screenshots into the terminal. Spotlight-powered, always up to date.

Copy Bar

A one-click copy bar under the terminal. Agents stage text, you click Copy. Editable, up to 10 tabs, free.