Use Codex with crystl

Updated September 18, 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 ❓ asked a question 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.

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.

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