# Creating a New Gem

## Install crystl

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

### Open a project you already have

This is the usual starting point, and the shortest route.

1. Open crystl
2. Click the **folder** icon at the bottom of the gem sidebar
3. Pick your project directory. It starts where your projects already are: 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. 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.
4. Your first shard opens automatically, and you’re ready to go

### Start a project from scratch

For a project whose folder doesn’t exist yet:

1. Click **+** at the bottom of the gem sidebar. This opens the New Gem panel directly — no extra click needed.
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. Pick a **project type** — Code, Research, Content, Records, Personal, Orchestration, or General. It decides which [starter kits](/content/docs/starter-files/index.html) and [optimizer](/content/docs/project-optimizer/index.html) checks fit the gem. Not sure yet? Leave it and crystl offers to set it for you once the gem is open; either way it’s [changeable any time](/content/docs/gem-types/index.html) from gem settings.
5. 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.
6. 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](/content/docs/isolated-sessions/index.html). 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**, under **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**, under **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](/content/docs/cli/index.html) 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, **context** to manage reusable files and starter bundles for new gems.

## Set up an agent

crystl runs your agent, it does not replace it, so you install the agent yourself and crystl manages it from there. Each page below covers installing it, signing in, launching it in a shard, and what crystl can and cannot do with that particular agent:

- **[Claude Code](/content/docs/agent-claude-code/index.html)**: the most complete integration, and the one crystl was built around first.
- **[Codex](/content/docs/agent-codex/index.html)**: fully integrated, and the only agent whose own launch flags follow your auto-approval mode.
- **[Antigravity CLI](/content/docs/agent-antigravity/index.html)**: fully integrated, with one exception worth knowing before you leave one running: its approvals stay in its own terminal.
- **[Kimi Code](/content/docs/agent-kimi/index.html)**: partial. Approval cards work; no turn-end reporting, history, or resume.

Those four are the tested integrations rather than a closed list. crystl recognises several other agents in the process tree, and a shard is a terminal, so anything you can type runs.

Once one is installed, start it inside any shard by typing its command:

```
claude
```

crystl detects the agent’s process and starts managing its permission approvals through floating glass panels, so you can allow or deny each tool call without leaving your terminal.

## Ask your agent about crystl

Your agent can run the `crystl` command, and crystl puts a reference to it in each gem’s instruction files, so a fresh agent already knows the commands exist.

The useful part on day one is that **the whole documentation set is in the terminal**, free on every tier. Rather than reading a page about a feature, ask the agent already sitting in front of you:

> _“what does crystl’s in gem approval mode allow? check `crystl docs`.”_
> 
> _“is anything waiting on me right now?”_

It can also report on your workspace (`crystl status`, `crystl shards --all`), hand you things through the copy bar, and, with a [Guild membership](/content/pricing/index.html), open gems and spawn workers for you. See [your agent can drive crystl](/content/docs/agent-drives-crystl/index.html).

## Find your way around

Four things worth knowing on day one. The [full list](/content/docs/keyboard-shortcuts/index.html) is longer, but these are the ones you will use every hour.

|  |  |
| --- | --- |
| `Cmd + Ctrl + T` | **New shard.** A second session in the same project, so one agent can work while you keep a terminal free. |
| `Cmd + D` | **Split the view** so you can watch both at once. `Cmd + Opt + ←` and `→` move between panes. |
| `Cmd + K` | **Clear the screen and scrollback.** Also frees that shard’s memory after a noisy build. |
| `Cmd + Shift + F` | **Search everything you have ever done.** |

That last one is the one people are most surprised by. Agent turns and shell commands go into a searchable [history](/content/docs/conversation-history/index.html) that lasts longer than the scrollback, so clearing a shard, or even closing it, does not lose what was said. Results span open and closed shards.

The shortcut scheme is consistent once you see it: `Cmd` acts on gems, `Cmd + Ctrl` acts on shards.

## Choose an auto-approval mode

crystl has three auto-approval 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-APPROVAL (DEFAULT)**), or set a per-gem override from the gem menu’s **auto-approval ›** 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](/content/docs/approval-modes/index.html) for details.

## Uninstalling crystl

To remove crystl completely, run its uninstall before you trash the app: the **uninstall crystl…** button in settings, **general > terminal**, or `crystl uninstall` in a shard. It removes the agent hooks, helper scripts, and the `crystl` command, asks before changing anything, and offers to move the app to the Trash at the end. Dragging the app to the Trash first runs no code, so nothing cleans up after it.

Afterwards, 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 are in your own repositories, and removing them is up to you.

## Next steps

In a hurry? [Scenarios](/content/docs/scenarios/index.html) is the task-first index: pick what you want to do and it sends you to the right page.

### Understand the shape

- [Gems & shards](/content/docs/gems-and-shards/index.html): the two levels everything else is built on, one gem per project and shards inside it.
- [Isolated sessions](/content/docs/isolated-sessions/index.html): give a shard its own git worktree so two agents can edit the same repo without overwriting each other.
- [Approval modes](/content/docs/approval-modes/index.html): what **off**, **in gem**, and **all** each let an agent do, and why your gem’s mode is the ceiling.
- [Conversation history](/content/docs/conversation-history/index.html): every turn and command is searchable with `Cmd+Shift+F`, long after the scrollback is gone.

### Day to day

- [Keyboard shortcuts](/content/docs/keyboard-shortcuts/index.html) and [split view](/content/docs/split-view/index.html) for moving around quickly.
- [Notifications](/content/docs/notifications/index.html): which panels float, and the rule that keeps crystl from floating a copy of a shard you are already watching.
- [Facet inserts](/content/docs/facet-inserts/index.html) to pin your go-to prompts as one-click buttons.
- [Workbench](/content/docs/task-backlog/index.html): a shared task list your agents can read and tick off.
- [Formations](/content/docs/formations/index.html) to save and restore a whole window arrangement.
- [Agent files](/content/docs/agent-files/index.html) and [starter files](/content/docs/starter-files/index.html) for the instruction files each gem hands its agent.
- [Project optimizer](/content/docs/project-optimizer/index.html) to score how well a project is set up for an agent before you blame the agent.

### Run more than one agent

These need a [Guild membership](/content/pricing/index.html), because they spawn, merge, and approve on your behalf.

- [Orchestration](/content/docs/orchestration-guide/index.html): start here. It is a decision guide for which of the options below fits what you are doing.
- [Fanout](/content/docs/fanout/index.html): hand one session a task list and it becomes a manager for the rest.
- [crystl quest](/content/docs/crystl-quest/index.html): a party of agents with roles, working in a shared chat.
- [Court](/content/docs/court/index.html): a standing crown you talk to, with a hand orchestrating underneath it.
- [Vigil](/content/docs/vigil/index.html): crystl notices when a whole fan-out has gone quiet and tells you.
- [Schedule agents](/content/docs/schedule-agents/index.html) to start work at a set time, free up to three schedules.

### Spend less, or run locally

- [Open models](/content/docs/open-models/index.html): run your agent on your own hardware or a hosted open model, with setup tutorials for [Ollama](/content/docs/open-models-ollama/index.html), [LM Studio](/content/docs/open-models-lm-studio/index.html), [vLLM](/content/docs/open-models-vllm/index.html), [llama.cpp](/content/docs/open-models-llama-cpp/index.html), and [z.ai](/content/docs/open-models-zai/index.html).
- [Model sizes](/content/docs/model-sizes/index.html): teach crystl your models once so every hero and quest picks the right one.

### Away from your desk

- [Mobile app](/content/docs/mobile-app/index.html) to answer approvals and read shards from your phone.
- [Remote SSH](/content/docs/remote-ssh/index.html) to work on a repo on another machine with approvals still reaching you.

### Reference

- [Your agent can drive crystl](/content/docs/agent-drives-crystl/index.html): the free read-only commands, and the Guild ones that set your workspace up.
- [crystl CLI](/content/docs/cli/index.html): every command, and the full free-vs-Guild breakdown.
- [Settings](/content/docs/settings/index.html): a map of every page and what each control does.
- [Updating crystl](/content/docs/updating-crystl/index.html): how updates arrive, and how to go back if one breaks something.
- [Licensing](/content/docs/licensing/index.html) for activation and renewal.