the crystl guild's
book of spells
Master crystl with a grimoire of powerful prompts. Summon heroes, assemble a party, revive shards, and complete epic quests.
Cross-Shard Telekinesis
Reach into a sibling shard without leaving your own.
Check on the agent working in my `api` shard. Read its screen, and if it's stuck waiting on me, tell me what it needs — then send it the answer so it keeps going.
- Steer another agent without switching tabs
- Unblock a worker that paused on a question
- Hand a fact or correction to a sibling mid-task
crystl shards --gem myapp see what is open and who is ⏸ awaiting input crystl screen --gem myapp --shard api read its terminal crystl send --gem myapp --shard api "use the v2 endpoint" type into it 
Resurrect the Fallen
Bring a shard back from the dead — name, colour, and session intact.
I closed a shard by mistake. List what can be brought back in this gem and resurrect the most recent one.
- Recover a shard closed in error
- Bring back a worktree branch you still need
- Restore an agent session mid-flight
crystl resurrect list --gem myapp what can return (free) crystl resurrect --gem myapp bring back the most recent crystl resurrect --gem myapp --shard opal or a specific one by name 
Anoint a Ruler
Crown one agent as orchestrator and let it spawn a court of workers.
You are the orchestrator now. Spin up three new shards in this gem — one to write tests, one for docs, one for the API — give each its task, watch them, and report back when they land.
- Turn one agent into a conductor of many
- Parallelise a feature across focused workers
- Keep oversight in one shard while work fans out
crystl shard create --gem myapp --prompt "write tests for auth" spawn a worker with a task crystl shard create --gem myapp --agent codex --prompt "update the docs" pick the agent crystl status watch every shard, ⏸ flags included 
Squash Every Bug
Loose the seeker on every bug at once — one isolated shard each, merge what passes.
Here are five bugs. Summon the seeker — our debugging specialist — into a fresh isolated shard for each one, brief each on its bug, watch them work, unblock any that stall, and merge the fixes once they're green.
- Put a debugging specialist on every bug at once
- Keep each fix in its own worktree, conflict-free
- Babysit the whole swarm from one seat
crystl shard create --gem myapp --hero seeker --crystal-name bug-login --isolated --prompt "fix the login redirect loop" a named debugging shard with its opening task crystl shard create --gem myapp --hero seeker --crystal-name bug-settings --isolated --prompt "fix the settings crash" repeat once per bug with a unique shard name crystl merge --gem myapp --shard bug-login land each fix once it is green 
Summon a Hero
Call a named specialist — its own role, persona, agent, and model.
Summon the ranger into this gem and have it scout the repo for dead code and unused exports.
- Drop a specialist persona onto a task
- Use a built-in (wizard, warrior, ranger…) or a project-local hero
- Get a focused expert instead of a blank agent
crystl hero list --gem myapp who can be summoned (free) crystl hero summon ranger --gem myapp --prompt "scout for dead code" call and brief the specialist crystl hero summon wizard --gem myapp --isolated --model gpt-5.1-codex-max summon into a clean worktree with a model override 
Run the Gauntlet
Launch a release-readiness crew: two seekers, one monk, and a scribe.
Before this branch merges, run the gauntlet for release readiness. Have the seekers hunt bugs, the monk run the checks, and the scribe give me the combined verdict.
- Run a final release-readiness pass
- Create isolated reviewer shards with one command
- Get a consolidated PASS/WARN/FAIL/BLOCKED verdict
crystl gauntlet "release readiness" --gem myapp spawn two Seekers, one Monk, and one Scribe crystl gauntlet --gem myapp --check "swift test" --check "npm test" tell the Monk which checks matter crystl screen --gem myapp --shard gauntlet-scribe read the consolidated verdict 
Begin the Quest
Seat a party of heroes and launch them on a shared quest.
Build a party called 'ship-it' with the warrior, scribe, and skeptic, then start a quest with them on this gem to land the release.
- Assemble a recurring multi-agent crew
- Run role-played agents in one shared chat
- Commit the party to the repo so the team inherits it
crystl party create ship-it --heroes warrior,scribe,skeptic --gem myapp seat the party crystl quest start --party ship-it --gem myapp launch the quest crystl party create ship-it --heroes warrior,scribe --local --local ships it with the repo 
Scry the Past
Gaze into a shard’s past and see every move that led it here.
Pull the transcript from the agent in the `auth` shard so I can see how it got here, then summarise the key decisions it made.
- Recover context from an earlier session
- Audit the reasoning behind a change
- Catch up on a worker you left running
crystl history --gem myapp --shard auth structured transcript: turns + tool calls crystl screen --gem myapp --shard auth or just the live terminal 
Merge the Realms
Weave a finished shard’s work back into main.
The isolated `refactor` shard is done and the tests are green. Merge its branch into main for me.
- Land an isolated shard’s work
- Close out a worktree branch cleanly
- Finish a parallel task without leaving your seat
crystl merge --gem myapp --shard refactor merge the worktree branch into main Conjure the Copy-Stone
Drop text into the one-click copy bar instead of making me select it.
Generate the production deploy command and drop it in the copy bar so I can review and paste it in one click.
- Hand over a token, URL, or command without drag-selecting
- Stack several items as numbered copy tabs
- Free on every tier — no Guild needed
crystl copy "npm run deploy" --label "deploy" one tab, named cat key.txt | crystl copy pipe anything in 
Etch a Rune
Pin a snippet to a facet button — a one-click insert in your terminal.
I keep re-running the same test command. Pin it to a facet button so it's one click from now on.
- Bind a command you re-run constantly
- Keep a frequent prompt one tap away
- Bind to a slot so it actually shows in the bar
crystl facet add "test" "npm test" --slot 1 --action submit runs on click crystl facet list see what is bound where crystl facet remove abc123 tidy up when it stops earning its slot 
Read the Omens
Watch every gem for approval prompts and answer the moment one appears.
Watch for approval prompts across my gems and tell me the instant one needs a decision. When the deploy approval comes up, approve it.
- Never let a worker sit stalled on an approval
- Block until something actually needs you
- Approve or deny pending tool calls in flight
crystl wait pending --timeout 600 block until a request appears (no polling) crystl pending list what is waiting (free) crystl approve 7 or crystl deny 7 
Watch the Constellation
Read the whole sky of live events — know the moment a worker blocks, asks, or finishes.
Watch all live crystl events and tell me the instant a worker becomes blocked, asks a question, or finishes its turn.
- Monitor a whole fan-out without polling screens
- Catch a worker parked on an in-terminal prompt
- Know when a shard goes from working to idle
crystl events --type pending_changed,askuser_changed,agent_status_changed,notification stream the lifecycle as JSON lines crystl wait awaiting --gem myapp block until a worker parks on a prompt crystl wait idle --gem myapp --shard opal block until a shard finishes a turn 
Consult the Mortal
Field an agent’s structured question and answer it on your terms.
Wait for the next question from any agent, summarise what it’s asking, and answer it once I confirm.
- Handle AskUserQuestion prompts, not just tool approvals
- Answer by option label or free text
- Keep a fan-out moving when a worker needs a decision
crystl wait askuser --timeout 600 block until a question opens crystl askuser list open questions (free) crystl askuser answer 12 "Use the xterm renderer." answer by text or option label 
Bind the Workbench
Turn a loose task list into a living plan the agent keeps current.
Turn this task list into a Workbench plan, mark the first item in progress, and keep it updated as you work.
- Give a fan-out a shared, visible plan
- Watch progress flip in the Workbench panel live
- Let the agent check items off as it lands them
crystl workbench list --gem myapp read the task list (free) crystl workbench add "fix SSH notifications" --section "Now" add a task crystl workbench start 3 mark task 3 in progress [~] crystl workbench check 3 mark task 3 done [x] 
Divine the Malady
Take crystl’s pulse — CLI, bridge, and hooks — before you debug any deeper.
Before we dig into this, check that crystl itself is healthy — the CLI, the bridge, and the hooks — and tell me anything that looks off.
- Rule out crystl itself before chasing a bug
- Diagnose missing approvals or notifications
- Sanity-check the bridge and hook wiring
crystl doctor check CLI, bridge, and hook wiring (free) crystl doctor --json machine-readable health for the agent to parse 
Bridge the Far Tower
Reconnect a remote shard’s bridge when the tunnel goes dark.
My SSH shard stopped sending notifications. Check the bridge route, and if the tunnel is blocked, set a direct bridge address.
- Revive a remote shard that went quiet
- Point the bridge at a direct address when the tunnel fails
- Clear the override once the tunnel is back
crystl ssh bridge-address 100.64.0.1:19280 set a direct bridge address crystl ssh bridge-address "" clear the override 
Send a Raven
Turn a hunted-down bug into a report the team can actually act on.
Investigate this crystl bug, write a plain-language report with reproduction steps and your technical hypothesis, then file it.
- File a real bug report, not a one-liner
- Send an idea straight to the crystl team
- Free on every tier
crystl report bug "SSH notifications stop after reconnect" --email [email protected] file a bug (free) crystl report idea "add a Workbench spell to the Book of Spells" send an idea Not a guild member yet?
The control spells — spawning shards, summoning heroes, assembling parties, merging — are Guild magic. Reads and the copy-stone are free for everyone.
join the guild