Getting Started

Updated June 6, 2026

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.

  1. Open crystl
  2. Click New Gem in the Crystal Rail (the glass bar at the edge of your screen)
  3. Choose a directory for your project
  4. Your first shard opens automatically, and you’re ready to go

Install the command line tool (optional)

crystl bundles a crystl CLI that lets you control gems, shards, and approvals from any shell. Install it from Help → install command line tool…: one admin prompt and crystl symlinks /usr/local/bin/crystl to the bundled binary. You can also install / uninstall from Settings → General → Command Line Tool.

Skip this step if you only use the GUI; you can always come back to it later. See crystl CLI for the full command reference.

Set up CLAUDE.md

Open the gem menu (click the ⋮ on the gem’s tab, or double-click its tile in the Crystal Rail) and choose settings. If the project directory doesn’t have a CLAUDE.md file, crystl will offer to insert one from your templates. You can manage multiple named templates, for example one for backend work and another for frontend, so every project starts with the right instructions.

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 approval mode

crystl supports four approval modes. Pick the one that fits your workflow:

  • Manual: Review and approve every tool call
  • Smart: Auto-approve safe operations (reads, searches), prompt for writes
  • Auto: Approve everything automatically
  • Pause: Queue all approvals for later review

You can switch modes globally from the Crystal Rail flyout, or set a per-project override from the gem menu’s approval entry (the ⋮ on the gem’s tab, or a double-click on its tile in the Crystal Rail). Per-project modes are saved in .crystl/project.json and persist across sessions. See Approval Modes for details.

Uninstalling crystl

To remove crystl completely:

  1. Quit crystl.
  2. If you installed the command line tool, remove it from Settings → General → Command Line Tool (or delete the symlink directly with 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