# Formations

> Save and restore named collections of gems for quick context switching when multitasking across projects.

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

1. Open the gems and shards you want in the formation
2. Go to **Settings > Formations** (`Cmd + ,` then navigate to Formations)
3. Click **Save Current**
4. Give the formation a name
5. 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:

1. Creates a regular shard in the gem
2. Runs the SSH command for the host
3. Polls for SSH ControlMaster availability so subsequent commands can reuse the connection
4. Calls `RemoteGitWorktree.create()` to recreate the worktree from the saved branch, or reattach it if the worktree already exists on the remote
5. Records the worktree path on the session so merge/close prompts behave correctly when the shard is later closed
6. `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:

```json
{
  "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.

---
Source: https://crystl.dev/docs/formations/