How Codex Actually Finds the Right Files

Watch (4:17)

Overview

AGENTS.md, skills, MCP, search, and compaction — the layers Codex uses to narrow a big repo down to a working set.

Full transcript (from the video)

If you ask codeex to fix a failing payments test, the useful question is not whether the model can hold your whole repository at once. The useful question is how it narrows the repo fast enough to act correctly. Codeex starts with rules, file maps, GP hits and a smaller working set. That is the mental model I want to give you first. Once you see that loop, the rest of the product stops feeling magical. Codeex does not become repoaware by osmosis. It loads a structured environment before it starts making serious decisions. Instructions tell it how this repo wants work done.

Capabilities tell it which tools and servers exist. Current context tells it what this task needs right now. Then the runtime turns the outcome back into reviewable artifacts like diffs, command output, and findings. Repo awareness is loaded, not guessed. Agents.mmd is one of the clearest reasons Codeex can feel repoare without pretending it has memorized the whole codebase. OpenAI documents progressive loading from the repository route down to the current working directory with at most one instruction file per level. That means the repo can narrow the search space before code reading even starts. The best agents files stay operational. They name canonical commands, generated paths, approval boundaries, and what done looks like. Skills solve a different problem from agents.md.

Agents files keep the always on repo rules small. Skills hold the heavier workflow packs that should not bloat every session. Open AI documents progressive disclosure here too. Codeex starts with skill metadata then loads the full skill.md only if the task actually matches. That is a clean architecture pattern. Small durable rules up front. heavier named procedures only when they matter. MCP is separate from repo instructions. It extends the tool surface, open AI documents, local servers, remote servers, and per server tool lists that gives you a simple debugging rule. If Codeex behaves incorrectly in this repo, inspect agents and skills. If Codeex exposes the wrong external tools, inspect MCP registration and tool gating. This is the main correction to the whole repo myth.

Codeex is not strongest when it tries to stuff everything into one giant turn. It is strongest when the runtime keeps rebuilding a smaller working set. Search narrows candidates reads confirm the right tool output becomes fresh evidence. If the session gets long, compaction carries forward the decisions instead of the whole raw transcript.

That is why repo understanding behaves more like a loop than a single prompt.

Repo awareness is not only about finding the right files. It is also about knowing what the agent is allowed to do once it finds them. OpenAI's codeex docs separate sandboxing from approvals for a reason. The sandbox is the technical boundary. The approval policy is the human stop line. That split is what lets Codeex work productively inside a repo without pretending one vague safe mode solves every risk question. The same repo aware loop shows up again when Codeex runs remotely. Open AI documents cloud tasks as worker environments that create a container. Check out the selected branch or commit run setup apply internet settings and then let the agent work. The docs also say agents.mmd can help the agent find repos specific lint and test commands there too. Then review closes the loop through /re the app review pane or github review comments. The practical takeaway is simple. If you want codeex to understand your repo better, do not only change the model, change the environment the model is stepping into. Keep agents.md short and operational. Put heavyweight playbooks into skills. Register narrower MCP servers. Name the real commands, file boundaries, and approval rules. The more inspectable the repo control surface is, the more predictable the codec session becomes.