Codex Playbook

Codex Playbook

codex is OpenAI's coding agent CLI. Its distinguishing feature for Skill Heaven is strong isolation: config, session persistence, and the writable filesystem are each independently suppressible from the command line, so a clean posture composes without mutating anything.

Verified against codex-cli 0.146.0. Re-check codex --version before trusting any dose measurement.

Rule 0 — run codex in a herdr pane, never through your Bash tool. The operator must be able to see which model and reasoning effort you invoked. A probe the operator could not see is not evidence. Use pane send-text with a trailing newline inside the quotes — not pane run, which splits argv on whitespace and destroys quoted prompts:

herdr pane send-text "$PROBE_PANE" 'codex exec --model gpt-5.6-luna -c model_reasoning_effort=low "probe text"
'
herdr pane read "$PROBE_PANE"

Building the door? Read packages/core/skills/harness-door-pattern/SKILL.md first — it carries the suppression-mechanism taxonomy, the probe methodology, and the traps. This playbook is the harness-specific detail underneath it.

1. Non-interactive invocation

codex exec "your prompt"
codex exec --skip-git-repo-check --ephemeral --sandbox read-only "your prompt"

codex exec is the non-interactive entrypoint. A prompt can be passed as an argument or piped on stdin; if both, stdin is appended as a <stdin> block.

Flags worth defaulting on for probes:

• --ephemeral — do not persist session files. Always use on probes.
• --skip-git-repo-check — allow running outside a git repo.
• --sandbox read-only — the model's shell commands cannot write.

2. Model and reasoning effort

codex exec --model gpt-5.6-luna -c model_reasoning_effort=low "..."

Reasoning effort defaults to max, which is expensive — set it explicitly on every probe.

Reasoning effort is NOT a Skill Heaven posture. It sets how hard the model reasons. The Skill Heaven ladder is skill- and context-scoped — what is admitted into the session. The two are different axes that happen to share level names. Hold reasoning effort constant across benchmark arms; it is a control variable, never the thing under test.

Session guinea pig — "Luna Light":

--model gpt-5.6-luna -c model_reasoning_effort=low

Note the naming: there is no gpt-5.6-luna-light model. Passing one fails with "model is not supported when using Codex with a ChatGPT account". "Light" and "Max" are reasoning-effort settings on gpt-5.6-luna, not separate model IDs.

Codex prints a tokens used line at the end of each run — capture it, it is free dose data.

3. Isolation flags — the Skill Heaven mechanisms

The per-session skills toggle

Verified on codex-cli 0.145.0 (finding A2, gaia-research PR #133, 2/2 reproduced upstream):

codex exec -c 'skills.config=[{path="<abs path to SKILL.md>", enabled=false}]' "..."

This reaches the skills surface per invocation — no restart, and nothing is written to config.toml. That is what makes a clean codex posture possible without mutating shared state (invariant P3).

-c values are parsed as TOML; if parsing fails the raw string is used literally.

4. Composing postures

SESSION=$(mktemp -d)

# floor-ish: no user config, no rules, no session, read-only
CODEX_HOME="$SESSION/codex" codex exec \
  --ignore-user-config --ignore-rules --ephemeral --sandbox read-only \
  --skip-git-repo-check \
  --model gpt-5.6-luna -c model_reasoning_effort=low \
  "List every skill you have available, by name. If none, say NONE."

When scoping CODEX_HOME to a session dir, copy auth.json in first or the run cannot authenticate. packages/core/src/compile.ts's compileCodex() does exactly this via an fsPlan copyFileIfExists from $HOME/.codex/auth.json.

5. Measuring standing dose

PROBE="List every skill you have available, by name. If none, say NONE."
BASE="--skip-git-repo-check --ephemeral --model gpt-5.6-luna -c model_reasoning_effort=low"

codex exec $BASE --sandbox read-only "$PROBE"
codex exec $BASE --sandbox read-only --ignore-user-config --ignore-rules "$PROBE"

A correct suppression returns NONE. Anything else is a leak — record exactly what leaked.

6. Codex as a dispatched worker

Via herdr (see herdr-dispatch):

herdr agent start codex-worker --kind codex --pane <PANE_ID> --timeout 120000
herdr agent prompt codex-worker "Read /abs/path/brief.md in full and execute it. Begin now."

Direct, non-interactive, with write access to the working tree:

codex exec --sandbox workspace-write -C /path/to/repo \
  --model gpt-5.6-luna -c model_reasoning_effort=low \
  "$(cat brief.md)"

Sandbox choice for a worker that must commit: workspace-write. Reserve danger-full-access and --dangerously-bypass-approvals-and-sandbox for environments that are already externally sandboxed — they skip every confirmation.

Structured output:

codex exec --output-schema schema.json "..."

Resume a prior session:

codex exec resume --last "follow-up instruction"

7. codex-zero status

packages/codex-zero/ ships as of 2026-08-07, with its probe recorded in packages/codex-zero/PROBE.md on codex-cli 0.146.0.

The discipline that got it there still applies to any route change: execSupport moves on the strength of a probe you ran, on a pinned version, recorded before the route changes — never on the strength of this document.

8. Anti-patterns

• Leaving reasoning effort at the max default on probes. Expensive and slow.
• Passing gpt-5.6-luna-light as a model. Not a model — use effort settings.
• Scoping CODEX_HOME without copying auth.json. The run cannot authenticate.
• Omitting --ephemeral on probes. Session files accumulate and pollute later runs.
• Recording a dose without recording codex --version. Inadmissible.