Court: the crown and the hand

Updated August 2, 2026

A court is a standing hierarchy you talk to through one front door. You talk to the crown. The crown hands work to the hand. The hand spawns workers and merges what they finish. Officers sit under the hand holding remits that persist.

It exists to solve one specific annoyance: the agent you want to talk to is busy.

Why the crown is idle on purpose

A crystl shard is single-threaded from your side. Anything you type while the agent is mid-turn queues up behind that turn and waits. So an agent doing real work cannot also be the agent you talk to, no matter how you prompt it.

The crown answers that by holding no tasks. It owns the conversation and owns none of the work, which is what keeps it free to answer. “Always available” really means “always idle,” and the only way to stay idle is to hold nothing.

That only holds if nothing can drag it into work, which is why the crown has exactly one inbound edge, and it’s you.

Nothing but you may send to a crown

An agent’s send or notify into a crowned shard is refused, and the refusal points it at the hand instead. The moment a finished worker can wake the crown, your conversation gets interrupted and the crown is just another busy agent.

The crown learns everything else by reading live state rather than being reported to. Ask it what’s happening and it looks; it doesn’t wait to be told.

Your own input is untouched everywhere you actually use it. Typing in the terminal, the chat dock, the phone, and crystl send from an ordinary shell all reach the crown normally. The restriction is on agents, not on you.

The three seats

Crown. The shard you talk to. Owns the conversation, owns no work. Usually this is the shard you were already in.

Hand. The crown’s orchestrator, an anointed shard. It spawns workers, keeps every one of them busy, and reviews and merges their branches in dependency order. The crown dispatches to it; it never reports back upward, because the crown reads state instead.

Officers. Standing seats under the hand, each with a --charge: a remit that persists where a worker’s task would end. A worker exists to finish one thing. An officer keeps holding its brief, so “keep the docs current” stays somebody’s job rather than becoming a task you have to remember to re-file.

How court differs from its neighbours

crystl has several ways to run more than one agent, and they are not interchangeable:

What it is
PartyA saved roster of heroes
QuestPeers in a shared chat, no leader
GauntletA one-shot audit crew
CourtA standing hierarchy with a single front door

Court is the only one that persists, and the only one with one way in. A quest is deliberately flat: agents talk to each other as peers and you watch. A court is deliberately not: everything reaches you through the crown.

Convening one

crystl court "ship the 3.0 release"

That’s the default subcommand, so crystl court "<goal>" and crystl court convene "<goal>" do the same thing.

Convening prefers to crown the shard you’re already in, because crowning in place transfers no context: you’re already talking to it, and it already knows what you’ve been doing. If no shard can be crowned in place, a crown hero is summoned instead and your goal rides along as its opening task.

An existing hand is reused rather than duplicated. A second one would give the crown two places to dispatch to, which defeats the point.

Each officer is briefed to report to the hand by its real shard name, so it knows where its output goes.

Seat officers when you convene, or later:

crystl court convene "ship the 3.0 release" --with scribe --with sentinel
crystl court add scribe --charge "keep the docs current"
crystl court dismiss scribe

crystl court --dry-run prints the plan and seats nobody, which is the cheap way to see what you’re about to create.

Checking on it

crystl court status

Shows the seated crown, hand, officers, and worker count. It’s composed entirely from a read, so it’s free on every tier. Convene, add, dismiss, and end create or close shards, so those need a Guild membership.

Dispatching to a seat

The hand dispatches to officers with crystl send, and should use --wait when it does. An officer already working is the normal case, and --wait treats a message accepted into the agent’s own input queue as delivered rather than reporting nothing. Exit 0 is delivered, 3 is queued behind the officer’s current turn (don’t re-send, or the charge arrives twice), 1 is no receipt from an idle shard and is safe to retry.

A seat restored after a crystl restart may not have its agent running yet. It reads as ⏸ no agent — relaunches on dispatch in crystl shards and starts its agent on its own conversation when the hand dispatches to it; a seat whose relaunch failed says ⚠ no agent — relaunch failed instead of accepting work it can’t do.

Ending it

crystl court end
crystl court end --keep-staff    # take the crown off, leave the staff running

court end dismisses the officers, then the hand, in that order, so officers are never left addressing a shard that no longer exists. Then it uncrowns the crown.

The crown is usually your own shard, so it’s never closed, only uncrowned. You get your ordinary shard back with its history intact. At a terminal it names the shards it’s about to close and asks first; a non-interactive caller (no tty, --json, or --force) proceeds without asking.

Standing courts per project

Optional profiles live in .crystl/court.json, mirroring .crystl/gauntlet.json:

{
  "profiles": {
    "default": {
      "goal": "keep the release train moving",
      "officers": [
        { "hero": "scribe", "charge": "keep the docs current" }
      ]
    }
  }
}

A --with flag is added on top of the profile’s officers rather than replacing them. The profile is your standing court; the flags are what you want for this particular convene.