Add an option to fall back to an alternative filename for the project-level instrucion file (AGENTS.md) if it's not present

Resolved 💬 0 comments Opened Sep 28, 2025 by byrongrogan Closed Oct 1, 2025

What feature would you like to see?

I'm looking at migrating some larger monorepos to work with Codex CLI, but Codex is currently hampered vs. other tooling we've already adopted by the lack of project-level docs (AGENTS.md vs CLAUDE.md).

Currently, in order to make this immediately work well with Codex CLI, we'd need to add AGENTS.md symlinks at each level of the project hierarchy that already has prior instruction files, across all of our repos. This is a bit of a mess when we have hundreds of projects and many repos where we'd need to do this.

So the request is: give us a config option that provides a fallback filename that you check when AGENTS.md doesn't exist at some level of the directory hierarchy. Concretely, this would just need to append to this single-item list here, based on a config option: https://github.com/openai/codex/blob/5c67dc3af12ab5426ba5002a90a50b24f1dcf8f9/codex-rs/core/src/project_doc.rs#L21

So with this, AGENTS.md would always be preferred if present (allowing people to migrate to better Codex-oriented prompting over time), but things would more or less "just work" immediately for repos/projects that already have prompts for other tools.

Are you interested in implementing this feature?

Happy to implement this if preferred.

Additional information

No response

View original on GitHub ↗