Add a 'project atlas' so codex cli knows the entire project layout at each startup

Resolved 💬 6 comments Opened Jan 3, 2026 by styler-ai Closed Mar 20, 2026

💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

What feature would you like to see?

Codex CLI struggles keeping an orientation in complex repos and projects you start a new session without a structural overview or alternatively the context is blown up with an orientation of the project at startup or after /compact.

Result is:

Codex duplicate folders and files appear because intent is not visible.
A clean folder structure slowly drifts into a mess.

I fixed this with ProjectAtlas by creating a lightweight, human- and agent-readable map that sits above deep code search. It answers "where should I look?" and "where should I put this?" before running heavy indexing tools or worse: reading files and folders with get-content.

I would like to see something similar or better to be included in Codex CLI directly, I just implemented it to compensate for the lack of it in Codex and because I currently can't contribute to the codex cli project.

How it works

ProjectAtlas is designed for the first 60 seconds of an agent session.

Each folder carries a .purpose file with a one-line summary so folder intent is explicit (no guesswork).
Each tracked source file starts with a Purpose: header or module docstring so file intent is visible without

a deep read.

projectatlas map builds a TOON snapshot (.projectatlas/projectatlas.toon) that contains:

a folder tree with inline purpose summaries
file summaries for targeted code reads
duplicate-summary warnings to spot drift
overview stats that show scope and coverage

projectatlas lint fails when Purpose headers or .purpose files are missing. The goal is to force a decision

before you proceed: add the missing summary, or remove/relocate the folder/file if it no longer belongs.

Why this matters:

Agents read the atlas at startup (via AGENTS.md) to decide where to look next.
The atlas tells you which files to open with deep-indexing tools (for example code-index MCP or language

servers) so you only deep-index what you actually need. Deep indexing here means full-file or symbol-level
analysis that can consume a lot of context if you run it blindly.

The lint gate keeps structure healthy over time by preventing silent drift.

You can look it up here, it's not perfect but I didn't see a single structure shift after using it with Codex CLI and the amount of context needed after startup droped siginificantly in combination with code-index since codex cli knows now exactly which file to lookup etc.

https://github.com/styler-ai/ProjectAtlas

Additional information

_No response_

View original on GitHub ↗

6 Comments

etraut-openai contributor · 7 months ago

Interesting idea. Thanks for sharing.

I'm curious about the following:

Did you manually create all the .purpose files, or did you use Codex or some other agent to generate them initially? What about the purpose header comments? I'm wondering how much work this entails.
Do you find that the .purpose files drift from reality over time? Or are folders generally stable enough that their purpose doesn't shift over time? If they do shift, have you found ways to automate the update of .purpose files?
Same question about Purpose header comments? Do you find that these drift over time? How do you prevent them from becoming out of date?

styler-ai · 7 months ago

Interesting idea. Thanks for sharing. I'm curious about the following: 1. Did you manually create all the .purpose files, or did you use Codex or some other agent to generate them initially? What 2. Do you find that the .purpose files drift from reality over time? Or are folders generally stable enough that their purpose doesn't shift over time? If they do shift, have you found ways to automate the update of .purpose files?

3. Same question about Purpose header comments? Do you find that these drift over time? How do you prevent them from becoming out of date?

1:
What I do is: I build a new lint rule into my CI build, so I have one project thats pure typescript so it's npm, I let my build fail as soon as a purpose header in a source file or purpose file in a folder is missing and I added an instruction in AGents.md so codex cli fixes these purpose files once they fail. the first time takes quite a while for long running projects, as expected, beauty of it: it's only done once. I let codex do 90% of the work, just reviewed it for the first time, but it didn't do any mistakes to be honest, since i used code-index to get a good summary, then i let codex reduce this to a one liner.

2:3:
I let codex update the purpose files if there is a major shift or refactoring, but the thing is: The purpose one liner is so high level that once they are setup there is almost no drift since the purpose of a file doesn't drift even after a refactoring most of the time. The logic how you do it can change, but what you want to do very rarely does and if so, you most probably need a new source file anyway, so the file gets deleted anyway.

etraut-openai contributor · 7 months ago

Thanks for the response.

This approach sounds like it's somewhat specific to your preferred approach to managing your code base. Other developers and code bases likely use similar (bug somewhat different) mechanisms. For example, it's not uncommon to include a README.md in major subdirectories to describe their purpose. You'll see that we do this at the crate level in the Codex source base. Many code bases also include a header comment in every file but don't label that comment with "Purpose". Also, features that we bake into Codex need to be language neutral, since Codex is used with a wide variety of programming languages.

For those reasons, I don't know if it makes sense for us to incorporate something this specific into Codex. On the other hand, this general pattern sounds like a good one to use with Codex (or coding agents in general), so maybe we could turn it into a "cookbook" or a "guide" that complements the base functionality in Codex.

Is there any specific support you would need in Codex to make your approach work better, or do the existing mechanisms (AGENTS.md, skills, model steerability, etc.) already work well?

styler-ai · 7 months ago

Thanks for the response. This approach sounds like it's somewhat specific to your preferred approach to managing your code base. Other developers and code bases likely use similar (bug somewhat different) mechanisms. For example, it's not uncommon to include a README.md in major subdirectories to describe their purpose. You'll see that we do this at the crate level in the Codex source base. Many code bases also include a header comment in every file but don't label that comment with "Purpose". Also, features that we bake into Codex need to be language neutral, since Codex is used with a wide variety of programming languages. For those reasons, I don't know if it makes sense for us to incorporate something this specific into Codex. On the other hand, this general pattern sounds like a good one to use with Codex (or coding agents in general), so maybe we could turn it into a "cookbook" or a "guide" that complements the base functionality in Codex. Is there any specific support you would need in Codex to make your approach work better, or do the existing mechanisms (AGENTS.md, skills, model steerability, etc.) already work well?

Thank you. My solution is language neutral my typescript project was just an example, I explained it in detail on my github page. It just generates a complete map of the project after each build. ProjectAtlas is build with python, works perfectly fine also there.
It depends on codex to maintain the purpose files and uses lint to point codex to the changes in the project.
The thing is that without a solution like this codex will keep drifting over time and after compact.
Maybe you could test it once to see if it makes sense?

If not included in codex, what would help the community imho is to include the skill I wrote and added to my github repo into the openai Codex skill folder and point to my ProjectAtlas project as an example and blueprint. That would be great.

styler-ai · 7 months ago

Thanks for the response. This approach sounds like it's somewhat specific to your preferred approach to managing your code base. Other developers and code bases likely use similar (bug somewhat different) mechanisms. For example, it's not uncommon to include a README.md in major subdirectories to describe their purpose. You'll see that we do this at the crate level in the Codex source base. Many code bases also include a header comment in every file but don't label that comment with "Purpose". Also, features that we bake into Codex need to be language neutral, since Codex is used with a wide variety of programming languages. For those reasons, I don't know if it makes sense for us to incorporate something this specific into Codex. On the other hand, this general pattern sounds like a good one to use with Codex (or coding agents in general), so maybe we could turn it into a "cookbook" or a "guide" that complements the base functionality in Codex. Is there any specific support you would need in Codex to make your approach work better, or do the existing mechanisms (AGENTS.md, skills, model steerability, etc.) already work well?

Hey I reworked it a bit and released a new version. You can now configure the programming language, should work fine now imho. Thanks again for the feedback

etraut-openai contributor · 5 months ago

This feature request hasn't received enough upvotes, so closing.