# Use Claude Code with crystl

> Install Claude Code, sign in, launch it in a crystl shard, and see what crystl can do with it: approvals, history, resume, and model sizes.

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](/docs/fanout/) 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](/docs/approval-modes/), and your [auto-approval mode](/docs/approval-modes/) 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](/docs/vigil/), `crystl wait done`, and the phone all read that signal.
- **Conversations are readable and resumable.** Sessions land in [history search](/docs/conversation-history/) and the chat dock, and a closed shard can be brought back with [resurrect](/docs/resurrect-shards/).
- **Tool calls render as blocks.** Structured [tool-call blocks](/docs/tool-calls/) 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](/docs/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](/docs/model-sizes/) 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](/docs/hero-shards/) and [quest](/docs/crystl-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](/docs/approval-modes/) is not **all**, which approves everything without asking.

## Other agent setup

- [Use Codex with crystl](/docs/agent-codex/)
- [Use Antigravity CLI with crystl](/docs/agent-antigravity/)
- [Use Kimi Code with crystl](/docs/agent-kimi/)
- [Open models](/docs/open-models/) to run any of them on your own hardware

---
Source: https://crystl.dev/docs/agent-claude-code/