Want to know how to use Codex without reading a hundred pages of documentation? Start with the command line, give it explicit project rules, and keep its permissions tight until you trust the task. OpenAI’s coding agent can inspect files, propose changes, run commands, and automate repeatable work, but the quality of the result depends heavily on the context and boundaries you give it.
This complete guide covers installation, AGENTS.md, the terminal interface, sandbox controls, repeatable workflows, automation, review, and common failure modes. I based it on OpenAI’s official Codex documentation and changelog, checked in August 2026. I haven’t treated researched behavior as personal hands-on testing.
What Is OpenAI Codex?
Codex is OpenAI’s coding agent for working with software projects. In the terminal, it can read a repository, answer questions about the code, edit files, run tools, and carry a task through multiple steps. The important word is agent. You’re giving it a goal and an operating environment, not asking for a single code completion.
That makes Codex useful for repository-wide work such as tracing a bug, updating tests, explaining unfamiliar architecture, producing a migration plan, or handling a repetitive maintenance task. Learning how to use Codex well starts with controlling that scope. Careless prompts are risky because a vague request combined with broad filesystem access can turn a five-minute job into an afternoon of cleanup.
What You Need Before You Start
You need Node.js and npm for the CLI installation path documented by OpenAI. You also need a project you can safely inspect and modify, preferably one tracked by Git so every change is reviewable and reversible.
Before you give an agent write access, commit or stash unrelated work. Run the project’s existing test command yourself. That gives you a clean baseline and prevents Codex from getting blamed for a failure that was already there.
If the repository contains production credentials, customer exports, private keys, or other sensitive material, remove them from the working tree or use a restricted sandbox. An agent doesn’t need every file on your machine just because the terminal can see it.
How to Use Codex in the Terminal
OpenAI distributes versioned Codex CLI releases through npm. Install the CLI globally:
npm install -g @openai/codexRun codex with no subcommand to open the interactive terminal interface. According to the official CLI documentation, the interface accepts global flags and image attachments, and web search defaults to cached mode.
OpenAI’s Codex CLI interface. Source: OpenAI.
The first job should be small and easy to verify. When you’re learning how to use Codex, ask it to explain the repository, locate the test command, or identify where a specific feature lives. Don’t begin with “rewrite the whole application.” You want to verify that it understands the project before it starts moving walls.
A useful first prompt looks like this:
Inspect this repository and explain how authentication works.
Name the relevant files, the request flow, and the test coverage.
Do not edit anything yet.That prompt gives Codex a concrete question and a clear read-only boundary. Once the explanation matches the code, you can ask for a plan or a narrow implementation.
Set Up AGENTS.md Before Serious Work
OpenAI’s Codex best-practices guide recommends AGENTS.md as the durable place to explain how the agent should work inside a repository. The /init command scaffolds a starter file.
Treat AGENTS.md like an operating manual, not a biography. Document the build command, test command, formatter, important directories, architectural constraints, and any files the agent must leave alone.
A practical version might contain:
# Project instructions
- Run `pytest -q` after Python changes.
- Run `npm test` after frontend changes.
- Keep API responses backward compatible.
- Never edit generated migration files by hand.
- Do not modify `.env`, credentials, or production data.
- Summarize changed files and test output before finishing.Keep the file current. If Codex repeatedly makes the same mistake, don’t keep correcting it in chat forever. Add the rule to AGENTS.md and turn the correction into durable project context.
A Reliable Codex Workflow
The safest way to learn how to use Codex is to split work into inspection, planning, execution, and verification. This is also how to use Codex without losing control of a large repository. Giving the agent every decision at once makes it harder to catch a wrong assumption early.
1. Ask for inspection first
Have Codex read the relevant files and explain the current behavior. Require file paths and concrete references. If its description is wrong, stop there. Fixing context is cheaper than repairing code written from a false premise.
2. Request a bounded plan
Ask for the smallest change that satisfies the goal. The plan should name files, tests, assumptions, and anything it won’t touch. A plan that says “update the backend” is useless. A plan that names three files and two acceptance checks is actionable.
3. Let it implement one coherent slice
Give Codex enough authority to finish the slice, but keep the scope narrow. A bug fix plus its regression test is one coherent slice. A bug fix, dependency migration, design refresh, and deployment rewrite are four separate jobs pretending to be one.
4. Review the diff and test output
A green test suite is evidence, not absolution. Inspect the changed files. Check for removed validation, hard-coded values, weakened tests, accidental API changes, and comments that promise behavior the code doesn’t provide.
5. Commit only after the result makes sense
Codex can help write a commit message, but you still own the repository. Keep commits narrow enough to revert. If the agent touched unrelated files, separate or discard those changes before committing.
Understand Approval Mode and Sandbox Mode
OpenAI describes approval mode and sandbox mode as the two major controls for how Codex operates. Approval mode determines when it asks before running a command. Sandbox mode determines which files and directories it can access.
Use restrictive settings while you’re learning how to use Codex on a new project. Broader access makes sense in a disposable worktree or isolated environment where the task genuinely needs it. It makes far less sense in your home directory with credentials and unrelated repositories nearby.
The physical rule is simple: match authority to the task. A documentation edit doesn’t need network access and unrestricted shell commands. A dependency upgrade may need package-manager access, but it still doesn’t need your password vault.
Configure Defaults Without Repeating Yourself
The CLI reads most defaults from ~/.codex/config.toml, while command-line -c key=value overrides take precedence for one invocation. Use the config file for stable preferences and the command line for experiments.
Keep global defaults conservative. Project-specific behavior belongs in repository instructions. That separation prevents one project’s unusual setup from leaking into every other Codex session.
If you maintain several repositories, standardize the basics: predictable test commands, clear contributor documentation, and explicit generated-file rules. Agents perform better when the project itself is legible.
Slash Commands Worth Learning
The official slash-command reference documents commands including /init, /mcp, /model, /plan, /review, and /status.
/init creates the project instruction file. /plan helps separate reasoning from implementation. /review is useful after a change lands. /status shows where the session stands. /model lets you change the model when a task needs a different balance of speed and depth.
You can queue slash commands with Tab while a chat is running. That sounds minor, but it keeps long sessions moving without forcing you to wait for the current response before preparing the next action.
How to Use Codex for Automation and CI
Interactive sessions are useful for exploratory work. Repeatable jobs belong in codex exec, also available as the shorter codex e. OpenAI documents this as the non-interactive path for scripts and CI, including newline-delimited JSON event output and a resume command for interrupted work.
Automation needs stricter contracts than chat. Anyone learning how to use Codex for unattended work should define the allowed directory, maximum runtime, expected artifact, and exact verification command. Make failure visible. A script that exits successfully after producing nothing is worse than a loud failure because it creates fake confidence.
A good automated task should answer four questions:
- What input triggered the run?
- What files may change?
- What command proves success?
- What happens when verification fails?
Store a receipt with the result. Include the input identity, changed-file list, test command, exit status, and any generated artifact path. That gives you something better than “the agent said it worked.”
The Codex App Server process flow behind Codex clients. Source: OpenAI.
Codex in the ChatGPT Desktop App
OpenAI’s Codex changelog says Codex joined the ChatGPT desktop app on macOS and Windows in July 2026. Existing users can update normally and keep their projects, settings, and workflows.
The desktop app is a friendlier entry point if you don’t live in a terminal. The CLI remains the better fit for repeatable commands, repository-local instructions, and CI-style automation because those workflows are easier to inspect and script.
Common Codex Problems and Fixes
Codex misunderstands the repository
Stop implementation and ask it to explain the relevant files again. Improve AGENTS.md, narrow the working directory, and include the acceptance condition. More autonomy won’t repair missing context.
It changes too much
Reduce the task to one behavior and name excluded files or subsystems. Ask for a plan before edits. Review the diff after each coherent slice instead of waiting for a giant final patch.
Commands keep asking for approval
Check approval mode instead of reflexively disabling safeguards. If the same safe command appears repeatedly, encode an appropriate project rule or use a controlled environment. Don’t solve friction by granting unrestricted access to everything.
Tests pass but the change is wrong
Tests only cover what they assert. Review behavior, interfaces, error handling, and the diff itself. Add a regression test that fails for the original bug and would fail again if the fix disappears.
The session loses direction
Restate the goal, current state, and remaining acceptance checks. For long work, ask Codex to write a checkpoint before continuing. If the task has grown into several unrelated jobs, split it.
Where Codex Fits in the AI Coding Stack
Codex isn’t the only coding agent, and it shouldn’t be your only evaluation point. My best AI coding agents comparison puts Codex next to Claude Code, Cursor, and Hermes with the tradeoffs spelled out.
Once you’re past setup, my Codex use-case hub collects more than 60 workflow ideas. Use those as starting points, then adapt them to your repository’s tests and authority boundaries.
Frequently Asked Questions
Can Codex edit an entire repository?
Yes, when its working directory and sandbox allow it. Broad access doesn’t guarantee a good result. Start with inspection and a bounded task, then review every changed file.
Does Codex need AGENTS.md?
The CLI can run without it, but AGENTS.md gives the agent durable repository-specific instructions. It reduces repeated corrections and makes automated runs more predictable.
Can I use Codex in CI?
Yes. OpenAI documents codex exec for non-interactive execution. CI jobs should use narrow permissions, explicit timeouts, deterministic verification, and machine-readable receipts.
Is Codex safe to run with full access?
Full access expands the blast radius of a mistake. Use it only in an isolated environment where the task needs it. For normal repository work, restrict files and commands to the smallest useful scope.
How long does it take to learn how to use Codex?
You can learn the interface in an afternoon. Reliable use takes longer because the hard part is task design: clear context, bounded authority, good tests, and disciplined review.
The Setup That Actually Sticks
Learning how to use Codex is mostly learning how to give an agent a clean job. Put stable rules in AGENTS.md. Inspect before editing. Match sandbox authority to the task. Require tests and inspect the diff.
Codex moves quickly, and OpenAI ships frequent changes. Check the changelog, keep your project instructions current, and make every automated run leave evidence. Speed is useful. Reviewable speed is what you can trust.
