OpenAI Codex-1 Agent Maximum Context Tokens

Do not make a token count the thing your team manages. A written context budget in your AGENTS.md, a narrow task handoff, and a verification loop that proves the diff still fits the codebase will carry you further than any maximum number. A context budget is a short, agreed rule for how much and what kind of information you hand an agent for a single task.

Codex CLI, OpenAI's coding agent that runs in your terminal, does its best work when you treat context as a scarce input rather than a place to dump the whole repo. That is the same habit we teach in cli-workflows training: small task, local rules, reviewable diff.

Why a bigger context window does not fix the real problem

More access and more tokens do not automatically produce better engineering. If your team makes the maximum context number the main planning question, you tend to miss what actually went wrong: the agent had unclear authority, stale knowledge of the repo, or no test command to run.

Picture the usual failure. You ask Codex to "fix auth," paste a long issue thread, attach five files of background, and hope a large window saves you. Then you review a sprawling diff with weak intent, argue about whether the agent "understood" the code, and quietly redo the work by hand.

That is context sprawl. It happens when teams use model capacity to cover for missing conventions. The agent sees more text. It does not see the right text. The durable fix lives in your repo, not in your token settings.

How to give Codex a clean task handoff

Start every task with a task envelope: one paragraph naming the file area, the behavior you want, the files not to touch, and the test command. This is the single most useful habit, because it forces you to know the change before the agent does.

Keep your AGENTS.md scoped instead of flat. A root AGENTS.md holds durable global rules like the build system and review expectations. Nested AGENTS.md files in high-change folders hold local rules for a service, package, or migration set. When two rules conflict, the more local one wins.

Make external context visible. MCP can connect a coding workflow to outside systems, but the agent should not treat every connected system as authority. Write an MCP boundary note that says which systems are read-only, which may create work, and which facts must be copied into the PR. The MCP spec is at modelcontextprotocol.io.

A copyable AGENTS.md convention

Put the convention where the agent and your reviewers both see it. For most teams that means a root AGENTS.md plus nested files in the folders that change most often.

# AGENTS.md: Codex context and verification convention

## Context budget
- Start each Codex CLI task with a one-paragraph task envelope.
- Include only the issue, files, errors, and constraints this change needs.
- Do not paste long transcripts when a short summary and links will do.
- Prefer local package instructions over broad repo guesses.

## Scope rules
- Root AGENTS.md holds repo-wide rules: build system, security, review expectations.
- Nested AGENTS.md files hold local rules for services, packages, migrations, tests.
- If two instructions conflict, the more local one wins unless a maintainer overrides it.

## MCP boundary
- Treat MCP-connected systems as context sources, not automatic approval.
- Read-only systems may inform the plan.
- Write actions outside the repo need explicit human approval in the task envelope.
- Copy any external fact used for the change into the PR notes.

## Verification loop
Before handing off a diff, record:
- Command run:
- Result:
- Files changed:
- Risk area:
- Tests skipped, if any:
- Human review needed from:

## Stop conditions
Stop and ask before changing auth, billing, data deletion, migrations, secrets, or public APIs.
Stop if the task needs context not present in the repo, issue, AGENTS.md, or an approved MCP source.

Roll this out as a small reviewed PR, not a policy memo. A tech lead proposes it, two frequent reviewers edit it, and each package owner decides whether a nested file is worth adding.

How to know the convention is working

A Codex-generated PR is ready when a reviewer can approve or reject it from the artifact and the evidence alone, without replaying the chat. If they still have to reconstruct the session to understand the change, the workflow is doing too much in their head and not enough on the page.

Run a quick check on the next few automated PRs.

- [ ] The PR names the AGENTS.md rule or MCP note it relied on.
- [ ] The verification footer lists the command run and its result.
- [ ] The first step is small enough to inspect without replaying the whole session.
- [ ] There is a one-line rollback path next to the change.

If most PRs clear that list, your context budget is doing its job. If they do not, tighten the task envelope before you touch any model setting.

Common questions

• Is there a fixed maximum context token number for Codex?

  Treat it as a workflow question, not a magic number. Even when a model exposes a large window, filling it rarely improves output and often hides intent. The reliable lever is a written context budget plus a task envelope, so the agent receives the issue, the files, and the test command rather than the entire repository.

• What goes in a task envelope?

  One short paragraph: the file area to change, the behavior you want, the files the agent must not touch, and the command to verify the result. That framing forces you to understand the change before delegating it, which is most of the value. Anything the agent genuinely needs beyond that belongs in AGENTS.md or a linked issue.

• Where should context rules live, root or nested AGENTS.md?

  Both, by scope. Root AGENTS.md holds durable repo-wide rules like the build system, security expectations, and review standards. Nested AGENTS.md files sit in high-change folders and carry local rules for one service, package, or migration set. When a global rule and a local rule disagree, the more local instruction wins unless a maintainer overrides it.

• How do I keep MCP context from becoming silent authority?

  Write an MCP boundary note. State which connected systems are read-only and may only inform the plan, which may create work items, and which facts must be copied into the PR description. Write actions outside the repository should require explicit human approval named in the task envelope, never an implicit grant from the connection.

Where to take this next

Pick the one folder that changes most this week and add a nested AGENTS.md with a context budget and a verification footer. Then take it into cli-workflows training and check whether a new reviewer can defend the merge without replaying the chat.

Further reading

• OpenAI developers: codex quickstart
• OpenAI developers: codex cli
• OpenAI developers: cli features
• OpenAI developers: cli slash commands
• MCP docs: specification 2025 11 25
• github.com: openai codex
• github.com: openai skills