# Codex Cheat Sheet

Codex surfaces, model and effort selection, config.toml and AGENTS.md, extension points, permissions and sandboxing, environments, SDK and integrations, security, the GPT-5.4 retirement map and governance.

import { Tabs, TabItem, Steps } from '@prosefly/astro-components';

Codex is OpenAI's coding agent, delivered across a CLI, IDE extension, cloud and app surfaces sharing one configuration. This is the reference for the [Codex track](/openai/codex/). Re-verify commands, models and retirement dates against [developers.openai.com/codex](https://developers.openai.com/codex) and [developers.openai.com/codex/models](https://developers.openai.com/codex/models).

## Surfaces

| Surface | What it is |
| --- | --- |
| ChatGPT desktop app | Codex inside the desktop client |
| ChatGPT Work on the web | Codex in the web workspace |
| Codex CLI | Terminal client (`codex`, `codex exec`) |
| Codex IDE extension | In-editor agent |
| Codex cloud | Managed cloud execution |
| Codex Micro | Lightweight surface |
| Integrations | Slack, GitHub, GitLab (beta), Linear |
| GitHub Action | Codex in CI |
| Codex SDK | Programmatic Codex |
| App Server | Serve Codex to apps |
| Non-interactive mode | `codex exec` for scripts/CI |

## Models and effort selection

Codex runs `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, plus `gpt-5.3-codex-spark` (a text-only research preview for near-instant iteration, on ChatGPT Pro). `gpt-5.5` and `gpt-5.4` remain as "other models".

```bash
codex --model gpt-5.6            # start with an explicit model
codex -m gpt-5.6                 # short flag
codex exec -m gpt-5.6 "fix the failing test in auth/"   # non-interactive
```

Inside an interactive session, `/model` switches model and effort.

### The reasoning ladder (CLI)

```text
Low → Medium (default) → High → Extra high → Max → Ultra
                                              │      │
                                    more thinking    automatic delegation to
                                    on one task      subagents in parallel
```

| Level | Meaning |
| --- | --- |
| Low / Medium / High / Extra high | Increasing deliberation on a single task |
| **Max** | Maximum thinking time on **one** task |
| **Ultra** | Automatic delegation to **subagents** running in parallel |

**Max vs Ultra** is the distinction to hold: Max thinks harder on one problem; Ultra fans the problem out to parallel subagents. In GUI clients the levels read Light/Medium/High/Extra High, and the Astra rollout exposes Power options (Terra Light, Sol Light, Sol Medium, Astra Light, Astra Medium, Astra Extra High). If Ultra is absent from the picker, enable it via Settings → Configuration → "Ultra in model picker slider".

## config.toml

One shared `config.toml` serves the desktop app, CLI and IDE extension. Config has basics/advanced/reference levels, environment variables and a sample config.

```toml
# ~/.codex/config.toml (illustrative — check the reference for the full key list)
model = "gpt-5.6"

[features]
context_management.experimental_mode = true   # Astra cross-context notes; opt-in
```

:::caution[Experimental context management]
`features.context_management.experimental_mode = true` lets Astra keep notes across context windows and search earlier messages/tool results in the same task. It is **opt-in**, and at launch it is **ChatGPT Plus/Pro sign-in only** — not Business, Enterprise, or API-key sign-in.
:::

## AGENTS.md

`AGENTS.md` is the standing instruction file Codex reads for a repository: how to build, test, and behave in this codebase. Keep it specific and current.

```markdown
# AGENTS.md

## Build & test
- Install: `pnpm install`
- Test: `pnpm test` — all tests must pass before you stop
- Lint: `pnpm lint` — fix, do not disable rules

## Conventions
- TypeScript strict mode; no `any`
- Prefer small, reviewable diffs
- Never edit files under `vendor/`

## Boundaries
- Do not push to `main`
- Ask for approval before deleting files
```

Agent configuration also covers **subagents**, **speed**, and **rules**.

## Extending Codex

| Mechanism | Purpose |
| --- | --- |
| Skills | Reusable capability packages |
| Plugins | Add functionality to Codex |
| MCP | Connect external tools/data via MCP servers |
| Hooks | Run logic at lifecycle points |
| Record & replay | Capture and re-run sessions |
| Site tools (WebMCP) | Web-based MCP tools |

## Permissions, profiles and sandboxing

| Control | What it does |
| --- | --- |
| Permission modes | How much Codex may do without asking |
| Profiles | Named configurations for different contexts |
| Sandboxing | Isolate execution (including Windows sandbox and WSL) |
| Auto-review | Automatic review of changes |
| Agent approvals & security | Human gates and safety on agent actions |
| Cloud internet access controls | Govern what cloud runs can reach |

## Environments

| Environment | Notes |
| --- | --- |
| Local | Runs on your machine |
| Cloud | Managed execution in Codex cloud |
| Git worktrees | Parallel work on multiple branches without switching |

Environment configuration covers modes plus local, cloud and git-worktree setups.

## Codex Security

A dedicated security surface (plugin, CLI, cloud) covering scans, deep scans, a security workbench, triage, fixes, hardening, and vulnerability reports, with CI and GitLab CI integration, backed by cyber-safety models and trusted access. Use it to shift security review left into the agent's workflow rather than bolting it on after.

## The GPT-5.4 retirement map

:::danger[Retirement, 31 August 2026]
`gpt-5.4` and `gpt-5.4-mini` **retire from Codex with ChatGPT sign-in on 31 August 2026**. `gpt-5.2` and `gpt-5.3-codex` are already deprecated with ChatGPT sign-in. **API-key sign-in is unaffected.**
:::

| Retiring (ChatGPT sign-in) | Replace with |
| --- | --- |
| `gpt-5.4` | `gpt-5.6-terra` |
| `gpt-5.4-mini` | `gpt-5.6-luna` |
| `gpt-5.2`, `gpt-5.3-codex` | already deprecated — move to the 5.6 line |

## Codex SDK, App Server, GitHub Action, non-interactive mode

- **Codex SDK** — build Codex into your own tooling.
- **App Server** — serve Codex capabilities to applications.
- **GitHub Action** — run Codex in CI pipelines.
- **Non-interactive mode** — `codex exec -m <model> "<task>"` for scripts and automation, no interactive session.

## Administration and governance

Codex ships an extensive admin surface for governed teams:

| Area | Controls |
| --- | --- |
| Rollout | Admin rollout guide, ChatGPT Work overview, cloud/local security |
| Auth | Workload identity, personal access tokens, service accounts |
| Users | Groups & provisioning, user lifecycle, roles & workspace permissions |
| Content | GPTs & sharing, managed configuration, workspace model availability |
| Compliance | Prisma AIRS, HIPAA configuration, Compliance API & audit events |
| Extensibility control | Plugin / connector / skill controls, admin plugin |
| Analytics | Workspace analytics, Analytics API |
| Deployment | App-update management, Windows deployment, remote connections, Amazon Bedrock |

## Worked setup — a governed team adopts Codex

<Steps>
1. **Standardise config** — commit a shared `config.toml` (`model = "gpt-5.6"`) and an `AGENTS.md` per repo with build/test commands and boundaries.
2. **Migrate off 5.4** — before 31 August 2026, switch ChatGPT-sign-in defaults to `gpt-5.6-terra` (was 5.4) and `gpt-5.6-luna` (was 5.4-mini). API-key users are unaffected.
3. **Set permissions** — pick a permission mode with approvals on destructive actions; enable auto-review; use profiles for local vs cloud.
4. **Sandbox** — run cloud tasks in the sandbox with cloud internet access controls scoped to what the task needs.
5. **Security** — turn on Codex Security scans in CI (GitLab CI supported) so vulnerabilities are caught in the agent's own workflow.
6. **Govern** — provision users via groups, set roles/workspace permissions, and export audit events via the Compliance API.
</Steps>

:::tip[Assessment signal]
"Think harder on one task" → **Max**; "fan the work out to parallel helpers" → **Ultra** (subagents). "Retired from Codex on 31 August 2026" with "ChatGPT sign-in" → the **5.4 → 5.6-terra / 5.4-mini → 5.6-luna** map, and note **API-key sign-in is unaffected**. "Notes across context windows, Plus/Pro only" → experimental context management.
:::

## Key facts to memorise

- One shared `config.toml` across desktop app, CLI and IDE; `AGENTS.md` holds per-repo instructions.
- Model/effort: `codex -m` / `codex --model` / `/model` / `codex exec -m`; ladder Low → … → **Max** (one task) → **Ultra** (parallel subagents).
- `gpt-5.4` / `gpt-5.4-mini` retire from Codex (ChatGPT sign-in) **31 Aug 2026** → `gpt-5.6-terra` / `gpt-5.6-luna`; API-key sign-in unaffected.
- Experimental context management is opt-in and **Plus/Pro sign-in only** at launch.
- Extend via skills, plugins, MCP, hooks, record & replay, site tools (WebMCP); govern via profiles, permission modes, sandboxing and the admin surface.