# Getting Started

> Install Crystl and create your first gem.

## Install Crystl

Sign in at [crystl.dev](https://crystl.dev/login) and download the latest version from your [account page](https://crystl.dev/account). 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:

```bash
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](/docs/approval-modes) for details.

## Next Steps

- Learn about [Gems & Shards](/docs/gems-and-shards) to organize your projects
- Set up [Facet Inserts](/docs/facet-inserts) to save your go-to prompts
- Explore [Isolated Sessions](/docs/isolated-sessions) for multi-agent workflows
- Set up [Remote SSH](/docs/remote-ssh) to use approval panels on remote machines
- Check the [Keyboard Shortcuts](/docs/keyboard-shortcuts) reference
- Read about [Licensing](/docs/licensing) for activation and renewal

---
Source: https://crystl.dev/docs/getting-started/