Use Claude Code with crystl · crystl Docs

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 cards, 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 ❓ needs you 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 are 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.

Accounts

An account is one login for an agent, kept in its own folder. Claude Code and Codex can each have several, so a work login and a personal one can live on the same Mac.

Add an account first. Settings, agents > agents lists your accounts under ACCOUNTS, each with its folder. + add claude account makes a new folder and opens a shard that starts Claude Code there. Type /login in that shard to finish. To do the same from the terminal, see crystl agent account.

Then type claude@work in any shard to run Claude Code on the work account. The same claude@label form can also name a model endpoint. crystl keeps the names unique, and crystl agent account list and crystl endpoint list show which is which.

In a shard not started on an account, a plain claude uses your usual login, the default account. A shard started on an account keeps it, so a plain claude typed later in that shard stays on the same login. When crystl restarts, the shard comes back on its account.

Once you have an account, File > new shard lists each agent with its accounts, such as claude · work.

The line at the bottom of each shard shows the account it runs on. For the default account, it shows the short form of your email when you are signed in, such as you for you@example.com. Click it to change the label, add another account, or view your accounts. The default account opens the same menu.

Have you run Claude Code from another folder with CLAUDE_CONFIG_DIR? crystl notices the first time you start Claude Code in a shard with CLAUDE_CONFIG_DIR set to that folder. A card asks whether to save it to your accounts.

crystl never reads or stores your login. The agent does its own login and keeps its own credential. crystl stores only each account’s label and folder. Removing an account takes it out of crystl, and its folder and login stay on disk.

Usage

crystl shows how much of your Claude plan’s five-hour and seven-day limits you have used, and when each one resets. You see it in three places:

• the line at the bottom of each shard, such as 5h 42% · 7d 18% used
• the usage meter at the bottom of the agent activity panel. Hover over it to see when each limit resets.
• crystl usage, which an agent can run before it starts more workers

On a Pro or Max plan, Claude Code passes these numbers to its statusline command after its first reply. crystl reads them there:

• An empty statusline. crystl fills it by itself in every account’s folder. It prints nothing, so Claude Code still shows no statusline.
• Your own statusline. crystl never changes it. Settings, agents > claude shows a new statusline command built from yours, with a copy line button. Replace your command with it. It runs crystl’s step first, then yours, and passes Claude Code’s input to your statusline unchanged. If an account’s folder has your own statusline, paste the line as statusLine.command in that folder’s settings.json. crystl usage prints the same line. Until you make the change, the usage meter shows no Claude usage.

The setting is show Claude plan usage (read from Claude Code’s statusline), under USAGE on settings, agents > claude. It is on by default. Turning it off removes the step.

crystl never reads or stores your login for this. It reads only the numbers Claude Code already passes to its statusline, and it never calls Anthropic for them.

A worker that hits a limit stops until that limit resets, and its row in the agent activity panel says when that is. crystl never moves work to another account to get around a limit.

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

• Use Codex with crystl
• Use Antigravity CLI with crystl
• Use Kimi Code with crystl
• Open models to run any of them on your own hardware

esc

↑ ↓ navigate↵ openesc close