Codex Context Window

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

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.

What It Does

• Lists available models and accepts model slugs or aliases such as sol, terra, luna, and all-gpt-5.6.
• 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 a preview-first workflow and creates timestamped backups before an applied change.
• Separates the effective-window percentage from the independent automatic history-compaction token limit.

Install

Clone the skill into Codex's user skill directory:

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

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

To update an existing installation:

git -C ~/.codex/skills/codex-context-window pull --ff-only

Use in Codex

Invoke the skill in a task:

$codex-context-window

The skill asks for:

1. Target models.
2. Raw context window, defaulting to 372K.
3. Effective-window percentage, defaulting to 95%.
4. Whether automatic history compaction should use the model default or an explicit token limit.

For a raw window of 372K and an effective percentage of 95%, the usable context is 353400 tokens (about 353K):

floor(372000 * 95 / 100) = 353400

CLI Workflow

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

List the current catalog:

cd ~/.codex/skills/codex-context-window
python3 scripts/update_context_catalog.py --list-models

Preview a change for the GPT-5.6 family:

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

Apply the reviewed change:

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

--auto-compact-limit default removes top-level model_auto_compact_token_limit overrides so Codex uses the model default. Use keep (the script default) to preserve any existing override, or pass a token value such as 350K to set an explicit limit.

Safety Notes

The script does not create a model catalog from scratch. It reuses an existing model_catalog_json when configured; otherwise it exports Codex's bundled catalog and changes only the selected models. Existing catalog and configuration files receive timestamped backups before writes.

model_context_window is a global setting for the active model. Changing a subset of model catalog entries does not increase the upstream provider's actual capacity, and a later model switch can still be affected by the top-level raw window. Confirm that a custom provider supports the requested context size.

Validate after applying a change without sending a billable model request:

codex exec --strict-config --ephemeral --skip-git-repo-check --help
codex debug models

Refresh After Codex Updates

A custom catalog pins the bundled model metadata used by Codex. After upgrading Codex, rerun the reviewed command with --refresh-from-bundled to rebuild the catalog from the new binary while retaining the selected context settings.

中文说明

这是一个用于安全调整 Codex 模型上下文窗口的 skill。它会询问目标模型、原始 窗口大小、有效窗口比例和自动压缩策略，先给出实际可用上下文的计算结果，再在 确认后修改配置并创建备份。

372K 原始窗口配合 95% 有效比例时，实际可用窗口是 353400 token，约 353K。这里的有效比例与 model_auto_compact_token_limit 是不同的概念；后者 保持模型默认值时，使用 --auto-compact-limit default。