Side Quest

Updated April 28, 2026

A side quest bridges two existing terminal sessions so they can talk to each other directly. Unlike a full Crystl Quest, a side quest doesn’t summon new shards or build a party — it pairs two shards you already have running and lets them swap messages through a small chat panel. The two shards can live in different gems and even on different hosts (one local, one over SSH).

When to Use It

Use a side quest when:

  • You’re already mid-task in two separate shards and want them to coordinate without setting up a full party
  • You want one shard on your laptop to consult a shard running on a remote machine over SSH
  • You need a quick collaboration channel between agents without committing to roles, models, or worktree isolation

For longer multi-agent work — especially anything that benefits from roles, lifebar tracking on more than two shards, sealed branches, or the full Quest verb set — use a regular Crystl Quest instead.

Starting a Side Quest

There are two ways to open one:

  • Menu: File → start side quest… (⌘⇧J)
  • Quest setup panel: open the quest panel from the gem toolbar, then switch to the side quest tab

The setup panel lists every shard currently open across every gem, including remote SSH shards. Pick two shards and start. If a side quest is already active, Crystl asks before tearing it down so the other side gets a clean end banner.

The Chat Panel

The side-quest panel mirrors the regular Quest Chat Panel at a smaller scale. On open, it plays the crystl side quest logo splash with a CRT-style fade-in, then shows two — X joined the side quest — system rows (one per participant) at the bottom of the chat area.

The right sidebar carries a PARTY list with one row per participant:

  • Crystal-color dot — matches the shard’s signature color
  • Name in the form shard — gem (e.g. diamond — myapp)
  • Status — ready, working, or idle, identical to Quest’s status states
  • Lifebar — the same context-budget bar Quest uses (~N turns left), driven by the shard’s agentInputTokens / turnMetrics

Bottom of the panel is an input field where you can speak as the user — anything you type lands as [side-quest from user] … in both terminals.

The Protocol

A side quest is started against agents that are already running, so Crystl can’t slot a --append-system-prompt block the way a regular Quest does. Instead the protocol is communicated through two channels:

  1. Start banner — when the bridge opens, each terminal receives a long bracketed-paste block declaring the rule:

    [side-quest active with <other>] PROTOCOL: you are now bridged to <other>.
To reply to any [side-quest from ...] message, run this exact bash command
via your Bash tool — never reply with plain chat text:
<abs path>/sidequest_msg "your reply". The script is the only channel
back to the other side; chat replies are invisible. Wait for the first
[side-quest from ...] message before doing anything.

  2. Per-message reminder — every routed message carries a tail reply hint so the protocol stays in the agent’s working context turn over turn:

    [side-quest from user] hello [reply via: <abs path>/sidequest_msg "..."]

If an agent ever drifts back to plain-chat replies, the next routed message refreshes the protocol.

sidequest_msg

sidequest_msg is the shell helper Crystl drops onto each shard’s PATH when the side quest starts. The agent calls it from its Bash tool — never as a function/tool call:

sidequest_msg "your reply text"

For local shards, the script lives at <projectDir>/.crystl/sidequests/bin-<shard>/sidequest_msg and writes JSONL lines to ~/Library/Application Support/Crystl/sidequests/<questId>.jsonl. The host process tails that file and routes new lines through the chat panel.

For remote SSH shards, the script lives at $HOME/.crystl-sidequests/bin-<shard>/sidequest_msg and posts each line to the host bridge’s POST /sidequest/message route over the SSH reverse tunnel — the same return path quest_msg uses for full quests.

The agents always reach the helper via its absolute path because Claude’s process environment was frozen before the side quest installed the script onto PATH, so subshells spawned by the Bash tool wouldn’t otherwise see it.

Side Quest over SSH

Side quests work across the local/remote boundary in either direction. Pick a local shard and a remote SSH shard and start — Crystl installs the local helper into the project’s .crystl/sidequests/ and heredocs the remote helper onto the SSH host. Messages flow through the same JSONL file watcher locally and through the bridge route remotely. No extra setup is required as long as the SSH ControlMaster socket is alive.

Ending a Side Quest

A side quest ends in any of these ways:

  • Click End in the side-quest tab of the quest setup panel
  • Start a new side quest (Crystl asks before closing the existing one)
  • Either of the two participating shards closes (or its gem closes)

On close, each terminal gets a [side-quest with <other> ended] banner, the helper script is removed, and the JSONL log is deleted. The chat panel dismisses.

Limitations

A side quest is intentionally simpler than a full quest:

  • Two participants only — there’s no third agent or DM routing
  • No roles or models — participants keep the agent and model they’re already running
  • No sealed mode — agents work in their existing directory or worktree; there’s no automatic branch creation
  • No verb suite — only sidequest_msg is provided; quest_task, quest_summary, and the rest are Quest-only
  • One side quest at a time — Crystl runs a single global bridge per app instance

For anything that outgrows these limits, end the side quest and start a regular Crystl Quest instead.