# 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.

## 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](/pricing) or [pitch in](/community).

## 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](/docs/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.

```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 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](/docs/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:

```bash
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

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