# Starting a Crystl Quest

> Summon a party of agents and begin multi-agent collaboration.

Starting a quest creates a coordinated group of Claude Code agents that work together on your project. This page walks through setup, party configuration, mode selection, and resuming existing quests.

## 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 > crystl quest > Party templates**.

### 2. 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](/docs/isolated-sessions).

### 3. 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 `cd`s to this directory
- **Sealed mode** — worktrees are created under `.crystl/worktrees/` inside this directory

### 4. Summon the Party

Click **Summon Party** to begin. Crystl creates shards for each hero in the party with staggered timing — 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 assigned model (Sonnet, Opus, or Haiku depending on the hero)
- In sealed mode: an isolated worktree on a dedicated branch

### 5. 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 > crystl 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, Dexterity (1-10 scale)
   - **Model** — Which Claude model to use (Sonnet, Opus, or Haiku)
   - **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](/docs/quest-heroes) 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.

## 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](/docs/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](/docs/remote-ssh).

### 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 — 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 — there's 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 > crystl 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).

## Related Docs

- [Crystl Quest](/docs/crystl-quest) — Overview of the quest system
- [Quest Chat Panel](/docs/quest-chat) — Using the chat interface
- [Quest Heroes](/docs/quest-heroes) — Hero catalog and stat system
- [Isolated Sessions](/docs/isolated-sessions) — How sealed mode worktrees work
- [Remote SSH Sessions](/docs/remote-ssh) — SSH tunneling, remote worktrees, and file relay

---
Source: https://crystl.dev/docs/starting-a-quest/