From 00689dce68d257b8264840b8d165d85ffc1a240b Mon Sep 17 00:00:00 2001 From: "John M. P. Knox" Date: Sun, 9 Aug 2026 13:42:12 -0500 Subject: [PATCH] docs(codex): add an official-references section to the codex backend doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Point at the upstream OpenAI Codex docs as the source of truth for the controls this backend maps (model, reasoning effort, service tier / Fast mode) — Codex is fast-moving, so links to the canonical pages age better than a local snapshot. Notes explicitly that Impasse runs non-interactive and hermetic (codex exec --ignore-user-config), so the interactive slash commands and config.toml persistence those pages also describe don't apply to a run. Consolidates the useful part of a scratch options summary into the doc a contributor actually reads; the standalone summary (never committed) is dropped. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01X8XaW2bqgYnp7oRVgfHXid --- docs/backends/codex.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/backends/codex.md b/docs/backends/codex.md index f1b1877..adee557 100644 --- a/docs/backends/codex.md +++ b/docs/backends/codex.md @@ -143,3 +143,19 @@ loop) — but they still carry `retryable: true`: as with `rate_limited`, the hi is plausible, offer it to the operator", and the failure message names the remedy (shrink the artifact, tighten the instruction, lower effort, or re-run unchanged — most plausible near the bound). `retryable` is a recoverability hint, not an auto-retry marker. + +## Official Codex references + +Codex is a fast-moving CLI, so the notes above are version observations, not a durable contract — +prefer the upstream docs as the source of truth for the controls this backend maps. (The runner runs +non-interactive and hermetic — `codex exec --ignore-user-config` — so the interactive slash commands +and `~/.codex/config.toml` persistence those pages also describe do **not** apply to an Impasse run; +Impasse passes every setting as a `-c` override or `-m`.) + +- [Codex CLI](https://developers.openai.com/codex/cli) — the tool overall. +- [Non-interactive mode (`codex exec`)](https://developers.openai.com/codex/non-interactive-mode) — how the runner invokes it. +- [Codex models](https://developers.openai.com/codex/models) — model selection (`-m` / `--model`). +- [Configuration reference](https://developers.openai.com/codex/config-reference) — the `-c` keys the runner sets: `model_reasoning_effort`, `service_tier`, `features.fast_mode`. +- [Speed / Fast mode](https://developers.openai.com/codex/speed) — the service-tier / Fast-mode behavior behind `--speed fast`. +- [Codex pricing](https://developers.openai.com/codex/pricing) — the higher credit cost Fast mode trades for speed. +- [OpenAI model catalog](https://developers.openai.com/api/docs/models) — available models (broader than the Codex selector).