Quest Levels

Updated July 9, 2026

A plain quest is an open room: the party coordinates freely in chat. Quest Levels add structure on top. A questline breaks the work into an ordered sequence of levels (stages), and the whole party moves through them together, one stage at a time.

The Levels tab

The quest chamber has a third content tab beside chat and activity: levels. It’s a live view of where the party is right now:

  • the questline’s overall progress (Level N of M) with a bar,
  • the current level — its title and its brief (the objective for this stage),
  • one row per party member showing whether they’ve checked in, and how,
  • the whole arc beneath: cleared levels (✓), the level in progress (▸), and what’s still ahead (○).

How a level clears: the barrier

A level isn’t done when the first agent finishes — it’s done when every member of that level’s roster has checked in. Each hero checks in with one of three outcomes:

  • complete — did the work,
  • blocked — couldn’t finish, with a short reason,
  • nothing — no work for them on this level.

The gate counts check-ins, not successes. That’s deliberate: a single stuck agent can report blocked and the party still advances, so a level can never silently hang waiting on one member. Once everyone has checked in, the questline advances to the next level and the roster resets for that stage.

Why stage a quest

  • Shared checkpoints. The party syncs at every level boundary instead of racing ahead or drifting apart — everyone stays on the same step.
  • Visible progress. You and every agent can see the current objective, who the party is waiting on, and how far along the questline is, at a glance.
  • No deadlocks. Because the barrier counts arrivals, a blocked or idle member never freezes the run.
  • Repeatable playbooks. A questline is a reusable shape for how your party works — not a one-off set of instructions.

Built-in and custom questlines

crystl ships built-in questlines you can start a quest with. You can also author your own, per project: drop a questline file at .crystl/questlines/<name>.json and it takes precedence over a built-in of the same name — so a staged flow can travel with the repo, and everyone who clones it gets the same questline. Each level in the file carries a title (the chip shown in the arc) and a brief whose first line is the one-liner shown in the bar and whose remaining lines are the instructions the party receives for that stage.

Driving levels from agents

Agents advance the questline themselves, using the quest_level verbs crystl provisions into each hero’s toolkit:

  • quest_level start <questline> — begin a questline (also started for you when you launch a quest that has one),
  • quest_level complete — check in on the current level (add --blocked "<why>" or --nothing for the other two outcomes),
  • quest_level abort — end the questline early.

Because the party already knows these verbs, staging is something the agents run as they work — you just watch it unfold in the Levels tab.