How to Fix OpenAI Codex CLI Context Window Exceeded Errors

Context window errors occur when your conversation plus file contents exceeds the model's token limit. This guide explains how to diagnose, prevent, and resolve these errors in OpenAI Codex CLI.

Understanding Context Windows

A context window is the total amount of text a language model can process at once, measured in tokens. Tokens are roughly equivalent to 4 characters or 0.75 words in English.

Common model context limits:

While these numbers seem large, they fill up quickly when:

• Reading multiple source files
• Maintaining conversation history
• Including system prompts and tool outputs

How Codex CLI Counts Tokens

Codex CLI tracks token usage across several components:

1. System prompt - The instructions that define Codex's behavior
2. Conversation history - Your prompts and Codex's responses
3. File contents - Any files Codex reads or you reference
4. Tool outputs - Results from commands Codex executes

When combined, these can quickly approach the context limit, especially in longer sessions or when working with large files.

Recognizing Context Errors

Context window errors typically appear as:

Error: Context length exceeded. Maximum context length is 128000 tokens.
Your messages resulted in 142567 tokens.

Or you may see warnings like:

Warning: Approaching context limit (95% used). Consider starting a new session.

Sometimes the error manifests as Codex "forgetting" earlier parts of the conversation or providing incomplete responses.

Creating Effective .codexignore Files

The .codexignore file prevents Codex from reading unnecessary files. Create it in your project root:

# .codexignore

# Dependencies (often massive)
node_modules/
vendor/
.venv/
__pycache__/

# Build outputs
dist/
build/
.next/
out/

# Large binary files
*.jpg
*.png
*.gif
*.pdf
*.zip
*.tar.gz

# Generated files
*.min.js
*.min.css
*.map
package-lock.json
yarn.lock
pnpm-lock.yaml

# Test coverage
coverage/
.nyc_output/

# Large data files
*.csv
*.json
data/
fixtures/

Pro tip: Start with aggressive exclusions and add exceptions as needed:

# Exclude everything in data/
data/

# But include config files
!data/config.json

Using Context Management Commands

Codex CLI provides commands to manage context:

/compact - Summarize History

The /compact command compresses your conversation history into a summary:

/compact

This preserves the key decisions and context while reducing token count significantly. Use it when:

• You have been working for a while and context is building up
• You are switching to a different task within the same session
• You see warnings about approaching context limits

Starting Fresh Sessions

For new tasks, start a fresh session rather than continuing an old one:

# End current session
exit

# Start new session
codex

This clears all conversation history and file context.

Referencing Specific Files

Instead of letting Codex scan your codebase, explicitly reference only needed files:

codex -f src/auth.ts "explain the authentication flow"

This is more efficient than:

codex "look at the auth system and explain it"

Strategies for Large Codebases

When working with large projects, use these strategies:

1. Work in Focused Directories

Navigate to the specific area you need:

cd src/components/dashboard
codex "refactor the chart component"

2. Use Multiple Sessions

Break large tasks into smaller, focused sessions:

• Session 1: Understand the current architecture
• Session 2: Plan the changes
• Session 3: Implement component A
• Session 4: Implement component B

3. Leverage Summary Files

Create architecture docs that Codex can read instead of scanning all files:

codex "read ARCHITECTURE.md and help me add a new API endpoint"

4. Exclude Test Files During Implementation

Add test files to .codexignore while implementing, then remove when writing tests:

# Temporarily exclude tests
**/*.test.ts
**/*.spec.ts

Model Comparison for Context

If you frequently hit context limits, consider the right tool for the job:

For very large codebases, Gemini CLI's 1M token context window provides 8x more capacity than Codex. See our guide on installing Gemini CLI.

When to Switch Tools

Consider switching tools when:

• Single files exceed limits - Use a tool with larger context or split the file
• You need full codebase awareness - Gemini CLI with 1M context handles this better
• Complex multi-file refactoring - Claude Code excels at maintaining coherence across files

Troubleshooting

Error Persists After /compact

If context errors continue after compacting:

1. Exit and start a fresh session
2. Check your .codexignore for missing exclusions
3. Reference fewer files explicitly

Codex Forgets Previous Instructions

This often indicates context is being silently truncated:

1. Use /compact to create an explicit summary
2. Re-state important context in your next prompt
3. Consider using a tool with larger context

Large File Cannot Be Read

If a single file exceeds limits:

1. Ask Codex to read specific sections: "Read lines 1-500 of large-file.ts"
2. Split the file into smaller modules
3. Create a summary document describing the file's structure

Next Steps

• Learn about session management in Codex CLI
• Explore Gemini CLI for 1M token context
• Read about orchestrating multiple AI tools for optimal workflows