How to reduce Codex CLI token usage
· 5 minute read
Codex token usage is the number of input and output tokens the Codex CLI spends on a task. Most of it is input: instructions, conversation history, and the output of shell commands Codex runs to explore your code. You reduce it by keeping instructions short, starting fresh sessions, and giving Codex a map so it runs fewer searches. Graphify, an open-source CLI, can cut the share spent reading files by answering structure questions from a graph.
Where does Codex token usage come from?Link to Where does Codex token usage come from?
Codex token usage comes mostly from context, not answers. Each turn sends the system instructions, your AGENTS.md files, the conversation so far, and recent command output. When Codex explores with rg, cat, or ls, that output joins the context. On a large repository, exploration can cost more than the edit itself.
OpenAI's Codex documentation describes the CLI as an agent that reads files and runs commands in your terminal. Every one of those reads is input on a later turn.
How do you check Codex token usage?Link to How do you check Codex token usage?
Use the /status slash command in the Codex CLI to see the current session's configuration and token use. Check it at the end of a task and write the number down. For a fair comparison, start each task in a new session and compare the same task before and after a change.
Which habits reduce Codex token usage?Link to Which habits reduce Codex token usage?
Five habits do most of the work. Each targets a different part of the context.
| Habit | What it cuts |
|---|---|
| Start a new session per task | Old history from unrelated work |
| Use /compact in long sessions | Detailed history, kept as a summary |
| Keep AGENTS.md short | Instructions loaded every session |
| Name files and symbols in the prompt | Exploratory searches |
| Give Codex a code map | Repeated grep and file reads |
AGENTS.md is the instruction file Codex reads, described on the AGENTS.md site. Treat it like CLAUDE.md: commands, conventions, and rules. Do not paste architecture into it, because it loads on every session.
How does a code graph reduce Codex searches?Link to How does a code graph reduce Codex searches?
A code knowledge graph is a map of a repository's functions, classes, files, and the calls and imports between them. Graphify is an open-source CLI that builds one, parsing code locally with tree-sitter. Codex can read the map instead of searching raw files to learn the structure.
Install the skill for Codex, then build the graph:
uv tool install graphifyy
graphify install --platform codexCodex calls skills with a dollar sign, so you run $graphify . in Codex, not the slash form. The README also asks Codex users to set multi_agent = true under [features] in ~/.codex/config.toml, for parallel extraction.
How do you make Codex use the graph every time?Link to How do you make Codex use the graph every time?
Run graphify codex install once in the project. It writes a section to AGENTS.md telling Codex to read graphify-out/GRAPH_REPORT.md before answering architecture questions. It also installs a PreToolUse hook in .codex/hooks.json. The hook fires before Bash tool calls and reminds Codex that a graph exists.
For a specific question, Codex can run graphify query "what calls the payment handler?" and get a bounded answer. The --budget flag caps the output at a token count. graphify path "A" "B" returns the shortest chain between two names.
Keep the graph current with graphify hook install. It rebuilds the code graph after each commit, locally, with no model calls.
How do you know it worked?Link to How do you know it worked?
Measure. Pick five real tasks, run them in fresh sessions, and record tokens from /status. Build the graph and run them again with the same prompts and model. The first graph build has its own cost for any docs and images it extracts. Results vary by codebase, so test on yours. Our guide to measuring token spend per task covers the method.
Do reasoning tokens count toward Codex usage?Link to Do reasoning tokens count toward Codex usage?
Yes. Reasoning models produce internal reasoning tokens before they answer. OpenAI bills those as output tokens, even though you do not see them. A higher reasoning effort setting can use more of them on the same task. So usage depends on how hard the model thinks, not only on what it reads.
For routine edits, a lower reasoning effort can cut usage. Keep higher effort for hard design or debugging work.
FAQLink to FAQ
Why does Codex use $graphify instead of /graphify?Link to Why does Codex use $graphify instead of /graphify?
Codex calls skills with a $ prefix. Run $graphify . in Codex. Other assistants use the slash form.
Does Graphify send my code to OpenAI?Link to Does Graphify send my code to OpenAI?
Not for code. Code is parsed locally with tree-sitter. Docs, PDFs, and images go through your assistant's model for extraction.
Does /compact reduce cost?Link to Does /compact reduce cost?
It replaces detailed history with a summary, so later turns send less. Some detail is lost, so give it a short note about what to keep.
Will the hook stop Codex from running commands?Link to Will the hook stop Codex from running commands?
No. It adds a reminder that the graph exists. Codex can still search when the graph does not answer the question.
Does a graph help on a small repository?Link to Does a graph help on a small repository?
Less. If the whole project fits in context, a map adds structure but saves little.
Get startedLink to Get started
Graphify is open source on GitHub. Install it with uv: uv tool install graphifyy. The Codex integration page has setup details. For the Claude Code side, read what fills the Claude Code context window. Setup details are in the installation docs.