Multi-Agent Development with Crystl Quest

Running one AI coding agent at a time is productive. Running three or four in parallel — each focused on a different part of the system — is a different category of output entirely. Multi-agent development is the practice of coordinating multiple AI agents on a single codebase simultaneously. Crystl Quest is how you do it without the agents tripping over each other.

What is multi-agent development?

Single-agent development is serial: give Claude Code a task, wait for it to finish, review the output, give it the next task. Your throughput is capped by one agent’s speed.

Multi-agent development breaks this constraint. Instead of one agent doing everything sequentially, you run several in parallel, each specializing in a different area. One handles frontend components. Another builds API endpoints. A third writes tests. A fourth reviews code as the others produce it.

While the backend agent is setting up database queries, the frontend agent is building the UI that will consume them. While both are coding, the QA agent is writing tests for features they’ve already finished. Work that would take a full day in serial can land in a couple of hours.

The hard part has never been running multiple Claude Code sessions. You can open four terminals and start four agents right now. The hard part is coordination: preventing file conflicts, duplicated work, and wasted effort on tasks another agent already finished. That coordination layer is what Crystl Quest provides.

How Crystl Quest works

Crystl Quest is the multi-agent collaboration system. You assemble a party of AI agents, give them a shared objective, and Quest handles communication, file isolation, and progress tracking.

Each agent is called a hero and runs in its own terminal shard within the same project gem. Heroes have names, functional roles, RPG-inspired stats, and Claude model assignments. Crystl spins up shards for each hero, injects role-specific system prompts, and opens a chat panel where everyone communicates.

Quest supports two collaboration modes:

Open mode

All agents share the same working directory. When one agent creates a file or edits a function, every other agent sees the change immediately. No merge step at the end — everyone is already working on the same files.

Open mode works well when agents focus on different areas of the codebase. A frontend agent editing React components and a backend agent modifying API routes rarely touch the same files. But if two agents edit the same file simultaneously, one will overwrite the other. Use open mode when you can clearly partition the work.

Sealed mode

Each agent gets an isolated git worktree on its own branch — a full copy of your repository checked out on a separate branch, sharing the same git history. Agents can’t see each other’s changes and can’t conflict.

Project: ~/projects/my-app (main branch)
  diamond     -- main working directory (you)
  ⎇ wizard    -- .crystl/worktrees/wizard    (branch: crystl/wizard)
  ⎇ ranger    -- .crystl/worktrees/ranger    (branch: crystl/ranger)
  ⎇ rogue     -- .crystl/worktrees/rogue     (branch: crystl/rogue)

When the quest is done, merge each agent’s branch back to main through the Isolation panel or the close prompt. Crystl handles the rebase and fast-forward merge automatically.

Sealed mode is the safer choice for most multi-agent work. Clean git history, no file conflicts, and the ability to review or discard each agent’s work independently.

Heroes and roles

Every agent in a quest takes on a hero identity. The role, stats, and personality are injected into the agent’s system prompt and shape how it behaves.

The hero catalog

Crystl ships with built-in heroes:

Hero	Role	Model	What it does
Wizard	UI/UX	Sonnet	Interface design, user experience, visual structure
Warrior	Designer	Sonnet	Persistent implementer, pushes through hard problems
Ranger	Frontend	Sonnet	Fast frontend work, concise code, quick iterations
Rogue	Backend	Sonnet	API routes, database queries, server logic
Healer	Context Health	Haiku	Monitors party health, writes handoff notes
Paladin	Researcher	Opus	Deep research, architecture analysis
Bard	Reviewer	Sonnet	Code review, thorough feedback
Druid	Planner	Opus	Project planning, task decomposition
Warlock	SEO	Sonnet	Meta tags, structured data, content optimization
Monk	QA	Haiku	Unit tests, integration tests, test suites

RPG stats

Each hero has four stats on a 1-10 scale: Strength (persistence), Intelligence (depth of analysis), Wisdom (judgment), and Dexterity (speed and conciseness). These translate into behavioral modifiers in the system prompt.

A Ranger with DEX 8 writes code quickly and communicates in short bursts. A Paladin with INT 10 researches thoroughly before writing a single line. The stats measurably change how the agent operates.

Model assignments

Most heroes run on Sonnet for balanced speed and capability. The Paladin and Druid run on Opus for deeper reasoning. The Healer and Monk run on Haiku for speed and low cost — their tasks involve frequent lightweight operations rather than deep analysis. You can override the model for any hero in Settings > crystl quest > Per-role config.

Custom heroes

The built-in catalog is a starting point. You can create custom heroes with any name, role, stats, and personality in Settings > crystl quest > Party templates. They work identically to built-in ones. If your project needs a Database Migration specialist or an Accessibility auditor, create a hero for it.

Crystl Quest chat

The quest chat panel is where all coordination happens. It opens when you start a quest and works like an IRC channel with structured message routing.

Message routing

Messages flow through three channels:

• #quest (broadcast) — Messages without an @mention go to the main channel. Quest delivers them to agents one at a time in priority order (sequential delivery) so each agent sees what the previous one did.

• @name (direct message) — Type @wizard followed by your message to route it to Wizard only. The message is injected directly into Wizard’s terminal.

• @you (agent-to-human) — When an agent needs your attention, it targets “you”. Crystl triggers a floating notification so you see it immediately, even if the quest panel is closed.

Agent-to-agent communication

Agents communicate using the quest_msg shell function, which Crystl adds to each agent’s PATH:

quest_msg "ranger" "API endpoints are ready -- you can start wiring components"
quest_msg "all" "Database migrations complete"
quest_msg "you" "Should the cache expire after 1 hour or 24 hours?"

Messages are stored in .crystl/quest/messages.jsonl and routed through the chat panel in real time.

Context health

The sidebar displays each agent’s remaining context budget as a health bar. When an agent drops below 50%, the Healer (if present) automatically writes compressed summaries (QUEST-LOG.md), handoff notes (HANDOFF.md), and settled decisions (DECISIONS.md) so the quest survives agents hitting their token limits. No prompting needed — the Healer watches status and acts automatically.

Crystl Quest over SSH

Crystl Quest works on remote servers. When you SSH into a remote machine from a Crystl terminal, Quest auto-detects the SSH session and adapts.

In sealed mode, worktrees are created on the remote host via the ControlMaster connection. No local state is created — everything lives on the remote under .crystl/worktrees/. Merge and rebase actions execute remotely through the same connection. Approval panels relay back through the SSH tunnel to your local Crystl bridge.

From your perspective, remote quests look and feel identical to local ones. Enable auto-tunneling in Settings > Claude > Remote SSH to make this work transparently.

Practical workflow

1. Open your project

Open a gem (project tab) in Crystl pointed at your repository.

2. Start the quest

Click the Quest button (crossed swords icon) in the shard bar.

3. Choose a party template

Select from built-in templates or a custom one:

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

4. Pick open or sealed mode

Open for shared-directory collaboration. Sealed for worktree-isolated branches. When in doubt, choose sealed.

5. Summon the party

Click Summon Party. Crystl creates shards for each hero with staggered timing. In sealed mode, each shard gets its own worktree on a dedicated branch.

6. Give instructions

Type your objective in the quest chat. Quest delivers it to agents sequentially — the first agent acts, then the next agent gets it with full context of what happened before.

7. Monitor and steer

Watch the chat panel as agents coordinate. Check context health in the sidebar. Use @mentions to redirect individual agents.

8. Merge and finish

In open mode, changes are already in your working directory. In sealed mode, close each shard to get the merge prompt: Merge to Main, Keep Branch, or Discard.

When to use open vs sealed mode

Open mode is best for rapid prototyping, exploratory work, and tasks where agents touch clearly separate files. No merge step means faster iteration. The tradeoff is risk: if two agents edit the same file, one overwrites the other.

Sealed mode is best for parallel feature work, projects with database migrations or schema files, and any task where you’d want to review each agent’s changes independently. The overhead is small (worktree creation plus a merge step at the end), and you get full control over what lands on main. For most multi-agent work beyond quick prototyping, sealed mode is the better default.

Tips for effective quests

Put architects before implementers. Party template order determines sequential delivery order. Put the Druid (Planner) before the Ranger (Frontend) so the plan is in place before implementation starts.

Include a Healer in long quests. The Healer’s automatic summarization prevents quest stalls when agents approach their token limits. It runs on Haiku, so the cost is minimal.

Use sealed mode for anything you’d want to code-review. Each agent’s branch is a self-contained diff. Much easier to evaluate than interleaved changes in a shared directory.

DM agents with specific, scoped tasks. Broadcasting vague instructions leads to agents stepping on each other. Use @mentions to give each agent a clear, bounded piece of work.

Check context health before sending big instructions. If an agent is at 40% context, a large new task will push it further. Let the Healer do a handoff first, or start a fresh shard.