# 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 `❓ needs you` 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.

## Each shard keeps its own Codex session

Codex can run a shared background server and reuse it across launches. That server keeps the environment of whichever shard started it, so a second shard's Codex sends its hooks and runs its tools under the first shard's identity. Conversation capture and restart resume then land in the wrong shard.

So inside a crystl shard, an interactive `codex` launch runs with `--no-daemon`. It gets its own private server, and what it reports belongs to the shard you started it in. You do not have to type anything for this, and `codex resume` and `codex fork` get the same treatment, because both open the same kind of interactive session.

**Subcommands run exactly as you typed them.** `codex agents` and `codex remote-control` exist to talk to the shared server, so they reach it normally. Nothing you can do in an ordinary terminal stops working in a crystl shard.

To put the shared server back for interactive launches too, set `CRYSTL_CODEX_ALLOW_DAEMON=1` in that shard:

```bash
export CRYSTL_CODEX_ALLOW_DAEMON=1
```

With the shared server back, a Codex launch in one shard can report under another shard's identity, and that is what breaks approvals, transcript capture and resume for the session. Set it when you want the shared server more than you want per-shard capture.

An older Codex with no `--no-daemon` flag is left alone. crystl asks your own `codex` binary whether it has the flag before it uses it.

## 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 appear 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/