codex-huge-context

Files (3)

• SKILL.md
• preflight.rb · scripts/
• preflight.test.rb · scripts/

SKILL.md (first lines)

# Codex Huge Context

Use this skill when configuring, repairing, or auditing Codex's one-million-token context setup. The intended topology is a direct API inference route that preserves the normal ChatGPT login for Gmail, Calendar, and other connector OAuth:

```text
Codex inference -> Keychain auth helper -> https://api.openai.com/v1/responses
Codex connectors -> normal ChatGPT login in auth.json
```

This is not an HTTP proxy. The API remains authoritative for access, actual model limits, and billing.

## Atomic provider and context invariant

Treat the provider selector, context window, compaction threshold, and custom model catalogue as one atomic configuration. In Peter's normal ChatGPT-authenticated setup, `model_provider = "openai"` selects the ChatGPT-backed route; never attach this skill's direct-API `922000` context window and `700000` compaction threshold to that route. The provider identifier alone does not determine transport: built-in `openai` with API-key authentication can also use the API. This skill and its preflight require the named `openai_api_direct` provider below so inference uses its dedicated Keychain helper while connector login stays separate.

That split configuration can leave a 700,000-token compaction threshold attached to a smaller provider or model-metadata limit. Codex may also clamp the requested window, so root numbers alone do not prove the usable context. A browser- or Computer Use-heavy thread can grow past the provider's real limit before compaction, receive `context_length_exceeded`, and become unable to compact because the compaction request itself no longer fits. Verify the fresh session's reported effective window as well as the files on disk.

The required preflight treats this mismatch as fatal. Do not launch or resume Codex after any config writer, app settings change, model change, or fleet sync until the preflight passes. If it reports an unsafe split configuration, restore `model_provider = "openai_api_direct"`, restart every Codex desktop/shared app server, and start or fork a fresh thread. Resuming the failed thread preserves its recorded provider.

## Safe input window

[GPT-6 Astra](https://developers.openai.com/api/docs/models/gpt-6-astra) exposes a 1,050,000-token total context window and can produce up to 128,000 output tokens. Codex does not set a smaller output budget on normal Responses API turns, so the catalogue must describe the safe input allowance rather than the raw total:

```text
1,050,000 total - 128,000 maximum output = 922,000 safe input
```

Use the same safe input policy for both direct-provider catalogue models ([GPT-6.1 Sol](https://developers.openai.com/api/docs/models/gpt-6.1-sol) has the same 1,050,000-token window and 128,000-token output limit):

- `gpt-6-astra`
- `gpt-6.1-sol`

Preserve the operator's selected supported model when configuring context. The examples below use Astra; enabling large context does not authorize replacing another selected model.

Codex applies its normal 95% effective-window reserve to the 922,000-token input allowance, so it reports and guards about 875,900 usable tokens. Set automatic compaction to 700,000 total active tokens. That leaves about 175,900 tokens inside Codex's effective guard and 222,000 tokens before the provider's safe input ceiling for the next prompt, tool schemas and results, instructions, serialization overhead, and compaction itself. This larger margin is intentional: Codex 0.144.6 checks already-recorded context before adding the next user message and context updates, and a terminal response that crosses the threshold may not compact until the following turn. The observed large-context workload grew by about 144,000 tokens in one turn, which made the former 820,000 threshold too aggressive.

Long-context requests above 272,000 input tokens use the provider's higher long-context pricing. Do not enable this route accidentally for workloads that do not benefit from it.

## Required files

`~/.codex/models-api-1m.json` must contain these values for all five model slugs while preserving the rest of each model entry:

```json
{
  "context_window": 922000,
  "max_context_window": 922000,
  "auto_compact_token_limit": 700000
}
```

Leave `effective_context_window_percent` absent to use Codex's 95% default, or set it explicitly to the integer `95`. Null, floating-point, or other values are invalid.

Start from the complete native catalogue for the installed Codex release, including its reviewer models: a custom catalogue replaces the built-in catalogue rather than overlaying selected entries. Use every model's genuine metadata and a client satisfying its minimum version. Preserve instructions, tool capabilities, and every safety field, including required review behavior; override only the context and compaction fields above. Never invent Astra metadata or relabel a Sol entry as Astra. The API context contract above supports the direct-provider override; it does not expand ChatGPT entitlement or relax client safety requirements. The preflight validates context and credential delivery, not the provenance of the remaining catalogue metadata.

The catalogue describes each model's safe maximum. Sessions default to a 500,000-token window
(Peter, 2026-10-12): step latency roughly doubles from 100k to 300k of context, so lanes run
smaller unless they need more. The root section of `~/.codex/config.toml` needs:

```toml
model = "gpt-6.1-sol"
model_provider = "openai_api_direct"
model_context_window = 500000
model_auto_compact_token_limit = 400000
model_auto_compact_token_limit_scope = "total"
model_catalog_json = "/Users/steipete/.codex/models-api-1m.json"

[model_providers.openai_api_direct]
name = "OpenAI API direct"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = true

[model_providers.openai_api_direct.auth]
command = "/Users/steipete/.codex/bin/fetch-openai-inference-key.zsh"
timeout_ms = 5000
refresh_interval_ms = 300000
```

`supports_websockets = true` is required: custom providers default to HTTP, which re-uploads the full
prompt every step (measured 2026-10-12 at 150k context on a ~22 Mbps uplink: 26-59 s per step on HTTP vs
0.8-3.7 s on WebSocket, whose continuations send only new items).

Replace legacy values such as `model_context_window = 1050000` or `922000` at the root; do not leave duplicate root keys. Keep the scope at `total`, because the safety budget applies to the complete active request, not only content added after a compaction prefix.

### Profiles

Codex 0.162 profiles are files: `codex -p <name>` layers `~/.codex/<name>.config.toml` over the
base config (names allow only letters, digits, `_` and `-`). Every host carries four:

| Profile | `model` | Context |
|---|---|---|
| `astra` | `gpt-6-astra` | base 500k |
| `sol61` | `gpt-6.1-sol` | base 500k |
| `astra-1m` | `gpt-6-astra` | `922000` window, `700000` compaction, scope `total` |
| `sol61-1m` | `gpt-6.1-sol` | `922000` window, `700000` compaction, scope `total` |

Each profile also sets `model_provider = "openai_api_direct"`. Any profile that sets context keys
must pin that provider and use 500000/400000 or 922000/700000; the preflight enforces this for
every `*.config.toml`. Use a `-1m` profile only for work that needs a whole-repo context.

Before modifying a host, back up both config files to date-stamped sibling files. Do not replace unrelated project, plugin, MCP, notification, approval, model-selection, or reasoning settings.

## API credential delivery

The auth command reads a dedicated Keychain delivery copy, never a value in TOML or an environment variable:

```zsh
#!/bin/zsh
set -euo pipefail
exec /usr/bin/security find-generic-password \
  -a Codex \
  -s "Codex OpenAI inference API" \
  -w /Users/steipete/Library/Keychains/login.keychain-db
```

Resolve and verify the host's actual Keychain path at installation time; the example is host-specific. Keep that absolute, non-secret path inside the external executable, not `$HOME`/`~`, a provider override, or non-empty `auth.args`. Managed autoreview replaces the client's HOME/USERPROFILE and XDG config/data/state/cache directories. Implicit Keychain selection can then return exit 44 (`SecKeychainSearchCopyNext` item not found) even though parent-session delivery succeeds. Repair the wrapper's Keychain selection—not the reviewer's HOME, filesystem grants, or credential access. Inspect an existing helper before changing it; it may already use explicit selection.

Use `$one-password` before handling the API key. The canonical value is the `OPENAI_API_KEY` field in Molty's `AI API Key - OpenAI - OPENAI_API_KEY - Serviceable Access` item. Read it through the service-account workflow inside the shared `op-work` tmux session and store/update only the Keychain copy. Never print, copy over SSH, place in a profile, or write it to a temporary file.

From steipete/agent-scripts, MIT.

More from steipete/agent-scripts