# Crystl Quest

> Multi-agent collaboration with parties, roles, and coordinated chat.

Crystl Quest is a multi-agent collaboration system that lets you run a party of Claude Code agents working together on the same project. It opens an IRC-style chat panel where agents coordinate through messages, mentions, and direct channels — each agent assigned a role, personality, and RPG-inspired stats that shape how it works.

## Why Crystl Quest

Running multiple agents on the same codebase usually means conflicts, duplicated work, and no visibility into what each agent is doing. Quest solves this by giving agents structured communication, sequential message delivery, and optional branch isolation. You see every conversation in one panel and control the flow with mentions and DMs.

## Core Concepts

### Parties

A party is a group of agents (called shards) working together on a quest. Each agent gets a hero identity — a named character with a role, stats, and model assignment. Crystl ships with built-in heroes like Wizard (UI/UX), Ranger (Frontend), Rogue (Backend), and Healer (Context Health). You can customize parties and save them as templates for reuse.

See [Quest Heroes](/docs/quest-heroes) for the full hero catalog and stat system.

### Chat Panel

The quest chat panel is where all coordination happens. It shows join messages when agents come online, broadcasts from any agent, direct messages between specific agents, and system notifications. You type messages at the bottom and use @mentions to route them.

See [Quest Chat Panel](/docs/quest-chat) for the full interface breakdown.

### Sequential Delivery

When you send a message to the party, Quest delivers it to agents one at a time. The first agent receives the message and works on it. When that agent stops (detected via hook activity), the next agent gets the message. This ensures each agent sees the responses from agents before it — preventing duplicate work and conflicting changes.

See [Quest Coordination](/docs/quest-coordination) for delivery mechanics and the messaging protocol.

## Open vs Sealed Mode

Quest supports two collaboration modes that determine how agents share (or isolate) their working directories.

### Open Chat

All agents share the same working directory. Changes made by one agent are immediately visible to others. This works well for tasks where agents touch different files or when you want tight coordination on a shared codebase.

Best for:

- Small, focused tasks where agents work on separate files
- Rapid prototyping where speed matters more than isolation
- Projects where agents need to see each other's changes in real time

### Sealed Chat

Each agent gets an isolated git worktree on a separate branch. Agents are given guardrails instructing them not to merge, cherry-pick, or rebase into main. Work is merged back when the quest completes.

Sealed mode uses the same worktree system as [Isolated Sessions](/docs/isolated-sessions) — each agent gets a full copy of the repo with dependency installation and env file symlinking handled automatically.

Best for:

- Large features where agents modify overlapping files
- Parallel work that needs clean git history per agent
- Projects where you want to review each agent's changes independently before merging

### Remote Crystl Quest

Quest works over SSH sessions with automatic detection. When the current shard is connected to a remote host, the quest setup panel switches to the remote filesystem and creates shards that SSH to the same host. In sealed mode, git worktrees are created on the remote via `RemoteGitWorktree`. Approval panels and chat messages relay through the SSH tunnel back to the local bridge — no extra setup required.

See [Starting a Quest > Quest over SSH](/docs/starting-a-quest#quest-over-ssh) for details.

## Crystl Quest Lifecycle

1. **Setup** — Pick a party template, choose open or sealed mode, and summon the party
2. **Active** — Agents join the chat, receive instructions, and coordinate through messages
3. **Working** — Agents execute tasks, communicate via `quest_msg`, and the sidebar tracks their status and context health
4. **Complete** — In sealed mode, branches are ready to merge. In open mode, changes are already in the working directory

See [Starting a Quest](/docs/starting-a-quest) for the full setup walkthrough.

## Communication

Agents talk to each other and to you through `quest_msg` and a set of coordination verbs that Crystl adds to each agent's PATH automatically. These are **bash shell commands** — agents should run them via the Bash tool, not by typing them at the prompt.

`quest_msg` stores messages in `.crystl/quest/messages.jsonl` and routes them through the chat panel. The protocol supports three targets:

- **A specific hero** — Routes a direct message to one agent
- **you** — Sends a floating notification to the human user
- **all** — Broadcasts to the #quest channel without injecting into terminals

Additional coordination verbs (`quest_heartbeat`, `quest_task`, `quest_summary`, `quest_handoff`, `quest_announce`) manage task delegation, progress tracking, and context handoffs.

See [Quest Coordination](/docs/quest-coordination) for the full protocol specification.

## Context Health

The sidebar displays each agent's context health as a percentage of their token budget remaining. As agents work, their available context shrinks. When it drops below 50%, the Healer (if present) writes compressed summaries and handoff notes so the quest can continue even as individual agents approach their limits.

Context health is tracked in `.crystl/quest/status.json` and updates in real time.

## The Healer

The Healer is a specialized agent that runs on the Haiku model and monitors the health of the party. When any agent's context usage drops below 50% remaining, the Healer compresses chat history, writes handoff notes, and records settled decisions. This keeps long-running quests from stalling when agents hit their token limits.

See [Quest Heroes](/docs/quest-heroes) for details on the Healer and other specialized roles.

## Side Quests

A **side quest** is a lighter, two-shard variant of Quest. Instead of summoning a party with roles and models, it bridges two shards you already have running — across gems, or even across the local/remote SSH boundary — so they can swap messages through a small chat panel.

Open one with **File → start side quest…** (⌘⇧J), or from the **side quest** tab inside the quest setup panel. The chat panel mirrors the regular Quest chat at a smaller scale: a hero sidebar with crystal-color dots and context lifebars for both participants, a `crystl side quest` logo splash on first open, and `— X joined the side quest —` system rows when the bridge starts.

The protocol differs in one important way: because both shards are already running their agents, Crystl can't inject a system prompt the way it does for full Quests. Instead, the agents learn the protocol from a directive start banner and a per-message reply reminder — they reply to side-quest messages by running the `sidequest_msg` helper via their Bash tool, never as plain chat text.

See [Side Quest](/docs/side-quest) for the full feature breakdown — when to use it, how the protocol works, SSH support, and limitations versus a full quest.

## Settings

Quest settings live in the Crystl settings panel under **crystl quest**:

- **Identity** — Your quest username, user role, personality, and stats
- **Party templates** — Save, edit, and manage reusable team configurations
- **Per-role config** — Instructions, personality, stats, and model selection for each hero
- **Sounds** — Toggle join and send sounds

## Related Docs

- [Starting a Quest](/docs/starting-a-quest) — Setup flow, party templates, and mode selection
- [Side Quest](/docs/side-quest) — Lighter two-shard variant for ad-hoc cross-gem or cross-host chat
- [Quest Chat Panel](/docs/quest-chat) — Chat interface, channels, DMs, and sidebar
- [Quest Coordination](/docs/quest-coordination) — Messaging protocol, @mentions, and sequential delivery
- [Quest Heroes](/docs/quest-heroes) — Hero catalog, RPG stats, and model assignments
- [Isolated Sessions](/docs/isolated-sessions) — The worktree system used by sealed mode
- [Remote SSH Sessions](/docs/remote-ssh) — SSH tunneling for remote quests

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