Codex-1M-Context

A Codex skill and companion CLI utility for safely configuring model context windows, effective-window percentages, and automatic-compaction defaults on Windows and macOS.

It is useful when a local model_context_window appears correct at startup but changes after the first turn because the active model catalog applies a separate effective-context percentage.

Chinese documentation: README.zh-CN.md.

What It Does

• Lists available models and accepts the sol alias or gpt-5.6-sol for this 1M workflow.
• Sets selected model entries' context_window, max_context_window, and effective_context_window_percent.
• Updates the top-level model_context_window and model_catalog_json entries in Codex's user configuration.
• Calculates the usable context before writing any files.
• Supports previews, timestamped backups, post-write verification, and rollback if a write or verification fails.
• Separates the effective-window percentage from the independent automatic history-compaction token limit.

Platform Support

The script uses Python pathlib, platform-safe temporary files, atomic replacement, and CODEX_HOME on both supported platforms.

• Windows: Python 3.11 or newer, launched with py -3; default config is %USERPROFILE%\.codex\config.toml.
• macOS: Python 3.11 or newer, launched with python3; default config is ~/.codex/config.toml.

Set CODEX_HOME to use another Codex configuration directory. The script finds the Codex executable through PATH, including the Windows codex.cmd launcher.

Install

Clone the skill into Codex's user skill directory.

macOS:

git clone https://github.com/smartcmd/codex-context-window.git \
  ~/.codex/skills/codex-context-window

Windows PowerShell:

git clone https://github.com/smartcmd/codex-context-window.git "$HOME\.codex\skills\codex-context-window"

Start a new Codex task, or restart Codex, so it discovers the skill.

Health Check

Run the isolated end-to-end self-check before first use and after updating the skill. It creates only temporary files and does not inspect or change your Codex configuration.

macOS:

python3 scripts/update_context_catalog.py --self-check

Windows PowerShell:

py -3 scripts\update_context_catalog.py --self-check

The self-check covers parsing, alias resolution, catalog updates, backup creation, atomic writes, TOML rendering, and verification of the resulting configuration.

Use in Codex

Invoke the skill in a task:

$codex-context-window

Configure a 1M Context Window

ChatGPT groups now support a one-million-token context window. Use the codex-context-window skill to configure a 1M window and a 900K automatic compaction threshold for gpt-5.6-sol only.

1. Send this request directly in Codex:

   Install this Skill: https://github.com/bendangmi/codex-1m-context
   
   Then set the context window for gpt-5.6-sol to 1M, with the automatic
   compaction threshold set to 900K.
   

2. Restart Codex after the configuration is written.

3. In the desktop app, enable Show context-window usage in Settings → General → Editor. Start a new message to confirm that the 1M setting is active.

4. In Codex CLI, run /status, then open context details to inspect the actual window size.

The skill asks for target models, raw context window, effective-window percentage, and the automatic-compaction behavior. For a raw window of 372K and an effective percentage of 95%, the usable context is 353400 tokens:

floor(372000 * 95 / 100) = 353400

CLI Workflow

The bundled script supports the same workflow outside a Codex task.

One-Million-Token Context

Codex can use a temporary 1M raw context window for GPT-5.6 Sol without changing the model catalog:

codex -m gpt-5.6-sol -c model_context_window=1000000 -c model_auto_compact_token_limit=900000

For a persistent full 1M usable window, use the skill script to set the raw window to 1M, the catalog effective percentage to 100, and the automatic compaction threshold to 900K. Confirm that the selected provider supports 1M before applying the change.

macOS:

python3 scripts/update_context_catalog.py \
  --models sol \
  --context 1M \
  --effective-percent 100 \
  --auto-compact-limit 900K \
  --apply

Windows PowerShell:

py -3 scripts\update_context_catalog.py --models sol --context 1M --effective-percent 100 --auto-compact-limit 900K --apply

To cancel the persistent 1M setting and restore the standard 272K full usable window, preview then apply this command:

--models sol --context 272K --effective-percent 100 --auto-compact-limit default --apply

Use --verify instead of --apply after writing. The script prints timestamped backups; use them if the previous settings were not 272K / 100% / model-default compaction.

List the current catalog on macOS:

python3 scripts/update_context_catalog.py --list-models

List the current catalog on Windows PowerShell:

py -3 scripts\update_context_catalog.py --list-models

Preview a change on macOS:

python3 scripts/update_context_catalog.py \
  --models sol \
  --context 372K \
  --effective-percent 95 \
  --auto-compact-limit default

Preview or apply the same change on Windows PowerShell:

py -3 scripts\update_context_catalog.py --models sol --context 372K --effective-percent 95 --auto-compact-limit default
py -3 scripts\update_context_catalog.py --models sol --context 372K --effective-percent 95 --auto-compact-limit default --apply

Use --auto-compact-limit default to remove top-level automatic-compaction overrides so Codex uses the model default. Use keep to preserve an existing override, or pass a token value such as 350K to set an explicit limit.

After applying, validate the exact persisted state without sending a model request.

macOS:

python3 scripts/update_context_catalog.py \
  --models sol \
  --context 372K \
  --effective-percent 95 \
  --auto-compact-limit default \
  --verify

Windows PowerShell:

py -3 scripts\update_context_catalog.py --models sol --context 372K --effective-percent 95 --auto-compact-limit default --verify

--verify checks the global raw window, configured catalog path, all selected model metadata, and the requested automatic-compaction behavior. It returns a non-zero status if any value is missing, stale, or reverted.

Safety Notes

The script reuses an existing model_catalog_json when configured; otherwise it attempts to export Codex's bundled catalog. Existing catalog and configuration files receive timestamped backups before writes. If an applied update fails or post-write verification fails, the script restores the original files.

If the installed Codex does not provide the bundled model export command, pass an existing catalog explicitly with --catalog PATH or configure model_catalog_json first. Do not claim that a local setting increases the upstream provider's actual capacity; confirm that a custom provider supports the requested raw context window.

For a lightweight Codex CLI parsing check, run:

codex --help

Fully restart Codex after an update because model_catalog_json is loaded at startup. Current Codex releases do not provide the older codex debug models subcommand used by earlier versions.