Why Codex uses so many tokens in large repositories

A coding agent does not begin with your team's mental model. Before it can change a small function, it may need to discover the package layout, conventions, callers, tests, build commands, and the boundary between relevant and irrelevant code.

On a compact repository, that orientation is cheap. On a monorepo, an innocent search can return thousands of lines. A test command can stream an entire build log. Each result becomes part of the conversation that the model processes again on the next turn.

The important distinction is between task context and conversation context. Task context is the evidence required to make the current decision: the relevant interface, its callers, the local convention, and the tests that define success. Conversation context also contains every detour taken to find that evidence. Both consume attention, but only one directly improves the change. The open-source Codex repository describes this context as the history of messages sent to the model and requires injected items to remain bounded in size. Read the Codex context guidance.

The context window is not just a memory limit. It is the working surface the agent pays to revisit on every step.

This is why a short implementation can consume more usage than a larger but well-scoped task. The cost follows the path to the answer, not the number of lines in the answer.

The effect compounds. A noisy search makes the next reasoning step larger; that step produces a longer plan; the longer plan is then carried into tool calls, edits, and verification. When the session is compacted or handed off, the agent may repeat part of the same discovery. The original read was not a one-time expense—it changed the cost profile of everything that followed.

Most teams optimize prompts first. Prompt length matters, but real sessions accumulate far more context through repository exploration and tool output. Four patterns deserve attention.

A useful audit separates inputs by the decision they supported. If a file read changed the plan, exposed a constraint, or prevented a regression, it was productive evidence. If it merely confirmed a fact that was already available in a closer source, it was navigation overhead. This framing is more actionable than labeling every token as either good or bad.

Notice that the largest line item is often not source code. Generated schemas, package-manager output, stack traces, repeated diffs, and verbose test reporters can dominate a session while contributing only a few decisive facts. The agent still has to process the surrounding text to recover those facts.

# Before reading broadly
1. State the decision the next read must support.
2. Read the smallest relevant range first.
3. Cap outputs with unknown size.
4. Preserve conclusions; do not repeat discovery.

An agent-readable repository is not one with the most documentation. It is one where the agent can find the right level of detail in a few deliberate steps.

That requires progressive disclosure. The repository root should answer orientation questions; package instructions should define local rules; implementation files and tests should provide the final evidence. When all three layers are collapsed into one enormous guide, every task pays for details that belong to other packages and other kinds of work. OpenAI reports using the same pattern internally: a short AGENTS.md acts as a map to deeper, versioned sources of truth. See OpenAI's harness-engineering practice.

Use context as navigation

A root AGENTS.md should explain where truth lives, which commands validate the work, and which boundaries are non-negotiable. It should not duplicate every package README. Supercode's Context Boosting addresses the adjacent orientation problem by building a size-limited project layout before the main work; depending on the request, it can also return no additional boost.

Commands are part of the information architecture too. A focused test command, a concise typecheck, and a diff that excludes generated artifacts are not merely developer conveniences. They are interfaces that return a smaller, higher-signal description of repository state.

The goal is not to prevent broad exploration entirely. Sometimes an architectural change genuinely requires it. The goal is to make broad exploration an explicit escalation step rather than the default starting point for every task.

Repository structure sets the ceiling, but the working environment also shapes what enters the session. Supercode's Token Optimization Basic reduces noisy or repetitive command output sent to the agent. Max also targets redundant exploration, repeated calls, and avoidable rework. Actual savings depend on the task, tools, and generated output.

Treat optimization as a sequence of interventions rather than a guaranteed compression result. Before a run, select only relevant instructions and skills. During discovery, scope reads and command output. Before a handoff, record decisions that would otherwise require another investigation.

Evaluate the result as a ratio between context consumed and validated work completed. Token reduction is not evidence of a better result by itself: required checks and task quality must remain explicit guardrails. If that trade-off matches your workflow, review the Supercode for Codex installation requirements.

Token reduction is useful only when task quality survives. Compare equivalent tasks and record context growth, repeated reads, command-output volume, elapsed time, test coverage, and whether the final change solved the problem.

Start with repeated task archetypes rather than isolated demos: a small bug fix, a cross-package refactor, a failing test investigation, and a documentation change. Run each archetype with the same acceptance criteria, then compare the path the agent took—not only the final message.

Separate productive evidence from navigation noise, and never report savings without the success criteria beside them.

A session that uses 30% fewer tokens but misses a caller or skips the required test is not an optimization. A session that consumes slightly more context yet eliminates a restart may be. Report the distribution across tasks and preserve failed runs; averages built only from successful demos will hide the cases where context management matters most.

Use this checklist as a preflight for repositories, agent instructions, and the commands exposed to Codex. The items are deliberately operational: each one can be reviewed, tested, and assigned to an owner.

• Give each task a specific package and outcome.
• Keep root instructions short and navigational.
• Read ranges before entire files.
• Exclude generated data from broad search.
• Cap logs and diffs without hiding failures.
• Write down decisions before switching threads.
• Compare quality alongside token usage.
• Remove stale and contradictory instructions.

Do not try to implement every item at once. Begin with the two highest-volume sources in real sessions, measure the change, and keep the intervention only if completion quality remains stable. Context engineering works best as an operating discipline, not as a one-time cleanup project.