Gems & Shards

Updated April 24, 2026

Gems

A gem is a project workspace in Crystl. Each gem is tied to a directory on your machine and appears as a tile in the Crystal Rail — the draggable glass bar at the edge of your screen — and as a tab in the tab bar at the top of the terminal window.

Gems give you:

  • Project isolation — Each gem has its own set of terminal sessions, its own approval mode, and its own .crystl/project.json config (name, icon, color)
  • Quick switching — Click any gem in the Crystal Rail or tab bar to jump between projects
  • Per-gem identity — Pick an icon and color per gem so you can tell them apart at a glance

Creating a Gem

There are two ways to create a new gem:

  • Click New Gem in the Crystal Rail, fill out the panel (name, path, icon, color, MCP servers, agent files), and hit Create.
  • Click the + button on the tab bar. This opens the directory picker so you can pick an existing project folder. The new gem is created with sensible defaults — you can rename it or tweak icon/color afterward from Gem Settings.

The + on the tab bar is for opening a different project. To spawn another terminal in the same project, use the shard bar (see below).

Shards

A shard is a terminal session within a gem. Think of shards as tabs inside a project — each one runs its own shell process and can have its own Claude Code session. Shards appear in the shard bar that drops in below the tab bar once a gem has two or more shards.

Shards are named after crystals — diamond, opal, jade, lapis, topaz, onyx, pearl, amber, quartz, ruby, garnet, emerald, cobalt, peridot, zircon, amethyst, tanzanite, carnelian, turquoise, morganite. Each crystal has a signature color used for the shard label text and underline accent in the shard bar. The first shard in every gem is always diamond.

Creating a Shard

Click the + button on the shard bar to add a new shard to the current gem. New shards inherit context from the currently selected shard:

  • Local cwd — If you’ve cd’d into a subdirectory of the project, the new shard starts in that same subdirectory. This matches the behavior you’d expect from Warp or iTerm — spawning a shard next to work you’re already doing keeps you in place.
  • SSH session — If the current shard is SSH’d into a remote host, the new shard automatically reconnects to the same host.
  • Remote cwd — If the current shard is SSH’d and sitting in a specific remote directory, the new shard cds to that same remote path after connecting. Crystl parses the remote working directory from the shell prompt, so it works even without shell integration on the remote side.

Isolated Shards

For multi-agent workflows, Option+click the + button on the shard bar to create an isolated shard backed by a git worktree. Each isolated shard gets its own branch (crystl/{name}), so multiple Claude agents can work on the same repo without stepping on each other.

  • Local gems — The worktree is created at .crystl/worktrees/{name} inside the project directory.
  • SSH gems — If the current gem has an active SSH session, the worktree is created on the remote server instead of locally. This lets you run isolated agents directly on the host where the code lives.

Isolated shards are marked with a ⎇ prefix in the shard bar. See Isolated Sessions for the full rundown, including the merge-on-close prompt and agent guardrails.

Working with Shards

  • Session state — Each shard maintains its own shell history, working directory, approval mode, and Claude session. Claude sessions autosave and restore when you restart Crystl, so you pick up right where you left off
  • Claude awareness — When you run claude in a shard, Crystl automatically connects to manage approvals through its glass UI
  • Context load indicator — After a shard has had 3+ Claude turns, a ~N turns left label appears in the status bar estimating how much of the context window is still available. Click it to open the context load panel, which shows per-turn token history and your current burn rate so you can decide when to /clear or compact.

Gem Settings

Each gem has a settings panel you can open by clicking a selected tile in the Crystal Rail, or from the status bar. Gem Settings includes:

  • Approval mode — Override the global approval mode for this gem. Choose Default (Global), Manual, Smart, or Auto Approve. See Approval Modes for details.
  • CLAUDE.md detection — Crystl checks whether a CLAUDE.md file exists in the project directory. If one is missing, you can insert a template with one click.
  • CLAUDE.md templates — Pick from your template library when setting up a new project. Manage templates in Settings → File Library → Templates. See Agent Config Editor for the full editing system.
  • Facet Inserts — Manage your saved prompts, commands, and shortcuts. See Facet Inserts for details.
  • Autosave — Toggle the 5-minute session history autosave on or off. Claude sessions are also autosaved and restored on restart.
  • Session history — Browse and open past sessions from the history button.

The Crystal Rail

The Crystal Rail is the glass bar that sits at the edge of your screen — left, right, or top. Drag it to any edge to reposition, or set it in Settings. It shows all your gems and lets you:

  • Switch between projects with a click
  • See which gems have active Claude sessions
  • Create new gems and shards
  • Access settings for each workspace