Getting Started

Updated September 20, 2026

Creating a gem simply adds a project folder to your chosen project directory. Use the folder icon to open an existing project and assign it an icon and color.

Install crystl

Sign in at crystl.dev and download the latest version from your account page. Open the downloaded .dmg and drag crystl to your Applications folder.

Launch crystl from your Applications folder or Spotlight. crystl works on the free plan right away, no license key required.

Create your first gem

A gem is a project workspace in crystl. Each gem maps to a directory on your machine and holds one or more terminal sessions called shards.

Open a project you already have

This is the usual starting point, and the shortest route.

  1. Open crystl
  2. Click the folder icon at the bottom of the gem sidebar
  3. Pick your project directory. It starts where your projects already live: your default gems directory if that folder exists, otherwise the first of ~/Projects, ~/Developer, ~/dev, ~/code, ~/src, ~/repos, ~/work that’s actually there, otherwise your home folder. The open button says what it will do, so open here takes the folder you’re browsing, open selected takes the highlighted one, and go up goes to the parent.
  4. Your first shard opens automatically, and you’re ready to go

Start a project from scratch

For a project whose folder doesn’t exist yet:

  1. Click + at the bottom of the gem sidebar. This opens the New Gem panel directly — no extra click needed.
  2. Give the gem a name: this becomes the folder name.
  3. The path field is the parent directory, not the project folder itself. It defaults to ~/Projects, so a gem named my-app is created at ~/Projects/my-app. Edit the field to put it somewhere else.
  4. Pick a project type — Code, Research, Content, Records, Personal, Orchestration, or General. It decides which starter kits and optimizer checks fit the gem. Not sure yet? Leave it and crystl offers to set it for you once the gem is open; either way it’s changeable any time from gem settings.
  5. Optionally pick an icon and color. Initialize git repository is off by default; turn it on only if the new folder should be its own repository.
  6. Hit Create

If the folder you picked sits inside a bigger git repository, crystl warns you at this point. Use shared shards is the default and leaves the folder in the parent repository. Make standalone repo opts into separate Git history so the gem can use isolated shards. Either button creates the gem.

There’s no folder browser in this panel on purpose: it creates a new directory rather than picking an existing one, so you type where it goes.

You can change the default parent directory in settings, general > gems, under DEFAULT GEMS DIRECTORY.

The command line tool installs itself

crystl bundles a crystl CLI that lets you control gems, shards, and approvals from any shell, and it puts itself on your PATH on launch. Two things:

  • Agents in your local shards always have it, whether or not it’s installed. Nothing to do here.
  • Terminals outside crystl need the symlink at /usr/local/bin/crystl. crystl writes it silently when it can. When that needs your admin password, crystl may offer to install it instead: a small card, one time, that you can dismiss for good. With notifications turned off the card never appears, so use Settings.

The manual controls are in settings, general > terminal, under CRYSTL CLI: current status, one button that matches the situation (install, uninstall, repair, or how to fix when something else owns that path, which explains rather than installing over it), and a link to the docs. Help → install command line tool… does the same thing. See crystl CLI for the full story and the command reference.

Set up CLAUDE.md

Open the gem menu (click the ⋮ on the gem’s tab) and choose settings, then open the agents tab. Under Agent Files, choose edit to create or edit CLAUDE.md, AGENTS.md, and the other instruction files for this gem. Use settings, context to manage reusable files and starter bundles for new gems.

Set up an agent

crystl runs your agent, it does not replace it, so you install the agent yourself and crystl manages it from there. Each page below covers installing it, signing in, launching it in a shard, and what crystl can and cannot do with that particular agent:

  • Claude Code: the most complete integration, and the one crystl was built around first.
  • Codex: fully integrated, and the only agent whose own launch flags follow your auto-approval mode.
  • Antigravity CLI: fully integrated, with one exception worth knowing before you leave one running: its approvals stay in its own terminal.
  • Kimi Code: partial. Approval cards work; no turn-end reporting, history, or resume.

Those four are the tested integrations rather than a closed list. crystl recognises several other agents in the process tree, and a shard is a terminal, so anything you can type runs.

Once one is installed, start it inside any shard by typing its command:

claude

crystl detects the agent’s process and starts managing its permission approvals through floating glass panels, so you can allow or deny each tool call without leaving your terminal.

Ask your agent about crystl

Your agent can run the crystl command, and crystl puts a reference to it in each gem’s instruction files, so a fresh agent already knows the commands exist.

The useful part on day one is that the whole documentation set is in the terminal, free on every tier. Rather than reading a page about a feature, ask the agent already sitting in front of you:

“what does crystl’s in gem approval mode allow? check crystl docs.”

“is anything waiting on me right now?”

It can also report on your workspace (crystl status, crystl shards --all), hand you things through the copy bar, and, with a Guild membership, open gems and spawn workers for you. See your agent can drive crystl.

Find your way around

Four things worth knowing on day one. The full list is longer, but these are the ones you will use every hour.
Cmd + Ctrl + T New shard. A second session in the same project, so one agent can work while you keep a terminal free.
Cmd + D Split the view so you can watch both at once. Cmd + Opt + ← and → move between panes.
Cmd + K Clear the screen and scrollback. Also frees that shard’s memory after a noisy build.
Cmd + Shift + F Search everything you have ever done.

That last one is the one people are most surprised by. Agent turns and shell commands go into a searchable history that outlives the scrollback, so clearing a shard, or even closing it, does not lose what was said. Results span open and closed shards.

The shortcut scheme is consistent once you see it: Cmd acts on gems, Cmd + Ctrl acts on shards.

Choose an auto-approval mode

crystl has three auto-approval modes. Pick the one that fits your workflow:

  • off: review and approve every tool call
  • in gem: reads anything, makes changes only inside this gem, runs git that cannot lose work, asks before anything else
  • all: approve everything automatically

You can set the global default in settings, agents > defaults (under AUTO-APPROVAL (DEFAULT)), or set a per-gem override from the gem menu’s auto-approval › entry (the ⋮ on the gem’s tab). Per-gem modes are saved in .crystl/project.json and persist across sessions. To take the wheel back for a moment without changing any setting, use pause auto-approvals in the crystl app menu. See approval modes for details.

Uninstalling crystl

To remove crystl completely, run its uninstall before you trash the app: the uninstall crystl… button in settings, general > terminal, or crystl uninstall in a shard. It removes the agent hooks, helper scripts, and the crystl command, asks before changing anything, and offers to move the app to the Trash at the end. Dragging the app to the Trash first runs no code, so nothing cleans up after it.

Afterwards, optionally remove the data crystl leaves behind:

rm -rf ~/Library/Application\ Support/Crystl
rm -rf ~/Library/Logs/Crystl
defaults delete com.crystl.app

Uninstalling does not touch your projects or their .crystl/ folders; those live in your own repositories, and removing them is up to you.

Next steps

In a hurry? Scenarios is the task-first index: pick what you want to do and it sends you to the right page.

Understand the shape

  • Gems & shards: the two levels everything else sits on, one gem per project and shards inside it.
  • Isolated sessions: give a shard its own git worktree so two agents can edit the same repo without overwriting each other.
  • Approval modes: what off, in gem, and all each let an agent do, and why your gem’s mode is the ceiling.
  • Conversation history: every turn and command is searchable with Cmd+Shift+F, long after the scrollback is gone.

Day to day

Run more than one agent

These need a Guild membership, because they spawn, merge, and approve on your behalf.

  • Orchestration: start here. It is a decision guide for which of the options below fits what you are doing.
  • Fanout: hand one session a task list and it becomes a manager for the rest.
  • crystl quest: a party of agents with roles, working in a shared chat.
  • Court: a standing crown you talk to, with a hand orchestrating underneath it.
  • Vigil: crystl notices when a whole fan-out has gone quiet and tells you.
  • Schedule agents to start work at a set time, free up to three schedules.

Spend less, or run locally

Away from your desk

  • Mobile app to answer approvals and read shards from your phone.
  • Remote SSH to work on a repo on another machine with approvals still reaching you.

Reference

  • Your agent can drive crystl: the free read-only commands, and the Guild ones that set your workspace up.
  • crystl CLI: every command, and the full free-vs-Guild breakdown.
  • Settings: a map of every page and what each control does.
  • Updating crystl: how updates arrive, and how to go back if one breaks something.
  • Licensing for activation and renewal.