Use Claude Code with crystl

Updated September 18, 2026

Claude Code is the agent crystl was built around first, and the one with the most complete integration. Everything on this page is what you get out of the box.

1. Install Claude Code

The native installer is the one Anthropic recommends, and it keeps itself updated in the background:

curl -fsSL https://claude.ai/install.sh | bash

Homebrew and npm work too:

brew install --cask claude-code          # does not auto-update
npm install -g @anthropic-ai/claude-code  # needs Node.js 22+

You need macOS 13 or later and 4 GB of RAM.

2. Sign in

Run claude and follow the browser prompts:

claude

Claude Code needs a Pro, Max, Team, Enterprise, or Console account. The free claude.ai plan does not include it. If ANTHROPIC_API_KEY is already set in your environment, Claude Code offers to use that key instead of opening a browser.

3. Check it runs on its own

Before involving crystl, confirm the CLI is healthy:

claude --version
claude doctor

claude doctor prints installation and settings diagnostics without starting a session. If it complains, fix that first. A problem here looks exactly like a crystl problem from inside a shard.

4. Launch it in crystl

Open a gem, then either type it in a shard:

claude

or have crystl spawn one for you:

crystl shard create --gem myapp --agent claude --prompt "add tests to the parser"

crystl launches the agent and sends the task as its first message. It works from any shard, so an orchestrating agent can fan work out the same way.

What crystl can do with it

Claude Code supports every integration crystl has.

  • Approvals reach you. Tool requests surface as approval panels, and your auto-approval mode decides what goes through without asking. crystl installs the hooks it needs for this the first time you use Claude in a gem.
  • Turn ends are reported. crystl knows when a turn finished, so crystl shards distinguishes ✓ declared done from ❓ asked a question instead of showing a flat idle. Vigil, crystl wait done, and the phone all read that signal.
  • Conversations are readable and resumable. Sessions land in history search and the chat dock, and a closed shard can be brought back with resurrect.
  • Tool calls render as blocks. Structured tool-call blocks expand in place rather than scrolling past as raw text.
  • crystl can tell it about itself. With tell agents about the crystl CLI on, crystl maintains a CLI primer in each gem’s CLAUDE.md so the agent can drive crystl. See agent files.

Settings

The claude tab under settings, agents enables the agent and sets its options. The generic launch commands live one tab over, under defaults.

Model sizes

Claude Code takes a model with --model. crystl’s model sizes map onto it like this by convention:

crystl agent profile set --agent claude --small haiku --standard sonnet --large opus

Those are aliases rather than pinned ids, so the CLI resolves them to the current version at launch and they never go stale. Teach crystl once and every hero and quest that asks for a size gets the right model.

Troubleshooting

claude works in Terminal but not in a shard. The shard inherits your login shell’s PATH. If you installed with npm into a version-managed Node, check that the same Node is active in a non-interactive shell.

Approvals never appear. Check that claude is enabled in settings, agents > claude, and that your auto-approval mode is not all, which approves everything without asking.

Other agent setup