# Use Codex with crystl

> Install OpenAI's Codex CLI, sign in, launch it in a crystl shard, and see what crystl can do with it, including the approval modes that map onto its own launch flags.

Codex is a fully integrated agent in crystl: approvals, history, resume, and turn-end reporting all work. It is also the one agent whose launch flags crystl sets from your [auto-approval mode](/docs/approval-modes/).

## 1. Install Codex

```bash
brew install openai/codex/codex
```

Or with npm:

```bash
npm install -g @openai/codex
```

## 2. Sign in

Run it from a project directory and pick **Sign in with ChatGPT** on first launch:

```bash
codex
```

An API key works too, if you would rather not use a ChatGPT account.

## 3. Check it runs on its own

```bash
codex --version
```

## 4. Launch it in crystl

Type it in a shard:

```bash
codex
```

or spawn one:

```bash
crystl shard create --gem myapp --agent codex --prompt "update the changelog"
```

Spawning is agent-neutral, so a Claude orchestrator can hand work to a Codex worker without you doing anything special.

## What crystl can do with it

- **Approval mode becomes launch flags.** Codex is the one agent where crystl translates your [auto-approval mode](/docs/approval-modes/) into the CLI's own permission arguments at launch, rather than only deciding per request.
- **Edits are understood.** Codex sends edits as `apply_patch` envelopes. Under **in gem**, crystl reads the patch and auto-approves an in-tree add or update while escalating a deletion or an out-of-tree path, the same rule it applies to any other agent's write tools.
- **Turn ends are reported.** `crystl shards` shows `✓ declared done` or `❓ asked a question` rather than a flat `idle`, and [vigil](/docs/vigil/) and `crystl wait done` read the same signal.
- **Conversations are readable and resumable.** Codex mints its own rollout id, which crystl reads back off the transcript, so [history search](/docs/conversation-history/) and [resurrect](/docs/resurrect-shards/) both work. Resuming runs `codex resume <id>`.
- **Tool calls render as blocks.** See [tool calls](/docs/tool-calls/).

crystl installs the hooks it needs into `~/.codex` when the agent is enabled and the binary is present on the machine.

## Settings

The **codex** tab under settings, **agents** enables it and sets its options, including its default model, approval policy, and sandbox mode.

Codex plugin and skill switches are **global** and live on that same tab, not in Gem Settings. Codex has no per-project plugin scoping, unlike Claude Code. See [plugins & skills](/docs/plugins-and-skills/).

## Model sizes

Codex takes a model with `-m` (or `--model`). Its default is `gpt-5.6-sol`, and the ids crystl suggests are `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-5.1-codex-max`, and `gpt-5.1-codex`.

```bash
crystl agent profile set --agent codex --small gpt-5.6-luna --standard gpt-5.6-terra --large gpt-5.6-sol
```

See [model sizes](/docs/model-sizes/) for what small, standard, and large mean.

## Troubleshooting

**Nothing is captured: no approvals, no transcript, no resume.** Codex is probably disabled in settings, **agents > codex**. crystl writes nothing into `~/.codex` for a disabled agent, and a shard running an agent with no hooks looks perfectly healthy while reporting nothing.

**A mid-session plugin change did not take.** Codex needs a manual restart to pick up plugin and skill changes. Claude Code reloads in place; Codex does not.

## Other agent setup

- [Use Claude Code with crystl](/docs/agent-claude-code/)
- [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-codex/