Starting a crystl quest

Updated August 1, 2026

Starting a quest creates a coordinated group of agents that work together on your project, each hero running its configured agent (Claude Code, Codex, or Antigravity CLI). This page walks through setup, party configuration, mode selection, and resuming existing quests.

Planning first? If you’d rather state a goal and have the levels authored for you before you pick a party, start with plan quest and the quest master instead. It shapes the questline, suggests the heroes, and hands you a pre-filled version of the panel below.

Opening the crystl quest panel

Click the Quest button in the shard bar, the crossed swords icon. If no quest exists for the current gem, the setup panel appears. If a quest is already running, clicking the button reopens the active quest panel.

Setup flow

1. Choose a party template

The setup panel shows available party templates. Each template defines a set of heroes with pre-assigned roles, stats, and model selections. crystl ships with built-in templates:

  • Design & Dev: Wizard (UI/UX), Ranger (Frontend), Rogue (Backend), Healer (Context Health)
  • Full Stack: Wizard, Ranger, Rogue, Paladin (Researcher), Healer
  • Review & QA: Bard (Reviewer), Monk (QA), Druid (Planner), Healer

You can also create custom templates in Settings > Quest > Party templates. Custom templates are global to your machine by default. Use create local party to commit a template to <gem>/.crystl/parties/*.json instead; it ships with the repo, so everyone who clones the gem gets the same party. You can also build and manage parties from the command line with crystl party (list / create / delete, with --local to commit), then launch one with crystl quest start --party <name>.

2. Choose a model size

Under the roster is a model size dropdown: each hero’s own (the default), small, standard, or large. It sets one model size for every hero in the party, so you can run a cheap party to explore and a large one for a hard problem without editing a single hero.

Picking a size overrides each hero’s own catalog size. That is deliberate: most heroes already carry a size, so a control that only filled in the blanks would do nothing for the built-in parties. Choose large and the whole party runs large. Leave it on each hero’s own and every hero keeps the size it was configured with.

Two things the size does not change, both called out under the dropdown:

  • Heroes with a model pinned launch with that pin, whatever the dropdown says. A pin is the most deliberate choice available, so it wins outright. No built-in hero carries one, so this only applies to heroes you pinned yourself. A pin that is a complete launch command runs the agent it names.
  • A hero with no size runs your agent’s own default. Under each hero’s own, a hero that never asked for a size gets no model flag at all, and your agent launches on whatever it is configured to run.

So each member resolves in three steps: a pin, then the member’s size (through the named agent’s own three, or the three default launch commands when nothing names an agent), then nothing. Solo hero shards run the same resolution, so a hero behaves the same summoned alone or seated in a party.

The dropdown remembers your last choice, so a repeat launch opens on the size you used before rather than resetting.

3. Choose a mode

Select the collaboration mode for this quest:

  • Open Chat: all agents share the same working directory. Changes are visible immediately across agents. Best for small, focused tasks or when agents work on separate files.
  • Sealed Chat: each agent gets an isolated git worktree on its own branch. Best for parallel feature work where agents might touch overlapping files. Uses the same system as isolated sessions.

4. Choose a questline (optional)

If the gem has an authored or saved questline, the panel shows a questline dropdown. It stages the party into an ordered set of levels instead of a plain open room.

  • When the quest master has authored a plan for this gem, that planned questline is preselected, so pressing begin launches straight into it.
  • Any saved questline templates are listed too, alongside the built-in questlines, so you can pick one to launch.
  • Launching carries the same party’s prior chat and questline forward. For a clean slate, use archive chat in the quest window’s menu first; picking a template always archives the old run for you.

Leave it on the emergent option and the quest starts as a plain party with no preset levels. The dropdown only appears when there’s a questline to choose.

5. Directory picker

Quest setup defaults to your current working directory, wherever you cd’d to before opening the panel. You can browse to a different directory using the browse button next to the path field.

For SSH sessions, the picker lists directories on the remote host. It reads the remote filesystem through the same ControlMaster connection as the parent shard, so there’s no extra auth prompt.

The selected directory determines where the quest runs:

  • Open mode: each shard cds to this directory
  • Sealed mode: worktrees are created under .crystl/worktrees/ inside this directory

6. Summon the party

Click Summon Party to begin. crystl creates shards for each hero in the party with staggered timing, so agents don’t all spin up at once, which avoids resource contention. Each shard receives:

  • The hero’s name, role, and personality as context
  • RPG stats translated into behavioral modifiers in the system prompt
  • The hero’s configured agent and model
  • In sealed mode: an isolated worktree on a dedicated branch

7. The quest begins

Once all agents are created, the quest panel opens with:

  • An ASCII art banner
  • Join messages as each agent comes online (— wizard has joined your party —)
  • The chat input at the bottom, ready for your first instruction

Party templates

Party templates save you from reconfiguring heroes every time you start a quest.

Creating a template

  1. Go to Settings > Quest > Party templates
  2. Click New Template
  3. Name the template
  4. Add heroes (pick from the built-in catalog or create custom roles)
  5. For each hero, configure:
    • Role: the functional role (e.g., Frontend, Backend, QA)
    • Personality: text that shapes how the agent communicates
    • Stats: Strength, Intelligence, Wisdom, and Dexterity (1-10 scale)
    • Agent & model: which agent runs the hero (Claude Code, Codex, Antigravity CLI) and which model it uses
    • Instructions: additional context or constraints for the agent
  6. Save the template

Editing a template

Select an existing template in the settings panel and modify any hero’s configuration. Changes apply to future quests; active quests keep their original configuration.

Built-in vs custom heroes

Built-in heroes come from the hero catalog with pre-set stats and roles. Custom heroes let you define your own names, roles, and stat distributions. Both types work the same way in a quest.

Choosing the right mode

When to use open chat

  • Agents are working on different files (frontend vs backend, tests vs implementation)
  • You want agents to see each other’s changes as they happen
  • The task is small enough that file conflicts are unlikely
  • You prefer simplicity over isolation

When to use sealed chat

  • Agents might edit the same files
  • You want clean git history with one branch per agent
  • You plan to review each agent’s work independently before merging
  • The project uses database migrations or schema files that could conflict
  • You want the safety net of being able to discard an agent’s branch without affecting others

Resuming a crystl quest

If you close the quest panel or navigate away, click the quest button again to reopen it. The quest continues running in the background: agents keep working, messages keep flowing, and the chat history is preserved.

If crystl restarts while a quest is active, the quest state is restored from .crystl/quest/ files. Agents reconnect to their shards and the chat panel repopulates with the message history. The file watcher resumes from a saved byte-offset cursor (v2/cursors/messages.cursor) so no messages are replayed or dropped across restarts.

Continuing after a quest has ended

A finished quest isn’t gone: its chat and questline stay in .crystl/quest/ until you archive them, and two one-click paths bring the party back.

  • In the begin-quest panel. When the gem has prior quest chat, a continue last quest button appears, named for the party that ran it. One click relaunches that party carrying its chat and questline forward: no picker fiddling, no template adoption.
  • From the Quest menu. continue quest reopens the live quest’s chat when one is running, and relaunches the last party the same way when none is.

Either way, crystl remembers whether the last quest ran open or sealed and resumes in the same mode: a sealed quest comes back sealed, worktrees and all. The panel’s mode radio pre-selects the remembered mode too (a quest master proposal outranks it when one staged the panel), and you can still flip it before launching.

Continuing is the default: launching the same party always carries its prior chat and questline forward. For a clean slate, use archive chat in the quest window’s menu first, pick a different party (crystl archives the old party’s chat for you), or launch a questline template, which always implies a fresh arc.

Ending a crystl quest

To end a quest, close all the agent shards or use the quest panel controls. In sealed mode, you’ll be prompted to merge, keep, or discard each agent’s branch: the same flow as closing isolated sessions.

crystl quest over SSH

Quest works fully over SSH sessions. All four combinations of mode and location (local open, local sealed, remote open, remote sealed) are supported. No extra configuration is needed beyond the standard SSH auto-tunnel.

Detection

When you open the quest setup panel from a shard that’s connected via SSH, crystl detects the remote session automatically. The directory picker switches to browsing the remote filesystem, and the path field defaults to the remote working directory.

Open mode over SSH

All quest shards SSH to the remote host and cd to the selected directory. Each shard reuses the ControlMaster connection from the parent, so there’s no repeated authentication. Agents share the same remote working directory just like a local open quest.

Sealed mode over SSH

Each agent gets an isolated git worktree on the remote host, created via RemoteGitWorktree. Branches follow the same crystl/{hero-name} naming convention as local sealed quests. Config files (CLAUDE.md, AGENTS.md, .mcp.json, .claude/) are symlinked into each remote worktree. On quest completion, the same merge/keep/discard prompts appear, and all git operations execute on the remote through the SSH connection.

Approval panels

Approval panels work over SSH through the bridge relay. The reverse tunnel set up by the ssh() wrapper routes hook requests from the remote Claude Code process back to the local bridge. Each agent’s approvals appear locally as usual, with nothing quest-specific to configure.

Chat relay

Quest chat messages between shards relay through the bridge. When one remote agent sends a quest_msg, the message routes through the SSH tunnel to the local bridge, which delivers it to the target shard (whether that shard is local or remote). The chat panel shows all messages regardless of where the agents are running.

crystl quest settings

Configure quest defaults in Settings > Quest:

  • Identity: set your quest username and user personality. Your messages appear under this name in the chat panel.
  • User stats: assign yourself RPG stats that appear in the party sidebar.
  • Default mode: pre-select open or sealed as the default for new quests.
  • Sounds: toggle the join sound (when agents come online) and send sound (when messages are delivered).