The Codex CLI Guide OpenAI Never Wrote

Codex CLI is OpenAI's terminal coding agent: a Rust binary, Apache 2.0, that reads your repository, runs your build and proposes diffs from a plain-English prompt. It defaults to GPT-5.6 Sol, which leads Terminal-Bench 2.1 at 89.5% (July 2026). Install takes one command. The interesting parts are what happens after.

Updated August 10, 2026 · by the AITerm team

What is Codex CLI?

Codex CLI is a local terminal agent from OpenAI. You open a project folder, type codex, describe a task in English, and it reads files, runs commands, and proposes a patch you approve before anything lands on disk. It is written in Rust, ships as a single binary, and the source is Apache 2.0 on GitHub, where it sits at 105.1k stars and 15.9k forks.

The first release was April 2025. Adoption stayed modest until the desktop app arrived in February 2026, and then the curve went vertical: past 3 million weekly users in April, more than 5 million by 2 June, and after GPT-5.6 shipped on 9 July it went 6 million on the 12th, 7 million roughly a day later, and 8 million by that Sunday.

Look, those numbers are worth one caveat. Roughly one in five Codex users is not a developer, and knowledge-worker adoption is growing about three times faster than developer adoption. So "8 million users" is not 8 million engineers. It is still the fastest adoption curve any terminal agent has had.

Codex is not only the CLI. The same account drives a desktop app, an IDE extension for VS Code and JetBrains, a web surface for cloud tasks, GitHub code review and a Slack integration. The CLI is the surface with the least ceremony and the most control, which is why it is the one people argue about.

Installing Codex CLI in under two minutes

One command, then one sign-in. On macOS and Linux the official installer is a shell script from OpenAI's domain, and on Windows it is the PowerShell equivalent or WSL. Homebrew and npm both work and pull the same Rust binary, so pick whichever your machine already manages.

# macOS / Linux, the official installer
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# or, if you already live in one of these
brew install --cask codex
npm install -g @openai/codex

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

cd ~/code/my-project
codex                       # first run opens the browser sign-in

So, sign in with ChatGPT unless you have a reason not to. That path uses the allowance already included in your plan, with no per-token bill. The alternative is an API key, which bills every token through your OpenAI Platform account at standard API rates and is the right choice only for automation you want costed separately from a human seat.

You are probably expecting a longer install section. There isn't one, and that is the point: every competing guide on this keyword spends 800 words on a step that takes 90 seconds. Everything that decides whether Codex is useful to you happens after the binary is on disk.

Is Codex CLI free?

The tool is free, the usage is not. Codex CLI is open source and installs on any plan including ChatGPT Free at $0, but the free allowance is capped tightly and excludes every cloud feature: no cloud tasks, no GitHub code review, no Slack. Those start at Plus. Honest answer for daily use, budget $8 to $20 a month.

Here's the thing about the pricing page: two mechanics matter more than the sticker price. First, metering moved to token-based credits during 2026, so a chatty session with six MCP servers connected costs more than a terse one, even at the same message count. Second, limits run on a rolling 5-hour window with a weekly cap on top, and the weekly cap resets seven days after your first message of the week rather than on a calendar boundary.

On Plus, published estimates put GPT-5.6 Sol at roughly 15 to 90 local messages per five-hour window, Terra at 20 to 110 and Luna at 50 to 280. Wide ranges, because a message that reads forty files is not a message that renames a variable.

Your first ten minutes in a session

The TUI opens on an empty prompt and everything else is a slash command. Type / to see the list your installed version actually ships, because the set changes often enough that any printed cheat sheet is wrong within two months. The five that carry the weight are /model, /diff, /review, /compact and /new.

/model            # pick Sol, Terra or Luna, and the reasoning effort
/diff             # what has changed so far, before you trust anything
/review           # Codex reviews its own diff, syntax highlighted
/compact          # summarise the session on purpose, not by accident
/new              # fresh thread, AGENTS.md reloaded

codex resume      # come back to a saved conversation
codex exec "..."  # headless, for CI jobs and scripts

Here's the thing about /review. It is the single most underused command in the tool. The sequence that works is /diff to confirm scope, /review to collect findings, fix, then /diff again before committing. Codex catches its own sloppiness at a rate that surprised us, mostly because a review pass runs with fresh attention on a diff rather than on a plan.

One habit to build on day one: one thread per unit of work. Not per day, not per feature area. When the task changes, /new. It costs you a reload of AGENTS.md and saves you the slow degradation that comes from carrying forty turns of irrelevant history.

Sandbox modes and approvals are two separate dials

This is the part Codex gets more right than anyone, and the part almost nobody reads. Two independent settings decide how the agent behaves: sandbox mode controls what it can technically touch, approval policy controls when it has to ask you first. Confusing them is how people end up either interrupted every eight seconds or one prompt away from a bad afternoon.

You're probably thinking this is the section to skim. It is the one that decides whether you can ever leave the agent alone.

Approval policy is the other axis: untrusted asks about anything it did not originate, on-request asks when it judges a step risky, and never stops asking entirely. The combination people actually want for unattended work is workspace-write plus never, which is what --full-auto gives you. Full write access to the project, zero network reach, no interruptions.

# the sane unattended run: sandboxed, uninterrupted
codex --full-auto

# explicit version of the same thing
codex --sandbox workspace-write --ask-for-approval never

# read-only exploration of somebody else's repo
codex --sandbox read-only

# --yolo is NOT a faster --full-auto: it removes the sandbox too
codex --yolo

How big is the context window, really?

272,000 input tokens, and roughly 258,400 of those are usable. The GPT-5.6 model card advertises 1,050,000 tokens, which is the raw API ceiling, not what the CLI gives you. Codex CLI v0.144.6, released 18 July 2026, wrote the 272K cap into its bundled model metadata for Sol, Terra and Luna alike.

That cap arrived as a cut, not as a limit that had always been there. Before 13 July 2026 the effective window sat around 353,400 tokens. It dropped to 258,400 with no announcement, a 27% reduction, and the developers who noticed filed GitHub issue #32806 against openai/codex with the before and after numbers side by side.

We think the cap is defensible engineering and the silence around it was not. A million-token window that degrades badly past a third of its length is worse than a smaller window you can plan against. Quality falls off well before the hard ceiling, often around 30% of the limit, so a smaller honest number produces better sessions than a large aspirational one.

Auto-compaction fires around 200,000 accumulated tokens by default. Turns out the useful reflex is to never meet it. Compaction is summarisation, and a summary drops the detail that made the agent right about your codebase thirty turns earlier. In practice, /new beats /compact almost every time.

AGENTS.md decides most of your output quality

Codex reads AGENTS.md from the repository at session start, and that file does more for your results than any model choice. It has a 32 KiB cap, which nobody hits, and a much lower practical ceiling, which everybody does. Rules the agent ignores are worse than no rules, because they cost tokens on every single turn.

Our first version on the AITerm repo was long and detailed. It listed the directory structure, the dependency inventory, the architecture history. The agent could read all of that from the repo faster than we could keep it true, and within three weeks it described a build script we had renamed. A stale memory file does not fail loudly. It just quietly makes the agent confidently wrong.

# AGENTS.md

## Build and test
- Build: ./build.sh (Swift Package, signed app)
- Never run git push without an explicit ask

## Conventions that get broken
- Every visible string goes through L("key"), all 7 languages
- No em dash anywhere in the project, including comments
- One atomic commit per coherent change, message in French

## Codex specifics
- workspace-write is enough, this repo never needs network
- Run ./build.sh before proposing a diff, it takes 40 seconds

Honestly, the test for every line is simple: does it change what the agent does? If not, delete it. Ours is under 40 lines now and the difference in first-attempt quality was larger than switching from Terra to Sol.

If you also run Claude Code, resist the urge to maintain two full files. Keep one canonical file and have AGENTS.md point at CLAUDE.md, or the reverse. We wrote up that whole trap in our Codex vs Claude Code comparison, along with the routing rules we use to decide which agent gets which ticket.

config.toml, profiles and MCP servers

Everything persistent lives in ~/.codex/config.toml, or $CODEX_HOME/config.toml if you move it. Codex resolves configuration from project files root-down toward your working directory, and a profile selected with --profile or the CODEX_PROFILE environment variable sits on top. Explicit activation only, so no profile ever surprises you.

Turns out profiles are the feature worth ten minutes of setup. One profile for exploration in read-only, one for the unattended runs, one that connects the MCP servers you only need occasionally. The alternative is a config that grants your riskiest task's permissions to every task you run.

# ~/.codex/config.toml

model = "gpt-5.6-terra"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

[profiles.explore]
model = "gpt-5.6-luna"
sandbox_mode = "read-only"

[profiles.unattended]
model = "gpt-5.6-sol"
approval_policy = "never"
sandbox_mode = "workspace-write"

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

MCP servers can also be added straight from the terminal, which writes the same TOML for you.

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add internal --url https://mcp.example.com/sse
codex mcp list

codex --profile explore        # read-only, cheap model
codex --profile unattended     # full-auto shape, sandbox on

Should you use the CLI or the Codex app?

Ask one question: can this task be reproduced from the repository alone? If yes, send it to the cloud surface and get on with your day. If it needs your branch, your uncommitted work, your local database or the fixture you never pushed, it belongs in the CLI. Task length has nothing to do with it, which is where most advice on this goes wrong.

And yes, the CLI is not a stripped-down app. It is the surface with the tightest loop between a prompt and a diff, which is the whole reason terminal agents took over from chat windows.

Where does Codex CLI actually fall down?

Three places, all documented by users rather than by OpenAI. Long requests get cut off, quality degrades before the context limit, and tool output eats your window faster than your prompts do. None of these are dealbreakers. All of them will cost you an afternoon if nobody warns you.

The first is a timeout. Requests have been reported dying at roughly 150 seconds, which is exactly long enough to be fine on a normal task and fatal on a multi-file refactor that needs sustained reasoning. Users have been asking for a configurable limit for months. Until it lands, the mitigation is smaller tasks, which is better practice anyway.

The second is quieter and worse. Answers start degrading well before the hard ceiling, with reports of noticeable decline around 30% of the context limit. That maps to about 75,000 tokens on today's cap. If a session feels dumber than it did an hour ago, it probably is, and no amount of rephrasing fixes it. Open a new thread.

The third is just arithmetic. In one representative debugging session, tool results accounted for roughly 81% of total tokens consumed. Your prompts are rounding errors next to the files the agent reads. The lever that actually matters is controlling what it reads and when, which is another argument for a short AGENTS.md and a lean MCP list.

An analysis of more than a thousand Codex CLI issues landed on the same conclusion we did after six months of daily use: teams do not want more raw model power. They want predictable guardrails and sessions that survive a long day. Operational excellence beats raw IQ, and that is the gap the roadmap still has to close.

The setup we run here

Codex almost never runs alone on our machines. It runs next to Claude Code, next to a build, next to a log tail, and the honest bottleneck stopped being the models a long time ago. It became knowing which of five sessions is waiting for an answer.

The mechanical rules are short. One git worktree per agent, never two agents in the same tree. One thread per unit of work. Terra by default, Luna for mechanical passes, Sol only when the output is not mergeable. Read-only for anything exploratory. --full-auto for unattended runs, never --yolo outside a container.

The measurement part is where our own product enters, once. We built AITerm because our Electron-based terminal could not hold this shape: 20 panes streaming agent output put it at about 1.9 GB of RAM on an M2 Air, against roughly 140 MB for the native Swift build, with keystroke latency staying under 8 ms while output was heavy. The binary is 8 MB. Our anonymous daily ping puts the median user at about three simultaneous agent sessions, and the top decile well past that.

The feature that changed Codex specifically for us is smaller: the 5-hour quota gauge sits in the sidebar next to the live status of every session. When your limits run on a rolling window rather than a monthly counter, seeing the clock is what stops a refactor from dying at 70% done.

None of the rules above need our app. Worktrees, short memory files, one task per thread and profiles all work in any terminal, including the one you have open. What the app removes is the alt-tabbing to find out who is waiting, which stops being a small thing somewhere around the third session. If you want the terminal side of that argument with numbers, we made it in our terminal comparison.

The short version: install it, set a profile, write forty honest lines in AGENTS.md, and start a new thread more often than feels necessary. That's it.

Going further

Sources

1. openai/codex, GitHub: Rust implementation, Apache 2.0, install scripts, 105.1k stars and 15.9k forks as of August 2026.
2. Issue #32806, GPT-5.6 Sol context cut, openai/codex, July 2026: 353,400 effective tokens before 13 July, 258,400 after, against a published 1,050,000.
3. Codex pricing, OpenAI: plan tiers from Free to Pro, credits and top-ups.
4. Using Codex with your ChatGPT plan, OpenAI Help Center: ChatGPT sign-in versus API key, shared rate limits across CLI, IDE and web.
5. Model Context Protocol, OpenAI Codex docs: codex mcp add syntax and the [mcp_servers.NAME] TOML table.
6. Config basics, OpenAI Codex docs: ~/.codex/config.toml, sandbox modes, approval policies and profile resolution.
7. Codex cloud, OpenAI Codex docs: delegating reproducible tasks to a prepared remote environment.
8. OpenAI hits 8 million Codex users, The New Stack, July 2026: 6 million on 12 July, 7 million a day later, 8 million by the weekend after GPT-5.6 shipped on 9 July.
9. Codex hits 4M weekly developers, Digital Applied, April 2026: the growth curve from under 1 million in February.
10. ChatGPT Codex limits 2026, SimpleMetrics: per-model message estimates on Plus for Sol, Terra and Luna, 5-hour window plus weekly cap.
11. The context window gap, Codex Knowledge Base, July 2026: v0.144.6 metadata, the 95% effective multiplier, compaction threshold near 200,000 tokens, and the 32 KiB AGENTS.md cap.
12. Codex, most common issues and feature requests, dev.to, 2026: analysis of 1,000+ issues, the ~150 second request cutoff, degradation near 30% of the context limit, and tool results at roughly 81% of session tokens.