Resurrecting Shards

Updated August 2, 2026

Closed a shard you didn’t mean to? crystl keeps a short undo-close list for each gem, so you can bring a recently closed local shard back, with its name, color, and best-effort isolation and agent session intact.

This is separate from the automatic session restore that brings your gems and shards back when you relaunch crystl. Resurrection is an explicit undo-close for shards you’ve closed during a session.

What gets remembered

When you close a local shard, crystl records it in that gem’s resurrect list before it goes. Each entry remembers the shard’s:

  • name and color: the crystal it carried in the shard bar
  • isolation state: whether it was an isolated shard backed by a git worktree, restored best-effort
  • agent session: the agent session it was running, resumed best-effort so you pick up where you left off. Claude Code (claude --resume), Codex (codex resume), and Antigravity (agy --conversation) all reopen their actual conversation; agents without a resume mechanism (or when the saved conversation is gone) start the agent fresh instead, with a note saying so

Quest party members and remote shards are skipped: they aren’t tracked for resurrection.

A restored shard relaunches its own agent

A shard that comes back from a resurrect (or from the session restore after you relaunch crystl) comes back as a shell first: its name, color, cwd, and role marker are there before its agent is. Rather than making you start the agent by hand, crystl holds a deferred relaunch on the shard and fires it the moment something is dispatched to it. Send it a message from the chat dock, a quest turn, the phone, or crystl send, and the agent starts on its own conversation and then receives what you sent, instead of the text landing in the shell underneath.

That’s what lets an overnight fan-out survive quitting crystl: a lead can address a restored worker and get the worker back, mid-conversation, not a fresh agent with no memory of the task.

When the relaunch can’t happen, the shard says so rather than looking healthy and quietly swallowing what you send it. crystl shards marks the two states apart:

  • ⏸ no agent — relaunches on dispatch: the deferred relaunch is armed and waiting.
  • ⚠ no agent — relaunch failed: <error>: the relaunch was tried and no agent came back, quoting the agent’s own error when it has one (a session id already in use, for example). Dispatches into it are refused instead of being dropped into a bare shell.

An orchestrator that survived the restart also reads as orchestrator (unmanned) until its agent is back, so a lead coordinating other agents can tell a live hand from an empty one.

Bringing a shard back

Resurrection lives in the crystl CLI. Listing what’s available is read-only and free; the resurrect action itself changes state, so it’s a Guild control command.

crystl resurrect list --gem myapp          # see what can be brought back
crystl resurrect --gem myapp               # bring back the most recently closed shard
crystl resurrect --gem myapp --shard opal  # bring back a specific one by name

Without --shard, crystl resurrects the most recent entry. See the CLI reference for every flag, the --json output, and the HTTP API (GET/POST /api/v1/gems/:id/resurrect).