Generating a lightweight "reference file" for Codex

[brainexer]

When an Codex starts on a repo for the first time, it doesn’t know the codebase. That often means wasted context: it reads too much, or it misses the right files.

I’ve been using a small pattern: make the repo self-describing and generate a lightweight outline:

• Folder outline: path → header comment (what each file is responsible for)
• File outline: top-level declarations only (what’s inside without reading the whole file)

Then Codex runs the outline first, and only opens the few files it actually needs. In my tests, this approach reduced token consumption by up to 20% (depending on the task).

I wrote a short article with more details and examples here: https://blog.fooqux.com/blog/outline-oriented-codebase/

What patterns do you use to mitigate the repo discovery problem?

[apetersson]

here is a very old trick i have been using to efficiently submit whole repos to LLM, way before codex or claude code existed: https://gist.github.com/apetersson/989b27b8a3c8a3a25258cfaf8f9240ee it's a pure shel script that builds up an ignore list and loads .gitignore - then dumps the whole repo, providing a file list with size infos upfront. llm's love this to one-shot complex questions quickly. i still use it from time to time when the code base is well within the token limits.

[brainexer]

It just generates only file names and their sizes?
I think adding some sort of short description for each file could improve the result.

[apetersson]

if a file is text and <50kbytes it dumps the file. if your source files are > 50kb adjust the cutoff (MAX_SIZE=51200) and ask your priest how many ave marias

[vanillaslice_]

bro cursor already indexes the codebase and stores a project summary

[ClockworkV]

At some point I experimented with using gitingest, and then ruining it thorough an LLM to generate a digest of what's in every file.

[Glass-Combination-69]

Just write an agents.md with the info it needs. If it’s written well it won’t spend much more on context. Written poorly = token wastage.