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

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.

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

a deep read.

1. 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

1. 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_