Getting Started

Updated April 3, 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.

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 — you’re ready to go

Set Up CLAUDE.md

Open Gem Settings from the status bar. 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 by clicking a selected gem tile to open Gem Settings. Per-project modes are saved in .crystl/project.json and persist across sessions. See Approval Modes for details.

Next Steps