Formations — Crystl Docs

Formations are named collections of gems (and optionally their shards) that you can save and reload as a group. Instead of opening your projects one by one, save your current layout as a formation and restore it all at once. Formations also cover SSH’d gems and remote worktrees, so you can restore a cross-host working layout with a single click.

How It Works

A formation captures which gems are currently open, along with each gem’s icon, color, and — for SSH’d gems — the remote host and remote working directory. You can also choose to save the shards within each gem (their names, working directories, and isolation state). When you load a formation, Crystl opens all the gems, restores their visual identity, optionally reconnects SSH sessions, and recreates the saved shards (including remote git worktrees). Formations are stored at ~/.config/crystl/formations.json.

Formations also save and restore Claude sessions. When you load a formation, each shard’s Claude session is resumed where it left off — no need to re-explain context or start over. Previous conversations are also accessible through the History button in each shard.

Saving a Formation

Open the gems and shards you want in the formation
Go to Settings > Formations (Cmd + , then navigate to Formations)
Click Save Current
Give the formation a name
Optionally toggle Include Shards to save shard layout within each gem

Crystl saves the set of open gems (and their shards, if selected) under that name.

Loading a Formation

From Settings > Formations, click a saved formation to load it. Crystl opens all the gems in that formation, applying each gem’s saved icon and color. If shards were saved, they’re recreated with their original names and directories. Any gems that were already open stay open.

If the formation contains SSH’d gems, Crystl shows a load dialog with two options:

load + connect — open the gems and automatically SSH into each remote host, cd to the saved remote working directory, and recreate any remote worktrees
load without SSH — open the gems as local sessions without touching SSH (useful when you’re offline or just want the layout back)

Icon and Color Preservation

Each gem entry in a formation stores its Lucide icon name and hex color. This matters most for SSH’d gems: remote gems often share the same local path (typically $HOME or /Users/chris), which means the per-project .crystl/project.json approach can’t differentiate them. Formations sidestep this entirely — icon and color are saved per-formation-entry, so two SSH gems pointed at different remote hosts can have distinct identities even when their local paths collide.

On load, Crystl applies the saved icon and color to each restored gem before the tab is rendered.

SSH Gems and Remote Working Directories

When you save a formation, Crystl inspects each gem to see if it’s currently SSH’d into a remote host. For SSH’d gems it captures:

sshHost — the host string used to connect (e.g. user@host)
remoteCwd — the current working directory on the remote, parsed from the SSH prompt using the detected hostname

On load (with load + connect), Crystl opens the gem locally, runs the SSH command, waits for the connection, and sends cd {remoteCwd} so the session lands in the same remote directory you left.

Remote Isolated Shards

Formations can also save and restore git worktrees that live on remote servers. If a shard is running in a remote worktree when you save, the entry records the remoteProjectDir (the remote parent directory that owns the worktree) alongside the shard’s name and branch.

On load, for each remote isolated shard Crystl:

Creates a regular shard in the gem
Runs the SSH command for the host
Polls for SSH ControlMaster availability so subsequent commands can reuse the connection
Calls RemoteGitWorktree.create() to recreate the worktree from the saved branch, or reattach it if the worktree already exists on the remote
Records the worktree path on the session so merge/close prompts behave correctly when the shard is later closed
cd’s into the worktree path

This lets you shut down your laptop with a five-gem, ten-shard remote layout and restore the whole thing — including each remote worktree branch — with one click.

Default Formation

Set a formation as the default to have Crystl auto-load it on startup. This is useful when you work on the same set of projects daily — launch Crystl and everything is ready with all your gems and shards in place.

To set a default, select a formation in Settings > Formations and mark it as default.

What Gets Saved

Saved	Not Saved
Open gems	Running processes
Gem names and local paths	Approval queue state
Gem icon and color	Terminal scrollback
SSH host and remote working directory
Shard names and directories (optional)
Remote worktree branch and parent dir (optional)
Claude sessions (restored on load)

Storage Format

Formations live at ~/.config/crystl/formations.json. Each formation is a named list of entries; each entry is one gem with optional per-shard state:

{
  "weekday": {
    "default": true,
    "entries": [
      {
        "path": "/Users/chris/Projects/crystl",
        "name": "crystl",
        "icon": "gem",
        "color": "#8ac6d1",
        "shards": [
          { "name": "diamond", "cwd": "/Users/chris/Projects/crystl" },
          {
            "name": "aquamarine",
            "cwd": "/Users/chris/Projects/crystl/.crystl/worktrees/aquamarine",
            "isolated": true,
            "branch": "crystl/aquamarine"
          }
        ]
      },
      {
        "path": "/Users/chris",
        "name": "prod-api",
        "icon": "server",
        "color": "#c9a27a",
        "sshHost": "chris@prod.example.com",
        "remoteCwd": "/srv/api",
        "shards": [
          { "name": "diamond", "cwd": "/srv/api" },
          {
            "name": "sapphire",
            "isolated": true,
            "branch": "crystl/sapphire",
            "remoteProjectDir": "/srv/api"
          }
        ]
      }
    ]
  }
}

Key fields per entry:

path — local gem directory (used as the SPM session cwd on load)
name — gem display name
icon — Lucide icon name (see LucideIconData.swift)
color — hex string, applied to the tab accent
sshHost — optional; present only for SSH’d gems
remoteCwd — optional; the remote directory to cd into after SSH connects
shards — optional array; each shard records name, cwd, isolated, branch, and (for remote worktrees) remoteProjectDir

Use Cases

Project Context Switching

Save a “frontend” formation with your UI repos and a “backend” formation with your API and database projects. Switch between contexts in one click.

Multi-Agent Workflows

Save a formation with a gem and its shards pre-configured — load it to instantly spin up the same multi-agent layout you had before, with Claude sessions restored so each agent picks up where it left off.

Daily Setup

Set your most-used projects as the default formation so Crystl opens them automatically every morning with all your shards ready to go.

Availability

Formations are a Guild feature.