`AGENTS.md` is silently truncated without any warning within the TUI

Thanks for the feature request. If we add this, we'll need to figure out how to surface this across all surfaces including the TUI, exec, and VS Code extension.

@etraut-openai thank you - it's difficult to classify this as a feature, it probably also is not a bug but it does indeed _lead_ to bugs. Primarily, for weeks I was under the impression codex isn't adhering to instructions given in AGENTS.md and I kept repeating myself within each session start, only to find out that codex silently truncates AGENTS.md which means important instructions are being clipped / dropped off and codex continues to do the wrong thing when applying fixes (our instructions include specific commands of running and inspecting unit tests and it would get these wrong 100% of the times).

With project_doc_max_bytes set to 80kb it now _fixes_ this for me but this resulted in numerous other issues as you can see.

At the very least, we should document the AGENTS.md behavior more clearly.

At the very least, we should document the AGENTS.md behavior more clearly.

Yes, that would be helpful. On that front, I'll note that there are probably 5 separate documents (some on github, some on openai.com) that describe AGENTS.md, all slightly different and none of them being clearly the authoritative comprehensive version. Also, I personally find http://agents.md/ pretty useless as a source of information so am a little annoyed how often it's referenced in the docs as a place to find more detailed information. What the user wants to know is specifically how AGENTS.md is handled in the codex harness (e.g. this very important truncation parameter), not the generic philosophy behind it.

On that front, I'll note that there are probably 5 separate documents (some on github, some on openai.com) that describe AGENTS.md, all slightly different and none of them being clearly the authoritative comprehensive version.

I'm also not authoritative but here's what I understand on how this works:
If codex is started in a sub-directory of the repository, or you use the -cd <dir> option (/status reports it as Directory), then CLI searches that cwd and all directories down to the root of the project, in that order, for AGENTS.override.md and if that doesn't exist for AGENTS.md (per directory).

You can copy the roots AGENTS.md to AGENTS.override.md and then edit it to be more like what you need/want (maybe make it shorter). That file is already in .gitignore

I start mine with:

AGENTS.override.md -this file- is the authoritative set. Follow this and ignore AGENTS.md in the same directory.

just to be sure - but that is how it should already be.

I am not sure of the 32kB truncation is per-file or for all AGENTS*.md's combined. If it is per file you can use the above to split it up in multiple AGENTS.md files with instructions limited to those specific to that (sub)directory.

You should also be able to add a $CODEX_HOME/AGENTS.md (the default of CODEX_HOME being ~/.codex). For even more general instructions that apply to every project.

I noted that the following works:

### Additional instructions

- If a file exists in the root of the project with the name `README-<current_branch>.md` then follow the instructions inside of it as well.
  Instructions in that file are more important than those in this file, because they are specific to what is being worked on at this moment.

allowing me to add instructions / explanations per-(feature)-branch.

Wow, I didn’t even realize it currently works this way — thank you, @guidedways, for surfacing it.

The only workaround I’ve found so far is to explicitly reference important sub-Markdown files from AGENTS.md and then ask Codex to read them during bootstrap.

This approach slows down the initial response to up to ~10 minutes on a context-dense project, but at least everything gets loaded without truncation into the context window, and Codex actually pays attention to those referenced .md files.

However, when the context usage reaches around ~30% and ~50%, some background compaction seems to happen, and I have to ask it to re-read those initial instructions again, because Codex starts to “forget” the essential parts of AGENTS.md (for me, they’re indispensable).

The worst case scenario is when the context window is ~85% full: the session basically “resets” during the answer, like a Groundhog Day wake-up. Hopefully it re-reads every instruction from the beginning, again, but from the user’s perspective it feels like starting over.

Honestly, I’d be totally fine with AGENTS.md taking up to 80% of the context, leaving only ~20% for a single “shot”, rather than having to rely on these workarounds.

I'm also not authoritative but here's what I understand on how this works: If codex is started in a sub-directory of the repository, or you use the -cd <dir> option (/status reports it as Directory), then CLI searches that cwd and all directories down to the root of the project, in that order, for AGENTS.override.md and if that doesn't exist for AGENTS.md (per directory).

How does codex know what the "root of the project" is? What if I start codex in a random directory that isn't a git repo, does it just go up the file tree until it's at /? That seems unlikely.

@nwalke If you don't use -cd <dir>, then whatever directory you're in when you start Codex

Edit: I went back and re-read the doc that was added last month. I must have completely spaced on this as it answers my question.

- The search starts at the repository root and continues down to your current directory. If a Git root is not found, only the current directory is checked. - In each directory along that path, Codex looks for AGENTS.override.md first, then AGENTS.md, and then any fallback names listed in your Codex configuration (see [project_doc_fallback_filenames](../docs/config.md#project_doc_fallback_filenames)). At most one file per directory is included. - Files are read in order from root to leaf and joined together with blank lines. Empty files are skipped, and very large files are truncated once the combined size reaches 32 KiB (the default [project_doc_max_bytes](../docs/config.md#project_doc_max_bytes) limit). If you need more space, split guidance across nested directories or raise the limit in your configuration.

Apologies for the noise :)

This feature request hasn't received any upvotes in three months, so I'm going to close.

I think the existing upvotes were hoping this would get resolved 😅 This is one of those 'hidden' bugs many aren't even aware of, so perhaps a lot of people running into this just feel their AGENT.md is sometimes being ignored.

Files are read in order from root to leaf and joined together with blank lines. Empty files are skipped, and very large files are truncated once the combined size reaches 32 KiB (the default [project_doc_max_bytes](https://github.com/openai/codex/docs/config.md#project_doc_max_bytes) limit). If you need more space, split guidance across nested directories or raise the limit in your configuration.

This seems to be a contradiction. Lets say R/ is the root of the project and you start Codex in R/S/T/ then I understand that the Codex CLI catenates R/AGENTS.md + empty line + R/S/AGENTS.md + empty line + R/S/T/AGENTS.md. If the total of that size goes over project_doc_max_bytes then this is silently truncated (yup, no idea why that has to be silent due to a "lack of votes" - you could also just fix it). The result is sent upstream as system message.

Then "if you need more space use nested directories". Huh? Those are catenated, so how is that helping?

I agree - truncating AGENTS should not be silent. If AGENTS is large, it's because the user wants to give the agent more instructions. Honestly, I feel it shouldn't be truncated at all, but if it's going to, there absolutely needs to be a warning.

@etraut-openai can the decision to close this issue be reconsidered?

@etraut-openai another point, recently I saw you push a change where the prompt was limited to 1MB (to match the max context window size - given larger prompts just don't make sense) - a fix to this would simply compliement that commit; I fear silently trimming AGENT.md is terrible UX for the end-user.

@guidedways, you can open a new feature request if you'd like. As you know, we generally prioritize feature requests based on upvotes. If a feature request doesn't get enough upvotes or receives no upvotes in a long time, that means it's either not a high priority for the Codex community or the description of the feature request wasn't compelling enough to attract upvotes. By opening a new feature request, you can give it a new title and description and see if that might attract more upvotes.

@etraut-openai thank you! I'll try and re-word in the process, and hope that it attracts more eyeballs this time 👀

Dear upvoters of the current issue, please unleash a flurry of votes here: https://github.com/openai/codex/issues/13386

😅