**What is the type of issue?** Documentation is missing **What is the issue?** The AGENTS.md loading budget has three behaviors that are implemented but documented nowhere in this repo (verified at `41ece455b7fa`, 2026-08-11): 1. **The cap**: `DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024` (`codex-rs/config/src/config_toml.rs:70`) limits the combined project-directory AGENTS.md chain. 2. **Truncation order**: files load root-first (`agents_md.rs` builds search dirs cwd→root then reverses), so whe

Docs: project_doc_max_bytes semantics are undocumented — the 22.5KB root AGENTS.md leaves ~9.7KB before nested files are truncated

Open 💬 1 comment Opened Aug 11, 2026 by StartupBros

What is the type of issue? Documentation is missing

What is the issue?

The AGENTS.md loading budget has three behaviors that are implemented but documented nowhere in this repo (verified at 41ece455b7fa, 2026-08-11):

The cap: DEFAULT_PROJECT_DOC_MAX_BYTES = 32 * 1024 (codex-rs/config/src/config_toml.rs:70) limits the combined project-directory AGENTS.md chain.
Truncation order: files load root-first (agents_md.rs builds search dirs cwd→root then reverses), so when the budget runs out, data.truncate(remaining) (agents_md.rs:130) hits the deepest, most-specific file first — with only a tracing::warn! to show for it.
The global file is exempt: ~/.codex/AGENTS.md loads in full via codex-home/src/instructions/mod.rs:24-67 with no length check — outside the budget entirely.

Why it matters here concretely: this repo's own root AGENTS.md is 22,519 bytes — ~70% of the default budget. A contributor working under codex-rs/tui/src/bottom_pane/ gets root + the 564-byte nested file = 23,083 bytes, leaving 9,685 bytes of headroom for any future nested files before silent leaf-first truncation. Nothing warns an AGENTS.md author that growing the root file shrinks the budget for every nested file in the tree.

grep -rn project_doc_max_bytes docs/ codex-rs --include='*.md' returns zero results; docs/agents_md.md is a 3-line pointer to the external guide. A short paragraph — in docs/config.md or the external agents-md guide — covering the cap, the leaf-first truncation order, and the global-file exemption would make this legible to both contributors and users tuning project_doc_max_bytes.

Where did you find it? codex-rs/config/src/config_toml.rs, codex-rs/core/src/config/mod.rs, the AGENTS.md loader (agents_md.rs), codex-home/src/instructions/mod.rs, and docs/. Found during an automated AGENTS.md audit (rent-check); all line references re-verified against source before filing.

View original on GitHub ↗

1 Comment

jdcodes1 · 9 days ago

Re-verified all three behaviors on current main (1f41cc5d92): the 32 KiB default (config/src/config_toml.rs#L71), root-first ordering with data.truncate(remaining) biting the deepest file (core/src/agents_md.rs#L115-L130, budget decrement at #L76), and the budget-exempt global file. Still true, still warn-level-only.

Two additions for whoever writes the docs paragraph: (1) the budget is consumed per environment in multi-environment turns — load_project_instructions iterates turn environments sharing one remaining counter (agents_md.rs#L52-L92), so with several environments the earlier environment's chain can starve the later one, another surprise worth a sentence; (2) the open feature request #38680 (explicit agents_files config list) proposes drawing from this same budget, which makes documenting the accounting more valuable — a config knob pointing at files that then get silently truncated leaf-first would be doubly confusing.

Beyond docs, a cheap legibility fix: when truncation actually fires, emit a user-visible warning (the TUI has warning cells) instead of only tracing::warn! — authors can't act on a signal they never see.