Getting Started

Updated August 6, 2026

"+ new" creates the gem in your home directory, with no dialog. Click the pulsing folder icon in the status bar to point it at your project.

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.

Platform support

crystl is macOS only today. There’s no Windows or Linux build yet.

That said, cross-platform is now on the table. crystl’s terminal core is being rebuilt on a more portable foundation, which clears the biggest technical blocker to a Windows or Linux version. It’s a possibility, not a promise: crystl is built by one developer, and a port only becomes realistic with either more paying subscribers (so I can afford the time) or volunteer contributors. If a Windows or Linux version matters to you, the most direct way to make it happen is to support crystl or pitch in.

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 + new at the bottom of the gem sidebar
  3. Click the pulsing folder icon in the status bar at the bottom of the window
  4. Pick your project directory
  5. Your first shard opens automatically, and you’re ready to go

If you clicked ”+ new” and never got asked for a directory

+ new at the bottom of the gem sidebar doesn’t open a picker. It creates the gem immediately in your home directory, ready to point somewhere.

Look at the status bar along the bottom of the window: the new, unconfigured gem shows a folder icon next to the path, and it pulses to get your attention. Click it and the directory picker opens. 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. It never creates a folder for you. 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. Pick your project folder and the gem re-roots there.

So nothing is broken if no dialog appeared: + new creates the gem first, then the status-bar folder icon opens the picker.

Start a project from scratch

For a project whose folder doesn’t exist yet:

  1. Click + at the bottom of the crystal rail (new gem) to open the New Gem panel
  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. 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.
  5. 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 → 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 worth knowing:

  • 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 → 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 → File Library to manage reusable files and starter bundles for new gems.

Start Claude Code

Inside any shard, start a Claude Code session.

claude

crystl detects the Claude Code process and begins managing permission approvals through floating glass panels. You can allow or deny each tool call without leaving your terminal.

Choose an auto-approve mode

crystl has three auto-approve 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-APPROVE (DEFAULT)), or set a per-gem override from the gem menu’s auto-approve › 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:

  1. Quit crystl.
  2. Remove the command line tool from Settings → general → terminal → CRYSTL CLI (or delete the symlink directly with sudo rm /usr/local/bin/crystl).
  3. Drag crystl from your Applications folder to the Trash.
  4. 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