Codex · Series · Part 3 of 8

Fewer tokens, faster onboarding: making AGENTS.md pay for itself

By now you have an AGENTS.md (Part 2). Two questions remain. Does it really save tokens, or does it just add more? And can it help when you join a new project or start a new feature? The honest answers: yes, if you keep it lean, and yes, and this is where I find it most valuable.

1. Tokens and the context window

Everything Codex sees is text, counted in tokens. The official pricing page describes them as small units of information that are read and written: your prompt, files, chat history, tool results and the model's response all use tokens. As a rough guide a token is a short chunk of a word. Your usage allowance, the speed of replies and the size of the context window (how much the model can hold in mind at once) are all measured in them. A chat spends tokens in four places:

The docs add a warning that is worth remembering: even with large context windows, models have limits. If the main chat fills with noisy output (exploration notes, test logs, stack traces), the docs say the session can become less reliable over time. They name two effects, context pollution (useful information gets buried under noise) and context rot (performance degrades as the chat fills with less relevant detail). So a lean context is not only cheaper. It is also better.

2. How usage is measured and limited

How Codex is billed depends on how you sign in (Part 1). The details below come from the official Pricing page, and I will not invent any numbers that are not there. Prices and limits change, so treat this section as a snapshot of 18 October 2026.

Two ways to pay

The docs also say ChatGPT Work and Codex share usage: they use the same pricing, credits and usage limits.

What decides how fast you use your allowance

The FAQ is direct about this. The number of messages you can send depends on the model, the size and complexity of your tasks, and whether you run them locally or in the cloud. Small scripts or routine functions may use only a fraction of your allowance, while larger projects, long-running tasks, or sessions where the agent holds more context use significantly more per message. Tasks that look similar can consume different amounts. Model choice, context, reasoning, tool use, retrieval and caching all affect usage, so prompt length alone is not a reliable estimate.

For Plus and Standard Business, the page gives these estimates of local messages per five-hour period. It stresses they are not fixed message limits, and that your usage dashboard has the real limits and reset times. Pro plans currently have no five-hour limit, and weekly limits may also apply.

Read the shape, not the digits: the lighter the model, the more messages the same allowance buys. Local messages and cloud chats share one allowance, and cloud tasks may use more of it than local messages.

Credits and what happens at the limit

• Credits are the unit used to pay for eligible usage on credit-based plans. After you reach your included limits, available credits let you continue working.
• Plus and Pro users who reach their limit can purchase additional credits instead of upgrading. Business, Edu and Enterprise plans with flexible pricing can purchase additional workspace credits.
• An active turn is not cut off. If you reach your limit during a turn, the agent can continue that turn, subject to fair use limits.
• An API key is the escape hatch. The FAQ says all users may also run extra local chats using an API key, charged at standard API rates.
• Workspace admins may have usage limits and spend controls on their side. The docs say these apply to eligible activity under a workspace plan, which can include some Codex activity, and that they do not govern OpenAI API Platform billing. Part 7 comes back to teams.

The token rate card, for credit-based usage

The Pricing page lists Standard-speed credit rates per million tokens. A few rows, copied as written:

Three things to take from it. Output costs more than input, per token. Cached input is much cheaper than fresh input (for GPT-6.1 Sol, 2.5 against 50). And the page notes that Codex credit billing has no separate cache-write charge. The page also says the credit rates alone do not decide your included subscription usage, and that API token prices are separate from subscription usage, so do not use them to estimate how many tasks your plan includes. It lists more models than the three above; see the page for the full table.

3. How to check what you are spending

Saving tokens only works if you can see them. These are the views the docs describe.

Where to look

The docs give this advice about the dashboard: check it every week or two to understand your pace and remaining capacity, and if usage is higher than expected, consider whether a smaller model or tighter task scope would still produce a useful result.

A worked estimate you can do by hand

You can check the order of magnitude yourself with the rate card above. Suppose one request sends 100,000 input tokens and gets 5,000 tokens back from GPT-6.1 Sol, with nothing cached:

input : 100,000 / 1,000,000 x 50  credits = 5.00 credits
output:   5,000 / 1,000,000 x 250 credits = 1.25 credits
total                                      = 6.25 credits   (Standard speed, no caching)

Now suppose 90,000 of those input tokens were a cache hit:

fresh input : 10,000 / 1,000,000 x 50  = 0.500 credits
cached input: 90,000 / 1,000,000 x 2.5 = 0.225 credits
output      :  5,000 / 1,000,000 x 250 = 1.250 credits
total                                  = 1.975 credits

These are arithmetic illustrations of how the published rates combine, not a prediction of your usage. Real tasks make many requests, and on a ChatGPT plan the credits only matter once you are past your included limits. For scale, the Pricing page itself says a typical GPT-5.6 Sol task may use 2-15 credits.

Why usage climbs in a long chat

• Long context: the more the chat holds, the more every turn draws on. Tasks that require the agent to hold more context use significantly more per message, says the FAQ.
• Tools: the FAQ lists tool use and retrieval as usage factors, and says every MCP server adds more context to your messages. Turn off MCP servers you do not need.
• Parallel agents: the subagents guide says subagent workflows consume more tokens than comparable single-agent runs, because each subagent does its own model and tool work. They are worth it for big tasks, not for small ones.
• Reasoning and speed settings: higher reasoning effort and faster modes both use more (section 7).

4. How AGENTS.md saves tokens

Think about what Codex does on a project it has never seen. To answer “how do I run the tests?” it must search, open the build files, read the README, maybe try a wrong command first. Each step reads files (tokens in), reasons (tokens out), and adds to the conversation. A one-line note in AGENTS.md replaces all of that.

Four separate savings add up:

• No re-explaining. You stop typing the same background into every chat. The best-practices guide lists “overloading the prompt with durable rules instead of moving them into AGENTS.md or a skill” as a common mistake.
• Less blind exploration. A folder map lets Codex open the right file first instead of reading five wrong ones. The guide recommends covering repo layout, how to run the project, build, test and lint commands, conventions, do-not rules, and what done means.
• Fewer wrong turns. A recorded gotcha prevents an attempt, a failure and a retry. The guide suggests that when Codex makes the same mistake twice, you ask it for a retrospective and update AGENTS.md.
• Cheaper to re-read. Repeated content can be billed at the cached-input rate, which the rate card shows is much lower than the fresh-input rate. I cannot tell you from the docs exactly which tokens in your session hit the cache, so treat this as a likely bonus rather than a promise.

One more fact from the AGENTS.md guide matters for cost: Codex builds its instruction chain once per run (in the TUI, once per launched session) and includes a limited amount of project guidance in the first turn. It stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. So the file is a bounded, one-time cost per session, and the cap protects you from a runaway file. It does not mean 32 KiB is a good target (section 6).

5. Does Codex get better after 10 days?

This is the question I get asked most, so let me answer it straight. What carries from one chat to the next is what is written down, not what happened in yesterday's chat. The docs say a chat keeps its own transcript and recorded working directory, while Codex reads files from the current working tree, and they tell you to keep durable project guidance in AGENTS.md or checked-in documentation so it is available to future chats. A fresh chat on day 10 starts as blank as on day 1, apart from the files you have written.

Yet day 10 can feel cheaper and faster. The difference is in your notes and your habits.

What does and does not get faster

So a task takes less time not because each reply streams faster, but because it needs fewer replies. A large, stale context does the opposite.

Things that do not give you savings

• Resuming an old chat. /resume (or codex resume from your terminal) reloads the selected chat's transcript so you can pick up where you left off. That is great for continuity, but the old text is back in the conversation, so do not expect it to be cheaper than starting fresh with a short note.
• Plan mode on its own. The plan lives in the chat. To keep it, ask Codex to write it into a file and link it (section 9).
• Memories. Codex has local memories, which are off by default. When enabled, Codex can turn useful context from eligible earlier chats into local memory files under ~/.codex/memories/. The docs call them a helpful recall layer and say to keep required team guidance in AGENTS.md or checked-in documentation, not only in memories. Memories are generated in the background and may not appear right away. Use /memories to control per chat whether memories are used or generated. The point here is: memory is still saved text, not a smarter model, and it is no substitute for a file your team can read and review.

A two-minute end-of-day habit

1. Write down what surprised you. A wrong turn, a command that failed, a rule you had to repeat. Add it to AGENTS.md or the feature note.
2. Delete one stale line. Anything that is no longer true or no longer needed.
3. Save the plan, not the chat. If tomorrow continues today's work, write a handoff note (below) so the next step is in a file.

Do this for ten days and day 10 really is easier, because you taught the next chat. The honest way to put it: Codex does not get smarter or faster, it gets less lost.

The handoff note: what “remember this session” should really be

It is tempting to end a day by typing “remember this”. That alone saves nothing unless a file gets written. A reliable version is an explicit handoff note. Chats can be continued (/resume, codex resume, or codex resume --last for the most recent chat in the current directory), but a note in the repository is smaller, readable, reviewable and shared with your team.

Before I close this chat, write a handoff note to docs/notes/2026-10-18.md:
- what we finished
- decisions made, and why
- what is still broken or unfinished
- the exact next step
Then add one line to AGENTS.md pointing to that file.

Next morning, start a new chat with: “Read docs/notes/2026-10-18.md and continue.” That starts small, and you can read and correct the note first.

• Check that it happened. Run /diff in the CLI (it shows staged, unstaged and untracked files) or git diff. No file change means nothing was kept.
• Read the note before you trust it. A summary keeps only what Codex chose to include, and subtle details can be lost.
• Keep secrets out. Never put passwords or keys in a note.
• Prune old notes. Keep the latest handoff linked, and archive or delete the rest so AGENTS.md stays lean.
• Need the whole transcript? /export session.md exports the conversation as Markdown (wait for the current turn to finish first). Useful as a record, but too big to be a handoff.

6. When it costs more than it saves

The file is loaded at the start of every session, even for a tiny question. A huge AGENTS.md pays that price on “what does this function do?” as well. The balance depends on how long and how relevant it is:

Practical limits that keep you near the sweet spot:

• Keep it short and practical. The best-practices guide says a short, accurate AGENTS.md is more useful than a long file full of vague rules, and to add new rules only after you notice repeated mistakes. The docs do not give a line count, so I will not either. The 32 KiB default cap is a ceiling, not a goal.
• Nest instead of bloating. The Pricing page tip says: if you work on a larger project, control how much context AGENTS.md injects by nesting them within your repository. Rules for services/payments/ belong in a file there. Files closer to your working directory come later in the combined prompt, so they override earlier guidance.
• Always-needed in the file, sometimes-needed in a link. The guide says that if AGENTS.md gets too large, keep the main file concise and reference task-specific markdown files for planning, code review or architecture. The release checklist is read once a month, so link it and let Codex open it only when you ask about releases.
• Use skills for long how-tos. Skills use progressive disclosure: Codex starts with each skill's name and description and loads the full SKILL.md only when it decides to use the skill. So a ten-step procedure costs almost nothing on unrelated work. The docs also cap the initial skill list (by default at most 2% of the model's context window, or 8,000 characters when that is unknown), so keep descriptions short.
• Trim your tools. Every MCP server adds context to your messages and uses more of your limit. Disable the ones you are not using.
• Delete the obvious. If the code makes it clear, the line is a tax with no benefit.
• Watch for truncation. If instructions are cut off at the cap, the docs say to raise project_doc_max_bytes or split large files across nested directories. Splitting is the cheaper fix.

Empty files are skipped, so a placeholder AGENTS.md costs nothing, but it saves nothing either. An AGENTS.md that is mostly a pasted README is the expensive end of the curve.

7. Habits that save more

The file is one lever. These habits matter just as much. They come from the Pricing FAQ, the best-practices guide, the speed page and the slash command reference:

> /compact          summarise earlier turns, free context
> /status           check model, approvals, token usage
> /new payments     next task: fresh named chat
> /resume           come back to an older chat if needed

Model, reasoning effort and speed

Three dials trade quality, time and usage. All are set per chat or in config, and the details of the models are in Part 4.

• Model. In the CLI, /model switches models, or launch with --model (alias -m), for example codex --model gpt-6.1-sol. As of 18 October 2026 the Model selection page says Luna is the most cost-efficient model and Astra is the most powerful, and that if you do not need to think about usage or time you can default to Astra. To reduce cost or latency, choose a lighter model. It recommends GPT-6.1 Sol for complex coding and agentic work when available to your account, and Luna for focused, repeatable tasks. The picker only shows models available to your account and workspace.
• Reasoning effort. Higher effort can improve results for complex tasks, but the docs say it takes longer and uses more tokens. Start with the default effort and raise it when the task needs deeper planning. The best-practices guide suggests Low for faster, well-scoped tasks, Medium or High for complex changes or debugging, and Extra High for long, agentic, reasoning-heavy tasks. In config the key is model_reasoning_effort. Available levels depend on the model and your client.
• Speed. The Speed page says you can increase model speed in Codex in exchange for higher usage. /fast toggles Fast mode for supported models (if the model has no Fast tier, the command is not shown), and you can persist it with service_tier = "fast" plus [features].fast_mode = true in config.toml. Ultrafast exists for specific models on specific plans (Pro $500 and eligible Enterprise and Edu plans) and costs even more.

The cost of speed, from the Pricing page, relative to Standard mode for the same model:

Fast mode is faster, not cheaper. If you are not waiting on the result, Standard speed lets the allowance last longer. With an API key, the page says API token pricing applies and ChatGPT credit multipliers do not.

The page's own advice on experimenting is a good rule: compare results on the same inputs and keep the lightest setting that meets your quality bar. Ask yourself how often the workflow runs, how quickly you need the result, how the output will be used, and how much its quality matters.

8. Onboarding onto a new project

Joining a project is the same problem Codex has every morning: lots of unknowns, little context. The file helps both of you. There are two situations.

You are new to the project

If the project already has an AGENTS.md, reading it is the fastest tour you will get: commands, structure and traps in one page. If it does not, you can use Codex to build the tour, then correct it with a teammate. Start Codex from the project directory (the CLI treats the directory where you start it as the project, or pass --cd / -C).

/init creates an AGENTS.md scaffold in the directory where you run it; the docs say to review it and edit it to match your repository conventions. Then use a repeatable recipe. Note that it follows the four-part prompt (goal, context, constraints, done-when) from the best-practices guide:

Goal: I am new to this codebase. Give me a one-page tour I can keep.
Context: start from the README, the build files and the top-level folders.
Constraints: read only, do not change any files yet. Mark anything
you are unsure about instead of guessing.
Done when: you have told me
1. what the project does and the main modules
2. how to build, test and lint (exact commands)
3. how a request or user action flows through the code, file by file
4. which parts look risky or fragile, and why
5. what you would add to AGENTS.md for the next person

Then, in the same chat, ask follow-ups such as “What do I need to know before changing the engine code?” or “Trace what happens when a user sends a chat message.” If you want a plan before any change, switch to /plan first. When the tour looks right, ask Codex to write the useful parts into AGENTS.md (a concise version: commands, folder map, two or three gotchas), and review it with /diff.

To confirm what Codex actually loaded, the AGENTS.md guide suggests running codex --ask-for-approval never "Summarize the current instructions." from the repository root. It should echo guidance from the global and project files in order of precedence. Once instructions are in a file, a new teammate asks Codex the same questions you did; the file answers them before they ask.

You are bringing someone (or Codex) into your project

If you maintain the project, AGENTS.md doubles as onboarding documentation that is actually kept current, because you use it daily. A new hire reads the same file their assistant does, and both start with the same understanding. The best-practices guide adds a related tip: personal skills live in $HOME/.agents/skills, and shared team skills can be checked into .agents/skills inside a repository, which is especially helpful for onboarding new teammates.

9. Starting a new feature

Features have a different problem from projects: the knowledge is temporary. The decisions you make this week (names, trade-offs, what is out of scope) matter until it ships and then mostly do not. Putting all of that in the permanent root file would bloat it.

Instead, write a short feature note and point to it:

# Feature: automatic offline fallback

## Goal
If the user picked Online but the internet is not reachable,
answer from the on-device model and tell the user why.

## Decisions
- Check VALIDATED network capability, not just "connected".
- If the online call fails before any text arrives, fall back.
- If it fails part-way, keep the text already received.

## Out of scope
- Switching back to online mid-conversation.

## Done when
- Unit tests for the decision logic pass.
- Manual test: airplane mode shows the fallback message.

## Current work
Working on automatic offline fallback.
Read docs/features/offline-fallback.md before changing the engine selection code.

This also helps across chats. If you stop on Friday and start fresh on Monday, the new chat reads the feature note and picks up where you left off, without you retelling the story. For a long task, /goal (for example /goal Finish the migration and keep tests green) keeps an objective attached to the active chat. The docs say goal text is limited to 4,000 characters and that for longer instructions you should put the details in a file and point the goal at that file, which is exactly the feature-note pattern.

A worked example: the first week on a feature

Imagine you join an Android team and your first ticket is the offline fallback above. Here is how the pieces fit, with a rough token view of each step.

1. Day 1 morning, tour. In the project root, run codex and paste the onboarding recipe. Codex reads the README and build files and reports. You run /init and trim the draft to build commands, a folder map and two gotchas. A teammate corrects one wrong claim. You commit. Cost: one exploratory chat, paid once.
2. Day 1 afternoon, plan. /new offline-fallback to start clean, then /plan with the four-part prompt. You save the decisions as docs/features/offline-fallback.md and link it from AGENTS.md. The chat can now be thrown away; the plan is a file.
3. Day 1 evening, build. Use a lighter model or lower effort for the well-scoped edits, and /status to check usage. When the chat grows long, /compact. Before closing, run the handoff prompt.
4. Day 2, continue. New chat: “Read docs/notes/2026-10-18.md and continue.” No retelling and no old transcript. Use /side for a quick question about a library without touching the main context.
5. Day 5, ship. Review with /diff and /review. Remove the “Current work” link, and move the one lasting lesson (“check VALIDATED network capability”) into the permanent notes. Delete stale notes.

Notice what never happened: the same background was never typed twice, and no chat ran for days. That is where the savings in this part really come from.

10. Making it a team habit

1. Commit the root AGENTS.md so everybody shares the same baseline.
2. Review changes in pull requests like code. A bad line affects every future session.
3. Add a line when something goes wrong. A bug caused by a missing convention becomes a one-line prevention for the next person. The guide's retrospective tip fits here.
4. Prune on a schedule. Every month or so, delete lines that are no longer true or no longer needed.
5. Keep personal taste personal. Preferences go in your global file at ~/.codex/AGENTS.md, not the shared one. Use AGENTS.override.md there only for a temporary override.
6. Share the usage tips. Smaller models for routine work, fresh chats between tasks, fewer MCP servers. They help the whole workspace's allowance last longer.

11. Pitfalls and a checklist

The whole series so far in one picture

Links and official docs

Codex changes quickly. This series was checked against the official documentation on 18 October 2026; always confirm details on the official pages. These are the pages behind this part:

• Pricing: plans, usage estimates, credits, token rates, and the tips for making usage last longer.
• Speed: Fast and Ultrafast modes and their billing.
• Slash commands in Codex CLI: /status, /usage, /statusline, /compact, /new, /resume, /fork, /init and more.
• Custom instructions with AGENTS.md: discovery order, nesting and the size cap.
• Best practices: prompts, planning, AGENTS.md and long-running chats.
• Model selection and Models: choosing a model and reasoning effort.
• Projects and chats: one chat per outcome, resuming chats.
• Long-running work: /goal and steering a running task.

What comes next

You now know where tokens go, how to watch them, and how to keep your notes lean. In Part 4 we look at the Codex models in more detail, the API route and the official links. If you want to revisit what goes into the file itself, go back to Part 2.