Getting Started · crystl Docs

Creating a New Gem

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 are: 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:

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:

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 lasts longer than 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:

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

Day to day

Run more than one agent

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

Spend less, or run locally

Away from your desk

Reference