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: ```bash curl -fsSL https://claude.ai/install.sh | bash ``` Homebrew and npm work too: ```bash 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: ```bash 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: ```bash 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: ```bash claude ``` or have crystl spawn one for you: ```bash 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](/content/docs/fanout/index.html) 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](/content/docs/approval-modes/index.html), and your [auto-approval mode](/content/docs/approval-modes/index.html) 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](/content/docs/vigil/index.html), `crystl wait done`, and the phone all read that signal. - **Conversations are readable and resumable.** Sessions land in [history search](/content/docs/conversation-history/index.html) and the chat dock, and a closed shard can be brought back with [resurrect](/content/docs/resurrect-shards/index.html). - **Tool calls render as blocks.** Structured [tool-call blocks](/content/docs/tool-calls/index.html) 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](/content/docs/agent-files/index.html). ## 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](/content/docs/model-sizes/index.html) map onto it like this by convention: ```bash 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](/content/docs/hero-shards/index.html) and [quest](/content/docs/crystl-quest/index.html) 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`](/content/docs/cli/#agent-account/index.html). 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](/content/docs/open-models/index.html). 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](/content/docs/agent-activity-panel/index.html). Hover over it to see when each limit resets. - [`crystl usage`](/content/docs/cli/#usage/index.html), 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](/content/docs/approval-modes/index.html) is not **all**, which approves everything without asking. ## Other agent setup - [Use Codex with crystl](/content/docs/agent-codex/index.html) - [Use Antigravity CLI with crystl](/content/docs/agent-antigravity/index.html) - [Use Kimi Code with crystl](/content/docs/agent-kimi/index.html) - [Open models](/content/docs/open-models/index.html) to run any of them on your own hardware `esc` `↑` `↓` navigate`↵` open`esc` close