Guide · Agent skill
How to use the Codex Huge Context agent skill (setup guide)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The codex-huge-context skill is an agent skill that teaches an AI agent to set up, repair, or audit a Codex configuration with a very large context window of about one million tokens. It is written for developers who run Codex on their own Mac and for operators who maintain several Macs. After this guide you will know what the skill does, how to add it to your agent, how to ask for it in plain words, and what it needs before you let it change any files.
Codex Huge Context Setupsteipete/agent-scripts · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. Confirm that SKILL.md is inside the codex-huge-context folder.
- 2Check your requirements. Confirm you have Codex, an OpenAI API account with access to gpt-6-astra and gpt-6.1-sol, and a normal ChatGPT login for connectors.
- 3Create the Keychain helper. Store your API key in the macOS Keychain under the account Codex and service name Codex OpenAI inference API, then save the helper script at ~/.codex/bin/fetch-openai-inference-key.zsh.
- 4Ask the agent to back up and configure. Request the setup in plain words. The agent should back up both config files to date-stamped copies before it edits anything.
- 5Add profiles and the provider. Let the agent set the openai_api_direct provider and create the profiles. Each profile must pin that provider.
- 6Run the preflight. Do not start Codex until the preflight passes. If it fails on a split configuration, restore the direct provider and start a fresh thread.
What an agent skill is and what this one makes the agent do
An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to handle a specific kind of task. The agent reads the skill when your request matches its description.
This skill covers one job: configuring, repairing, or auditing Codex's one-million-token context setup. It routes model inference through a direct OpenAI API provider, with the API key fetched from a macOS Keychain helper, while the normal ChatGPT login stays in place for connectors such as Gmail and Calendar. It also gives exact config values, compaction thresholds, and a preflight check that blocks launching Codex when the provider and context settings do not match.
- Sets the provider to a direct API route at https://api.openai.com/v1/responses
- Keeps connector OAuth on the normal ChatGPT login in auth.json
- Sets the safe input window to 922,000 tokens and automatic compaction to 700,000 tokens
- Adds named profiles for Astra and Sol models with and without the large window
- Runs a preflight that treats a mismatched provider and context split as fatal
Install the codex-huge-context skill
Download the skill ZIP from this page. Unzip it into your personal skills folder at ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill available only in that project. After unzipping, the codex-huge-context folder should contain SKILL.md.
If you use the Claude apps instead of the file system, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills
Prepare the requirements before you ask for setup
The skill assumes several things are already in place. It does not create them for you, and it cannot verify your account or access to the models.
You need Codex, an OpenAI API account with access to the named models (GPT-6 Astra and GPT-6.1 Sol), a macOS Keychain helper script at ~/.codex/bin/fetch-openai-inference-key.zsh, and a normal ChatGPT login for connector OAuth. The source says the API remains authoritative for access, actual model limits, and billing, so check your own account before you rely on the setup.
- Codex installed on your Mac
- An OpenAI API account with access to gpt-6-astra and gpt-6.1-sol
- The Keychain helper at ~/.codex/bin/fetch-openai-inference-key.zsh
- A normal ChatGPT login for connectors such as Gmail and Calendar
Store the API key in the Keychain and wire up the helper
The auth command reads a dedicated Keychain copy of the key. The key is never placed in TOML or an environment variable. The helper below is the script the skill expects, copied from the skill source. Save it at ~/.codex/bin/fetch-openai-inference-key.zsh. The Keychain item it reads uses account Codex and service name Codex OpenAI inference API.
- Keep the key only in the macOS Keychain, not in config files
- The config refers to the script path, not to the key itself
#!/bin/zsh
set -euo pipefail
exec /usr/bin/security find-generic-password \
-a Codex \
-s "Codex OpenAI inference API" \
-wUnderstand the context window and compaction numbers
The skill uses 922,000 safe input tokens. GPT-6 Astra has a 1,050,000-token total window and can produce up to 128,000 output tokens, so 1,050,000 minus 128,000 leaves 922,000 for input. Automatic compaction is set to 700,000 total active tokens to leave room for the next prompt, tool results, and the compaction request itself.
Above 272,000 input tokens the provider uses higher long-context pricing, so the skill says not to enable the large route for work that does not need it. For everyday lanes, the skill sets a 500,000-token base window with 400,000-token compaction and recommends the large profiles only for whole-repo work.
- Base: 500,000-token window, 400,000 compaction, scope total
- Large: 922,000-token window, 700,000 compaction, scope total
- Use the -1m profiles only when a task needs the whole repository in context
Trigger the skill with natural requests
You do not need special syntax. Describe the outcome in plain words and mention Codex and context, so the agent matches the skill. Good requests name the action: set up, repair, or audit. Ask the agent to back up files before it changes them, since the skill requires that.
Example requests that should match the skill: set up Codex for a one-million-token context using the direct OpenAI API; audit my Codex config for a provider and context mismatch; repair my Codex profiles so the -1m profile uses the correct compaction limit; roll out the same Codex context config to my other Macs.
- Set up my Codex config for the 1M context window with the direct API route
- Audit my Codex config and tell me if the provider and context settings mismatch
- Add the astra-1m and sol61-1m profiles and run the preflight
- Back up my Codex config files, then update the context settings
Run the preflight and start a fresh thread
The skill requires a preflight to pass after any config change, app settings change, model change, or fleet sync, before Codex is launched or resumed. If it reports an unsafe split configuration, the skill says to restore the openai_api_direct provider, restart every Codex desktop or shared app server, and start or fork a fresh thread. Resuming the failed thread keeps its recorded provider, so it does not fix the problem.
- Do not launch or resume Codex until the preflight passes
- Verify the fresh session's reported effective window, not only the files on disk
What people use it for
- Give a single Mac a whole-repository context lane for large code reviews, using the -1m profile only for that work.
- Audit an existing Codex config to find a 700,000-token compaction threshold left on the ChatGPT route.
- Roll out one audited configuration to several Macs so each machine uses the same provider and profile names.
- Repair a thread that hit context_length_exceeded by restoring the provider and starting a fresh thread.
Frequently asked questions
Is the codex-huge-context skill free?
The skill is published under the MIT licence, as stated on this page. Using it still requires an OpenAI API account with access to the named models, and the API bills according to its own terms.
What do I need before I install codex-huge-context?
You need Codex, an OpenAI API account with access to GPT-6 Astra and GPT-6.1 Sol, a macOS Keychain helper script at ~/.codex/bin/fetch-openai-inference-key.zsh, and a normal ChatGPT login for connector OAuth. The skill does not create these for you.
Where do I put the codex-huge-context skill folder?
Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ inside a project. In the Claude apps, upload it under Settings, then Capabilities, then Skills.
Will this skill work on Windows or Linux?
The skill's helper is a macOS Keychain script that calls /usr/bin/security, so it is written for a Mac. The file also assumes a specific user home directory, so check the paths before using it on another system.
Does the skill send my data to the network?
Yes. It routes Codex inference to https://api.openai.com/v1/responses and runs a helper script that reads your key from the Keychain. Review the script and the config before you let the agent apply them.
How is this different from the default ChatGPT login setup?
The default ChatGPT-authenticated route keeps the normal login for inference. This skill uses a separate openai_api_direct provider for inference with API-key auth, and keeps the ChatGPT login for connectors. It also enforces a preflight that rejects mixing the large context values with the ChatGPT route.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you run Codex on your own Mac, have a direct OpenAI API account with access to the named models, and want an agent to set up or audit a very large context configuration. Pick something else if you lack that API access, or if you cannot verify the hardcoded paths and settings, since the file assumes one user home directory and specific Codex releases.
Download the skill