How to actually use Codex like a senior developer, not a chatbot

Most people install an AI coding agent, type "fix this bug," get a patch, run it once, and call it done. Then three days later they find out the "fix" broke something else because nobody actually checked what changed. That's not Codex's fault — that's a workflow problem. Codex isn't a chatbot that spits out code snippets. It's an agent that can read your entire codebase, make edits, run your tests, and verify its own work — but only if you give it the structure to do that.

This guide walks through how to actually run Codex the way it's designed to be run: from your first real task, through debugging and planning, to reusable project instructions, parallel agents, and cloud workflows that keep working while you're doing something else.

What is Codex, exactly?

Codex is OpenAI's agentic coding tool. Unlike the old Codex API, this version is built for actual agentic work — you describe what you want in plain English, and Codex figures out which files to change, what commands to run, and how to verify the result. It ships as a terminal CLI, an IDE extension, a desktop app, and a cloud version that runs tasks in isolated containers.

The CLI is open source and a terminal-based coding agent that reads, modifies, and executes code directly on your machine, built in Rust. Your code doesn't get uploaded anywhere by default — your source code stays local unless you explicitly share it, only prompts and high-level context are sent to the model.

How do you install Codex and get it running?

The primary place to start is the Codex CLI GitHub repo and the official documentation at developers.openai.com/codex. Installation only takes a minute:

# Install using npm
npm install -g @openai/codex

# Or install using Homebrew
brew install --cask codex

Then simply run codex to get started. You can also grab a platform-specific binary from the GitHub releases page if you'd rather skip the package manager.

Before you install, check your environment. Node.js version 22 or later is required for the npm package, and macOS and Linux are fully supported, while Windows works through WSL.

Once installed, authenticate:

codex login

This opens a browser for interactive login, though a device code flow exists for headless environments, and you can also pipe in an API key directly. If you're on a paid ChatGPT plan, you're already covered — ChatGPT Plus, Pro, Business, Edu, and Enterprise plans all include Codex access.

Run codex in your project folder and you'll land in an interactive session. From there, a handful of slash commands matter immediately: /init creates an AGENTS.md file with instructions for Codex, /status shows current session configuration, /permissions lets you choose what Codex is allowed to do, /model lets you choose what model and reasoning effort to use, and /review runs a dedicated review against your changes.

What should your first real task actually look like?

The mistake most beginners make is giving Codex something vague like "improve this app" and walking away. A good first task is narrow enough to verify quickly but substantial enough that you're not just watching it type. Think: "add pagination to the /users endpoint and write a test that confirms page 2 returns the correct offset" — not "make the API better."

The key habit to build immediately: don't just accept "done." A finished-looking response from an agent isn't the same as a working, verified change. Ask Codex to show you what it ran, what passed, and what it actually checked — not just what it claims to have fixed.

Why does "done" not mean what you think it means?

This is the part almost everyone skips, and it's the part that saves you the most pain later. Without an explicit verification step, "done" just means the agent stopped typing — not that the change works, not that it didn't break something else, and not that the tests you assume exist actually ran.

Build a habit of asking Codex to run and show the actual test output, lint checks, or a manual reproduction of the bug before you trust that a task is finished. If there's no test covering the change, ask it to write one before it touches the code. This single habit does more to make Codex trustworthy than any prompt trick.

How do you get better debugging results from Codex?

When something's broken, resist the urge to jump straight to "fix it." A better sequence is: diagnosis first, fix second. Ask Codex to investigate and explain the root cause of a bug before authorizing any change to the code — and explicitly forbid edits during that first pass.

That constraint matters more than it sounds like it should. When you tell an agent it's not allowed to edit anything yet, it has to actually explain the mechanism behind the bug instead of pattern-matching a plausible-looking patch onto the symptom. You end up with a real explanation you can sanity-check, rather than a fix that happens to make the error message go away without addressing why it happened.

Once you've read and agree with the diagnosis, then authorize the change. This two-step rhythm — investigate, then fix — catches a surprising number of "solutions" that would have just moved the bug somewhere else.

Should you trust Codex's own review of its work?

No — and this matters even after tests pass. Passing checks doesn't mean the implementation is good. Codex has a built-in /review command that runs a dedicated review against uncommitted changes, a commit, or a base branch, and it's worth running after every meaningful task.

But treat that review output the way you'd treat a second opinion from a junior teammate: useful, worth reading closely, not the final word. An agent reviewing its own work (or another agent's work) can still miss subtle regressions — an edge case in a CSV export, a rounding error in a calculation, a change that passes the obvious test but breaks an assumption three files away. Run the review, read it critically, and still eyeball the actual diff yourself before shipping.

How do you set up reusable project instructions with AGENTS.md?

Retyping your project's conventions every session is a waste of time Codex is specifically built to eliminate. That's what AGENTS.md is for. AGENTS.md gives Codex reusable instructions for a local Codex user profile, repository, or subdirectory — think of it as a lightweight onboarding note that Codex reads before it starts work: project norms, preferred commands, review expectations, writing style, and things it should be careful about.

Run /init inside a project and Codex will draft one for you based on the codebase it finds. From there, OpenAI's guide to custom instructions explains how the file loading actually works: Codex reads AGENTS.md files before doing any work, and by layering global guidance with project-specific overrides, you can start each task with consistent expectations no matter which repository you open.

A few practical rules worth knowing:

• Keep it lean. Try to keep your AGENTS.md lean — Codex loads it into the session's instruction context, so unnecessary information can crowd out useful context, and Codex stops adding project guidance once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB.
• Use nested files for special cases. Use nested AGENTS.md files when one part of a project has special rules — for example, a slides/AGENTS.md file might remind Codex to update .pptx sources before exported PDFs, while a backend/AGENTS.md file might list API test commands.
• Don't treat it as a security boundary. AGENTS.md is a text file that goes into the model's context — it shapes behavior through instruction, not enforcement, so if you write "never modify vendor/," Codex is more likely to avoid that directory, but it's not locked out. For anything truly dangerous, use sandbox restrictions instead of instructions.
• Global defaults live in your home directory. Put durable working agreements — code style preferences, commit message format, testing philosophy — in ~/.codex/AGENTS.md so every project inherits them automatically.

How do sandbox settings and approval policies actually work?

This is the control system that decides how much freedom Codex has, and it's genuinely worth understanding rather than accepting the defaults blindly. Codex separates two concepts: what it's technically allowed to touch, and when it has to stop and ask you first.

Sandbox mode defines the technical boundary. The official security documentation lays out the three levels: sandbox_mode can be "read-only," "workspace-write," or "danger-full-access." In read-only mode, Codex reads files and answers questions but changes nothing — the right mode for reviewing a pull request or exploring a repository you just cloned. Workspace-write is the practical default for daily use: Codex edits files and runs commands inside the workspace without interruption, and stops and asks when it needs to write somewhere outside that boundary or when a command requires network access.

Approval policy decides when Codex has to pause and check with you, separate from what it's physically capable of doing. Approval policy controls when Codex must ask you before it executes an action — for example, leaving the sandbox, using the network, or running commands outside a trusted set. The three main values are untrusted, on-request, and never.

A sensible starting configuration, set either with flags or in ~/.codex/config.toml:

codex --sandbox workspace-write --ask-for-approval on-request

This lets Codex work freely inside your project while still checking in before it does anything riskier. By default, network access stays off too — by default, the agent runs with network access turned off — which is worth knowing if a task suddenly needs to hit an API or install a package.

Only reach for full access when the environment itself is the safety net. As one detailed breakdown of the settings puts it, use "never" approvals with "danger-full-access" sandboxing only when the surrounding machine or container is the real sandbox — a disposable Docker container, not your daily laptop.

How do you run parallel agents without them stepping on each other?

Once you trust Codex on a single task, the next level is running several at once — but this is where a lot of people get burned. The official guidance on subagents is blunt about where parallelism helps and where it doesn't: use parallel agents for read-heavy tasks such as exploration, tests, triage, and summarization, and be more careful with parallel write-heavy workflows, because agents editing code at once can create conflicts and increase coordination overhead.

In practice, that means fanning out multiple agents to explore a codebase, review different modules, or triage a list of bugs works great. Fanning out multiple agents to edit the same files at the same time is asking for merge conflicts.

For local parallel work, isolate each agent in its own Git worktree rather than running multiple write-capable sessions in the same checkout — running several write-capable Codex sessions in one working directory doesn't actually isolate anything from each other, it just means you're hoping they don't touch the same files.

What can Codex cloud do that the CLI can't?

The CLI and desktop app are great for hands-on sessions where you're watching and approving as you go. Codex cloud is built for the opposite: work that runs while you're doing something else entirely. Run tasks in isolated cloud environments, work in parallel, and start work from the web, GitHub, GitLab, Linear, or Slack — give longer tasks dedicated environments and let them continue while you work on something else.

Cloud tasks run in genuinely isolated infrastructure, not just a sandboxed folder on your own machine. Codex cloud runs in isolated OpenAI-managed containers, preventing access to your host system or unrelated data, and uses a two-phase runtime model where setup runs before the agent phase and can access the network to install dependencies, then the agent phase runs offline by default — secrets configured for cloud environments are available only during setup and are removed before the agent phase starts.

Getting started is a short setup: connect GitHub or GitLab, create an environment, and start your first cloud chat — configuring the dependencies, tools, variables, and setup steps each repository needs. When a task finishes, you don't just get a "done" message — you get something to actually evaluate: inspect the summary and diff, request a follow-up, or open a pull request when the result is ready.

This is the workflow worth building toward: kick off a longer refactor or a well-scoped bug fix from your phone or browser in the morning, and come back to a reviewable diff instead of a half-finished chat session.

What's the realistic way to put all of this together?

Don't try to adopt every piece at once. A workable progression looks like this:

1. Week one: Install the CLI, run it in workspace-write / on-request mode, and give it small, well-scoped tasks you can verify in a few minutes.
2. Week two: Start every debugging session with an investigation-only pass before authorizing fixes, and run /review on every change before you commit it.
3. Week three: Write an AGENTS.md for your main project so Codex stops needing the same context repeated every session.
4. Week four: Try parallel agents for read-heavy exploration tasks, and move your first genuinely async task — a dependency bump, a test-suite expansion — into Codex cloud.

Codex doesn't get more useful because you feed it bigger prompts. It gets more useful because you give it verification steps, boundaries, and memory — the same things you'd want from any developer joining your team for the first time.

The agents aren't going anywhere. The developers who figure out how to actually manage them — not just chat with them — are the ones who'll be shipping twice as fast by the time everyone else catches up.