Use Codex with crystl

Updated October 3, 2026

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.

1. Install Codex

brew install openai/codex/codex

Or with npm:

npm install -g @openai/codex

2. Sign in

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

codex

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

3. Check it runs on its own

codex --version

4. Launch it in crystl

Type it in a shard:

codex

or spawn one:

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 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 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 and resurrect both work. Resuming runs codex resume <id>.
  • Tool calls render as blocks. See 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:

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.

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.

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

See 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