Workflow & Core Tools · daymade/claude-code-skills

codex-1m-context-window-setup

Name: codex-1m-context-window-setup
Author: daymade/claude-code-skills

Configures and verifies an expanded, model-aware context window for OpenAI Codex CLI and Codex Desktop by safely updating the shared base config. Use whenever Codex shows about 258K context, the user asks for 500K or 1M context, auto-compaction happens too often, model_context_window or model_auto_compact_token_limit needs repair, or a workstation/classroom needs the same long-context setup across macOS and Windows. Detects the selected model's live maximum, requests up to 1M tokens, sets compaction to 60% of the attainable window, preserves unrelated TOML, backs up changes, and fails rather than guessing when the model contract cannot be verified.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE；GitHub API spdx MIT）Commit d5c4678cb5

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

A single Python script with three modes (doctor/apply/verify), all invoking the official Codex CLI via subprocess to retrieve 'live data': codex doctor --json parses the selected model and config.load status, while codex debug models fetches the current model catalog, never memorizing or hallucinating model limits.

daymade-codex/codex-1m-context-window-setup/SKILL.md

If Codex cannot return a live model catalog, stop. Do not substitute remembered model limits, API marketing numbers, or a bundled default.

On the code side, selected_model() verifies checks.config.load.status=='ok' before reading model; live_model_catalog() requires a non-empty list of dict items, failing with SetupError otherwise—'fail when the model contract cannot be verified' is a core design principle.

Model-aware computation: target_raw = min(1,000,000, model max_context_window); usable = target_raw × effective_context_window_percent; auto-compact = target_raw × 3/5 (user-established 60% policy); and outputs capped_by_model / expands_catalog_default for reporting.

daymade-codex/codex-1m-context-window-setup/scripts/codex_context_window.py

target_raw = min(TARGET_CONTEXT_CEILING, maximum_raw) target_effective = target_raw * effective_percent // 100 compact_limit = target_raw * COMPACT_NUMERATOR // COMPACT_DENOMINATOR

TARGET_CONTEXT_CEILING = 1_000_000 and COMPACT 3/5 are top-level constants; reference context_window_contract.md explains that 'the skill name describes the requested ceiling, not that every model fulfills 1M' (Codex will clamp to max_context_window).

apply is a conservative editor: regex replaces only simple integer assignment lines for two top-level keys (model_context_window / model_auto_compact_token_limit); it refuses to modify if syntax cannot be conservatively preserved; new keys are inserted before the first table header; followed by tomllib re-read verification after modification.

daymade-codex/codex-1m-context-window-setup/scripts/codex_context_window.py

raise SetupError( f"top-level {key} uses syntax the conservative editor cannot preserve; " "no file was changed")

SIMPLE_INTEGER_ASSIGNMENT matches only top-level bare keys; render_config also flags errors on BOM, preserves original newline styles (\r\n vs \n), and fully re-parses with tomllib.loads post-modification to assert the values of both keys.

Safe disk-writing chain: content-addressed backup (config.toml.<UTC_timestamp>.<sha12>.bak placed in CODEX_HOME/backups/codex-1m-context-window-setup/) → same-directory temporary file + fsync + os.replace atomic substitution → pre-write concurrency change detection → post-write strict-config doctor verification, automatically restoring original bytes upon failure.

daymade-codex/codex-1m-context-window-setup/scripts/codex_context_window.py

backup = backup_dir / f"config.toml.{timestamp}.{digest}.bak"

apply_configuration refuses to write if current != original_bytes; strict_config_check uses codex --strict-config doctor --json requiring config.load=ok; exception branches atomically restore original content or delete the new file.

verify acts as a drift detector: re-runs live catalog to compute recommended values and reports a mismatch with a non-zero exit code if it deviates from the current base config—instantly revealing compliance status after Codex upgrades or default model changes.

daymade-codex/codex-1m-context-window-setup/SKILL.md

It exits non-zero when the current base config no longer equals the model-aware recommendation. Report the mismatch; do not call it configured.

In main(), when mode==verify, exit_code = 0 if report["status"]=="configured" else 1; restart_required: true is set post-apply (existing sessions do not expand in-place).

Explicitly constrained skill scope: does not change model/reasoning tiers/sandbox/approval/plugins/MCP/browser settings, does not touch profile-level configurations, does not override per-command -c flags, does not claim the current thread is expanded, and does not enforce 1M unconditionally.

daymade-codex/codex-1m-context-window-setup/SKILL.md

Do not ask the user for raw token numbers. The model catalog is the authority and the script derives the attainable values.

The 'Refuse scope expansion' section lists explicit out-of-scope items, paired with 'do not ask users for token numbers'—eliminating guesswork from the workflow.

2Core Capabilities

01doctor: Read-only diagnostic of current limits, explains the origin of the 258K limit, and previews recommendations (model/catalog default/maximum/usable percentage/60% compaction point/current config/target path)

02apply: Model-aware safe updating of the two base config keys to attainable ceilings, complete with backup/atomic write/concurrency check/failure rollback/strict verification

03verify: Validates whether configuration still matches model-aware recommendations after updates/model changes/new machine setup (non-zero exit = reconfiguration needed)

04Cross-platform support (dual command templates for macOS/Linux bash and Windows PowerShell)

05Dual formatting with machine-readable output (--json) and human-readable reports, copying values directly from script output

06Testability: --codex-bin explicitly designates executable paths (for diagnostics/testing), equipped with built-in pytest tests

3External Dependencies

Kind	Dependency / Endpoint
cli	codex（官方 CLI；doctor/debug models/--strict-config doctor）
cli	uv（uv run --no-project python 执行脚本）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local script or command: python3 runs codex_context_window.py (standard library only)
本地工作目录: File read/write and artifact output: Writes $CODEX_HOME/config.toml during apply (content-addressed backup + atomic replacement in same directory + failure rollback to original content); backups written to $CODEX_HOME

Audit Notes: Runs a self-contained local Python script using only stdlib and invokes the official local Codex CLI. Modifies local configuration ($CODEX_HOME/config.toml) guarded by content-addressed backups, atomic replacement, concurrency detection, and automatic rollback on failure. Involves no external network transmissions, credential access, or destructive deletions. Note: The script itself makes no HTTP requests; whether codex doctor accesses the network depends on official CLI behavior. Modifies shared base config; multi-threaded concurrency is guarded by byte comparison.

5Second-Pass Verification

[ok] 只改两键的保守编辑承诺 — TARGET_KEYS=('model_context_window','model_auto_compact_token_limit')；SIMPLE_INTEGER_ASSIGNMENT 仅匹配顶层；非保守语法 raise 且不写。
[ok] 备份/原子/回滚链 — backup_config → atomic_write(mkstemp+fsync+os.replace) → strict_config_check → 异常分支 atomic_write 原文/删除新文件，全链在代码中。
[ok] 无网络/凭证 — 脚本 imports 无 http 库；env 仅 CODEX_HOME；不读 auth 文件。
[ok] verify 漂移语义 — main() exit_code = 0 if status=='configured' else 1（verify 分支），SKILL 描述一致。
[unlocatable] codex CLI 输出 schema（doctor --json / debug models 字段） — 字段名（checks.config.load/details.model、models[].context_window/max_context_window/effective_context_window_percent）依赖安装的 codex 版本，本环境无 Codex 未运行验证；SKILL 要求 doctor 失败即停机，schema 漂移会被显式失败捕获。

6Verdict & Scenarios

Treats the live model catalog as the single source of truth, gracefully degrading and marking capped_by_model when a model does not support 1M

Textbook-grade configuration writing safety: backup + atomic replace + concurrency detection + strict verification + failure rollback

Minimal invasiveness: regex modifications strictly limited to two keys, fully preserving TOML comments/newlines/other tables

Clear scope refusal checklist, eliminating scope creep such as accidental changes to model/sandbox/MCP settings

Best for: Ideal for power users of Codex, as well as workstation and classroom fleet deployments: expanding default 258K context to 500K/1M, resolving overly frequent auto-compaction, or verifying configuration compliance after upgrades; well-suited for cautious configuration workflows demanding 'reversibility, verifiability, and zero impact on other settings' (script semantics match classroom environments).

Not for: Not suitable for users looking to adjust models, reasoning effort, or sandbox approval settings (refused by boundary rules); not suitable for environments running outdated Codex versions lacking the debug models command (halts with an error); users overriding configurations via profile levels or per-command -c flags are not managed by this skill (only base config is modified).

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload codex-1m-context-window-setup.tar.gz

sha256: 9d4e6694887d55eb…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.