Know Your Codex — The Complete Guide
A developer's guide to understanding OpenAI, ChatGPT, Codex, the Codex CLI, slash commands, approval modes, AGENTS.md, installation, and how to get better results from the AI coding agent working in your terminal.
1. OpenAI — The Name & A Brief History
Why "OpenAI"?
The name OpenAI originally signaled an ambition to make advanced AI research broadly beneficial, widely shared, and aligned with the public good. The word "Open" reflected openness in research and access, while "AI" was the direct statement of the field: artificial intelligence.
Over time, the company evolved in structure, products, and deployment strategy, but the mission has remained centered on building AI that benefits humanity.
Timeline
- December 11, 2015: OpenAI was introduced as a nonprofit AI research company with the goal of advancing digital intelligence in a way that benefits humanity.
- 2019: OpenAI created a capped-profit structure to raise the capital needed for large-scale AI research and deployment.
- November 30, 2022: ChatGPT launched publicly and became the product that put conversational AI into mainstream daily use.
- 2021 to 2024: The original Codex model helped establish OpenAI's push into coding assistance, while ChatGPT kept expanding from chat into a broader work platform.
- May 16, 2025: OpenAI introduced the new Codex coding agent experience for software engineering tasks.
- September 15, 2025: OpenAI announced upgrades to Codex, including stronger real-time collaboration, IDE support, and cloud task workflows.
OpenAI's story is really two stories at once: a research lab building frontier models, and a product company turning those models into tools people actually use every day.
2. ChatGPT — Why It Changed Everything
Before ChatGPT, many people saw large language models as something for demos, benchmarks, or developer APIs. ChatGPT changed that by making AI feel conversational, practical, and immediate.
You could ask a question, iterate, refine, paste code, request a rewrite, compare options, and keep going in one threaded conversation. That interaction model turned AI from a one-shot tool into a working partner.
What ChatGPT Made Normal
- Asking follow-up questions instead of rewriting the prompt from scratch
- Uploading text or code and iterating on it in context
- Using one model for writing, research, coding, analysis, and planning
- Treating AI as an everyday assistant instead of a rare specialist tool
Codex inherits the conversational and iterative workflow people learned from ChatGPT, but applies it directly to software projects, files, shells, tests, and code review.
3. What Is Codex?
Codex is OpenAI's coding agent for software engineering work. In practice, that means it can read your repository, inspect files, run terminal commands, edit code, execute tests, explain changes, and help you move from "idea" to "working implementation" much faster.
Codex Then vs Codex Now
The name "Codex" has two important phases:
- Original Codex (2021): a code-specialized OpenAI model that powered early developer workflows and helped popularize AI code completion.
- Modern Codex (2025+): a full coding agent experience available through the CLI, IDE integrations, and cloud task workflows.
So when people say "Codex" today, they usually mean more than just a model. They mean a working coding system.
What Codex Can Do
- Explore a codebase and explain how it works
- Implement features from a prompt or specification
- Fix bugs and regressions
- Run tests, linters, and local tooling
- Review pull requests and suggest improvements
- Help with refactors, documentation, and migration work
4. Why the Name "Codex" Fits
A codex was the historical ancestor of the modern book: bound pages that made knowledge easier to organize, reference, and navigate.
That name fits unusually well for an AI coding tool.
Why?
- A codebase is a kind of living book
- Source files are pages of system knowledge
- Good engineering depends on navigating, understanding, and revising that knowledge safely
In short: Codex is a tool for reading and rewriting the "book" of your software.
5. Installing Codex
Codex is available as a CLI and can also be used through supported editor integrations and ChatGPT plans.
macOS
If you use Homebrew:
brew install --cask codex
codex --version
codex --login
If you prefer npm:
npm install -g @openai/codex
codex --version
codex --login
Linux
npm install -g @openai/codex
codex --version
codex --login
Make sure node and npm are already installed. A modern Node.js setup is the safest path before installing the CLI globally.
Windows
The most reliable setup is to run Codex through WSL rather than plain Command Prompt, especially for repo tooling, Unix-style commands, and smoother local development workflows.
wsl --install
Then inside your WSL terminal:
npm install -g @openai/codex
codex --version
codex --login
First Login
codex --login
This connects the CLI to your OpenAI account. Depending on your setup, Codex can be used through supported ChatGPT plans or through API-based workflows.
6. Codex Highlights
Codex is useful because it is not limited to generating code snippets. It can operate on a real project with real files, real commands, and real constraints.
Core Strengths
- Repo-aware: it works against the code you actually have, not an imaginary greenfield project
- Terminal-native: it can inspect, run, and verify work in the same environment you use
- Iterative: you can refine a task over multiple prompts instead of starting over each time
- Agentic: it can carry a task through analysis, edits, and validation
- Review-friendly: it can explain why a change was made, not just produce one
Typical Use Cases
| Task | Where Codex Helps Most |
|---|---|
| Bug fixing | Reproducing, tracing, patching, verifying |
| Feature work | Turning specs into implementation |
| Refactoring | Preserving behavior while improving structure |
| Onboarding | Explaining architecture and file responsibilities |
| Reviews | Finding regressions, risky assumptions, and missing tests |
7. Running Codex in the Terminal
The terminal is where Codex feels most natural because software work already happens there.
Common Patterns
codex
Launch an interactive coding session inside the current project.
codex "explain the auth flow in this repo"
Use a direct prompt to start from a concrete task.
codex "fix failing tests in the payments module"
Start with an outcome, not implementation details. Let Codex inspect the code first.
What the CLI Workflow Feels Like
- You describe the task
- Codex reads the repo and gathers context
- It proposes or performs edits
- It runs checks where possible
- It reports what changed and what still needs attention
That loop is what makes Codex feel closer to an engineering assistant than a chat bot.
8. Slash Commands — The Fast Way to Drive Codex
Slash commands are the keyboard-first control layer for Codex CLI. Instead of restarting the CLI or rewriting your prompt, you can change models, reset context, inspect status, review diffs, or switch behavior directly inside the session.
The Most Useful Slash Commands
| Command | What It Does | When to Use It |
|---|---|---|
/model | Change the active model and, when supported, reasoning effort | Switch between faster and deeper thinking mid-session |
/new | Start a fresh conversation in the same CLI session | Change tasks without leaving the terminal |
/clear | Clear the terminal and start a fresh chat | Reset both the screen and conversation |
/status | Show session configuration and token usage | Check model, approvals, writable roots, and context usage |
/diff | Show the Git diff, including untracked files | Review edits before committing |
/compact | Summarize the conversation to save context | Keep long sessions from bloating the context window |
/review | Ask Codex to review the working tree | Get a second-pass check for regressions and missing tests |
/permissions | Change approval behavior mid-session | Move between stricter and faster execution modes |
/plan | Switch into planning mode | Get a plan before letting Codex edit anything |
/init | Generate an AGENTS.md scaffold | Bootstrap project-specific instructions |
/mention | Attach a file or path to the conversation | Point Codex directly at the code you care about |
/resume | Reopen a previous saved conversation | Continue earlier work without losing context |
/fork | Branch the current conversation into a new thread | Explore an alternative approach safely |
/mcp | Show configured MCP tools | Check which external tools are available |
/copy | Copy the latest completed output | Reuse a plan, explanation, or review quickly |
/ps | Show background terminals and recent output | Inspect long-running processes from inside the CLI |
A Few Practical Examples
/model
Use /model when the task changes shape.
- Start with a faster model for repo exploration or simple edits
- Switch to a stronger coding model for architecture, large refactors, or tricky debugging
- Use
/statusright after if you want to verify the active model and session settings
/new
/new is the clean way to switch tasks without quitting Codex.
Example flow:
/new
Now help me review the caching changes in the API layer.
This is useful when the current chat is about one problem and you do not want stale context leaking into the next one.
/diff and /review
These are the commands that make Codex safer in real repos.
/difflets you inspect exactly what changed/reviewasks Codex to evaluate the working tree like a reviewer, not like the original implementer
That combination is one of the easiest ways to catch subtle regressions before you commit.
9. How to Check Usage Stats in the CLI
People often ask how to see "usage statistics" in Codex. In the CLI, the most useful answer is /status.
What /status Shows
- active model
- approval policy
- writable roots
- current token usage
- remaining context capacity
That gives you a session-level view of how the current conversation is configured and how much room you have left before the context gets crowded.
Related Commands for Session Hygiene
/compact: summarize the conversation so you keep the important context while freeing space/statusline: customize the footer so model, context stats, limits, git info, token counters, session ID, and other indicators stay visible/ps: inspect background terminals if a long-running command is still working
Important Distinction
/status is about the current Codex session, not your account billing dashboard.
If you are using Codex through a ChatGPT plan, your overall usage limits depend on the plan. When you hit those limits, Codex access pauses until the window resets. For local CLI work, /status helps you manage the session you are in right now, not your full subscription consumption.
10. Approval Modes — Why They Matter
When Codex works locally, permissions matter. A serious coding agent should not blindly modify files or execute commands without clear boundaries.
Typical Modes
- Normal / Ask-first: Codex asks before important actions
- Auto-accept: Codex proceeds faster when you trust the scope
- Read-only / Planning workflows: useful when you want analysis before edits
Practical Rule
- Use ask-first mode for unfamiliar repos, production-adjacent work, and risky migrations
- Use auto-accept mode for scoped tasks in repos you know well
- Use planning mode when the task is large, ambiguous, or architectural
The right approval mode is not about convenience. It is about matching trust to risk.
11. AGENTS.md — The Secret to Better Results
If there is one habit that improves Codex output the most, it is giving the agent local project instructions.
AGENTS.md tells Codex how your team works: commands, conventions, constraints, expectations, and "don't do this" rules.
What to Put in AGENTS.md
# Project Rules
## Commands
- `npm run dev`
- `npm test`
- `npm run lint`
## Conventions
- Use TypeScript everywhere
- Prefer named exports
- Keep components under 200 lines where possible
- Add tests for behavior changes
## Guardrails
- Do not modify generated files
- Do not change database schema without a migration
- Ask before introducing new dependencies
Why This Helps
- Codex stops guessing your standards
- It picks better commands on the first try
- It avoids obvious team-specific mistakes
- Outputs become more consistent across sessions
Think of AGENTS.md as the difference between hiring a contractor with no briefing and hiring one with a proper project handbook.
12. How to Use Codex Better
Good results usually come from good task framing, not magical prompting.
Best Practices
- Start with the goal, not the implementation: say "fix the login redirect bug" before saying "change line 42"
- Give constraints early: framework version, coding standards, test command, no-new-dependencies rules
- Ask for a plan on large tasks: especially for migrations, refactors, or cross-cutting changes
- Point to files when you already know the area: this reduces search time and ambiguity
- Have it verify changes: ask it to run or describe the relevant tests, linters, or checks
- Keep tasks scoped: one crisp task beats five loosely related ones in the same prompt
- Use slash commands deliberately:
/model,/new,/status, and/compactare workflow tools, not just convenience features
Better Prompt Examples
Instead of:
fix this
Use:
Investigate why password reset emails are not being sent in production.
Check the mailer service, env usage, and recent auth changes. Fix the bug,
update tests if needed, and summarize the root cause.
Instead of:
refactor dashboard
Use:
Refactor the dashboard page to reduce duplication across the three summary cards.
Keep behavior identical, do not change styling, and run the relevant tests after editing.
The Core Pattern
Goal + context + constraints + verificationThat formula produces consistently better results than vague "please improve this" prompts.
13. Where Codex Fits Best
Codex is strongest when the work has concrete artifacts:
- source code
- tests
- logs
- config
- docs
- command output
It is especially good at:
- turning tickets into implementation steps
- making careful, incremental edits in existing repos
- catching missing edge cases during code review
- accelerating boring but necessary engineering work
It is less impressive when the request is vague, context-free, or based on hidden assumptions that are never stated.
14. Codex, ChatGPT, and the Bigger Picture
ChatGPT made AI conversation mainstream. Codex applies that same interaction model to engineering work.
If ChatGPT is the general-purpose conversational layer, Codex is the software-delivery layer. It takes the flexibility of chat and adds files, terminals, verification, and action.
That is why Codex matters: not because it writes code in isolation, but because it works inside the real shape of software development.
15. Final Take
Codex is most useful when you treat it like a fast, careful engineering collaborator:
- give it repo context
- give it rules
- give it verification steps
- keep tasks well scoped
- use slash commands to manage session state instead of fighting the interface
Do that, and it becomes much more than autocomplete. It becomes a practical coding agent that can help you understand systems faster, ship changes with less friction, and spend more of your time on the hard parts that actually need human judgment.