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

### 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](/docs/isolated-sessions/). 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:

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

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

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