Gems & Shards

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 gem tab bar, which sits across the top of the terminal window by default or down the left side when Sidebar Mode is on (Settings > General).

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.

A shard’s crystal name is set when it’s created: in the app, new shards are auto-assigned the next free crystal, and from the CLI you can pick any name you want by passing --crystal-name (see below) — the flag isn’t limited to the crystal list, so crystl shard create --gem myapp --crystal-name deploy-bot works and names the shard deploy-bot. The built-in crystals are just the defaults — and the names that carry a signature color in the shard bar.

Separately from the crystal name, every shard carries a stable internal ID plus an editable display label. crystl shard rename --gem myapp --shard opal --name "auth-refactor" sets a short label (lowercased, ≤14 characters) shown on the shard’s pill, in the window title, and in crystl shards / crystl status — without touching the crystal name, git branch, or session identity, so restore, history, and formations all survive a rename. After renaming you can address the shard by its label, its crystal name, or its ID; ambiguous duplicate labels are rejected rather than silently routing to the wrong shard. See shard rename for details. Creating and renaming shards from the CLI are Guild actions; on the free tier you create shards with the in-app + button, which auto-assigns the next crystal.

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.

From the CLI

Once you’ve installed the crystl CLI, you can spawn shards from any shell. Handy for scripts and for orchestrator agents that want to fan work out into sibling shards.

crystl shard create --gem myapp                          # shared cwd
crystl shard create --gem myapp --isolated               # git worktree
crystl shard create --gem myapp --crystal-name opal      # pick the name
crystl shard create --gem myapp --prompt "add tests"     # launch an agent on a task
crystl shard create --gem myapp --hero seeker --prompt "review auth" # named hero on a task
crystl gauntlet "release readiness"                      # spawn a review crew

The same --gem <name> flag accepts the gem’s display name or its UUID. List options with crystl shards --gem myapp. For broader readiness passes, crystl gauntlet creates a named crew of isolated shards (gauntlet-seeker-a, gauntlet-seeker-b, gauntlet-monk, and gauntlet-scribe) so the reviewers are easy to track in the shard bar.

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.
• Undo close: Closed a shard by accident? crystl keeps a short undo-close list per gem — bring it back with crystl resurrect, name, color, isolation, and agent session intact.

The gem menu

Each gem exposes a menu with three entries:

• history: Browse and reopen past sessions for the gem (see Conversation History)
• settings: Open the Gem Settings panel (below)
• approval: Set the per-gem approval mode (see Approval Modes)

Open it by clicking the ⋮ on the gem’s tab, or by double-clicking the gem’s tile in the Crystal Rail. A single click on a rail tile just switches to that gem.

Gem settings

Open the gem menu (the ⋮ on the gem’s tab, or a double-click on its tile in the Crystal Rail) and choose settings. 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 entry in the gem menu.

Plugin and skill inclusion

The New Gem panel and Gem Settings panel both include four collapsible sections that control which plugins and skills load into agents started inside this gem. Each section shows a checkbox row per installed entry; unchecking an entry writes a disable flag on save.

• INCLUDE PLUGINS?: every installed Claude Code plugin from ~/.claude/plugins/. Unchecked entries write enabledPlugins.<id>: false to <gem>/.claude/settings.json so that plugin doesn’t load when you run claude inside this gem.
• INCLUDE SKILLS?: same pattern for user-level Claude skills from ~/.claude/skills/. Unchecked entries land in the same <gem>/.claude/settings.json under skillOverrides.
• INCLUDE CODEX PLUGINS? (global, restart codex): Codex plugins from ~/.codex/plugins/cache/. Codex has no per-project scope, so unchecking here writes the disable to ~/.codex/config.toml globally for every Codex session on your machine. Codex must be restarted in any running shard for the change to take effect.
• INCLUDE CODEX SKILLS? (global, restart codex): Codex/agent skills from ~/.agents/skills/. Also writes globally to ~/.codex/config.toml and requires a Codex restart.

These same lists power the per-row disable menus in the Context Load Panel. Use the panel for ad-hoc, one-row-at-a-time changes during a live session and use Gem Settings to lock in the per-gem default before you start work.

Auto-detect on new gem

When you create a new gem, crystl scans the chosen project directory for marker files and, if it finds any, pops an alert proposing which Claude plugins to enable for the new gem. Markers it looks for:

Marker	Suggests
vercel.json or next.config.*	Vercel / Next.js plugins
shopify.app.toml	Shopify plugin
wrangler.toml or wrangler.jsonc	Cloudflare plugin
supabase/config.toml	Supabase plugin
.sentryclirc or sentry.properties	Sentry plugin
Package.swift	Swift tooling

The alert lists the suggested set and gives you three buttons:

• accept: unchecks every non-suggested plugin in the New Gem panel before the gem is created, leaving only the matches enabled
• customize: closes the alert without changing checkbox state so you can tweak the inclusion lists yourself before hitting Create
• skip: leaves all plugins as-is (default: every installed plugin enabled)

The dialog only fires on new-gem creation, not on existing gems being reopened.

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