Token Budgets & Context Management

Token budgets control how much context Codex can consume per session. The project_doc_max_bytes setting in config.toml caps the total size of merged AGENTS.md content. In monorepos with deep hierarchies, the merged content can easily exceed this limit, causing Codex to truncate rules — potentially dropping critical constraints. The default is generous for single-project repos but often insufficient for large monorepos.

Context management is about more than token limits. Every line in AGENTS.md competes for attention in the model's context window. Verbose rules dilute important ones. A 300-line AGENTS.md with 50 rules performs worse than a 100-line AGENTS.md with 20 precise rules — not because of token limits, but because the model's attention is finite. Write rules like you are paying per word, because in a real sense, you are.

# Context management settings
project_doc_max_bytes = 65536      # Max merged AGENTS.md size (64 KB)

# Strategies for staying under budget:
# 1. Split rules into directory-scoped files (only loaded when relevant)
# 2. Move reference docs to separate files, link from AGENTS.md
# 3. Use terse rule format: one line per rule, no prose
# 4. Archive deprecated rules instead of commenting them out

# Monitor with: codex /status (shows loaded config size)

1. Measure current usage Run /status in every major workspace directory. Record the merged config size for each. Identify the largest.
2. Trim verbose rules Convert prose-style rules ("When writing tests, always make sure to include...") to terse format ("Tests: always include edge cases and error paths").
3. Split by scope Move workspace-specific rules out of root AGENTS.md into directory-scoped files. The root should contain only cross-cutting rules.