Your agent can drive crystl

The agent in your shard can run the crystl command. That means it can look things up, report on your workspace, and (with a Guild membership) set the workspace up for you.

This is the fastest way to learn crystl. Instead of reading a page about a feature, ask the agent sitting in front of you.

It already knows the commands

crystl maintains a CLI reference inside each gem’s CLAUDE.md or AGENTS.md, so a fresh agent in a fresh gem starts out knowing the commands exist. You do not have to paste anything.

That is the tell agents about the crystl CLI setting, on by default, under settings, agents > defaults. Turning it off stops new writes but leaves blocks already written in place. See agent files.

An agent can also tell whether it is inside crystl at all: the CRYSTL_SHARD environment variable is non-empty in a shard and unset everywhere else.

Ask it to look things up

crystl docs is the whole documentation set, in the terminal, and it is free on every tier.

Ask your agent: “what does crystl’s in gem approval mode actually allow? check crystl docs.”

It runs something like:

crystl docs approval          # search
crystl docs approval-modes    # read the page

Every page carries its crystl.dev URL, so the agent can hand you a link to the same page in your browser.

This is worth knowing before you start reading docs yourself: your agent can answer most crystl questions without you leaving the shard, and it will quote the version of the docs that matches what it can see.

Why the answer is sometimes a little old. The crystl docs CLI caches the index for six hours, so just after a docs update the terminal may serve a slightly older page than the website. Ask again tomorrow, or open the URL.

Ask it what your workspace is doing

Also free, also read-only:

crystl status              # everything, including memory pressure
crystl shards --all        # every shard in every gem, and who needs a person
crystl history search "…"  # find that thing you said three days ago

crystl shards --all is the one to remember. It leads with the shards that want a human, and for agents that report turn ends it says what each one’s last turn was: ❓ asked a question, ✓ declared done, or ⚠ turn failed. A quiet shard is not a finished shard, and that command is how you tell the difference in one call.

Ask your agent: “is anything waiting on me right now?”

Let it hand you things

crystl copy "the thing you need"

Anything you would otherwise drag-select out of wrapped terminal lines goes to a one-click copy bar instead. Free on every tier. A well-behaved agent reaches for this on its own for tokens, URLs, and especially commands it wants you to run.

crystl card "…" gets your attention with a notification, on the desktop and on your phone.

Let it set up your workspace

These are Guild commands, because they change things rather than read them.

crystl open ~/Projects/other-repo        # open a gem
crystl shard create --gem myapp --prompt "add tests"   # spawn a worker
crystl merge                              # integrate a finished worker's branch

The useful moment is mid-task. Your agent notices the bug is actually in a sibling repo, opens that project as its own gem, and carries on, without you stopping to do it by hand.

From there, one session can manage several: see fanout and the orchestration guide.

On the free tier these return 403 guild_required. A good agent will tell you that is what happened rather than working around it.

What it cannot do

• Change what you have not approved. Driving crystl is not a way around approval modes. The same rules apply to an agent’s tool calls whether or not it also uses the CLI.
• Message a crown. In a court, only you may talk to the crown. An agent’s send into one is refused and pointed at the hand instead.
• Speak for another agent. Commands report where they came from, and a shard cannot call off another shard’s vigil watch or answer its questions.

Where to go next

• crystl CLI for the full command reference and the tier breakdown.
• Getting started if you have not created a gem yet.
• Fanout for one agent managing several.