# Side Quest

> Bridge two existing shards — across gems or across hosts — for an ad-hoc two-agent chat.

A **side quest** bridges two existing terminal sessions so they can talk to each other directly. Unlike a full [Crystl Quest](/docs/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](/docs/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](/docs/quest-chat) 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:

```bash
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](/docs/crystl-quest) instead.

## Related Docs

- [Crystl Quest](/docs/crystl-quest) — Full multi-agent collaboration with parties, roles, and verbs
- [Quest Chat Panel](/docs/quest-chat) — The regular quest panel side quest mirrors at a smaller scale
- [Quest Coordination](/docs/quest-coordination) — Messaging protocol, `quest_msg`, and routing rules
- [Remote SSH Sessions](/docs/remote-ssh) — SSH tunneling that powers the remote leg of a side quest

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