Terminal Coding Agent
Codex CLI: Install, First Task, AGENTS.md, and Approval Modes
Codex CLI is OpenAI's own product. This guide is independent and not affiliated with or endorsed by OpenAI.
Codex CLI is OpenAI's terminal-based coding agent: a program you run from a command line that reads your project, writes and edits code, and runs commands on your behalf, all inside a conversation you steer in plain language. It sits in the same general category as Claude Code: both are agentic coding tools that live in a terminal instead of a browser tab or an IDE sidebar. This guide walks through installing Codex CLI, running your first task, what an AGENTS.md file is for, and the approval and sandbox settings that decide how much it can do without stopping to ask you first. It closes with a plain, non-marketing comparison to Claude Code, since the two tools solve the same basic problem with different defaults.
Codex CLI is OpenAI's command-line coding agent. You install it with a one-line installer script, a package manager command, or a downloaded binary, then run it from inside a project folder and sign in with a ChatGPT account or an API key. Your first task is just a plain-language instruction typed at the prompt. An AGENTS.md file in your project gives Codex standing instructions it reads automatically before working. A sandbox setting controls what it's technically allowed to touch (read-only, read and edit the workspace, or unrestricted), while a separate approval setting controls when it pauses to ask you before acting, and the two can be tuned independently.
Published
Free lesson · no account neededMeet ClaudeWhy Claude?6 minStart the free lessonKey Takeaways
- Codex CLI installs with a one-line shell script, a package manager command, or a downloaded binary, and needs either a ChatGPT sign-in or an API key to run.
- Your first task is typed in plain language once Codex CLI is running; there is no special command syntax required to ask it to do something.
- AGENTS.md is a plain Markdown file Codex reads automatically, with a global copy and a per-project copy that can override it, before it starts working on a task.
- Sandbox mode controls what Codex is technically capable of touching; approval policy controls when it pauses to ask a human first. These are two separate settings, not one.
- A full-bypass flag exists that skips both the sandbox and approval prompts entirely, and should be treated as a deliberate, higher-risk choice rather than a default.
- Model names and default settings in this space change quickly; treat anything version-specific here as a snapshot and check the current official docs before relying on it.
Copy and Paste
Prompts You Can Use Today
A reasonable first task to hand Codex CLI
Look at the structure of this project: what language and framework it's built with, how the folders are organized, and whether there's a test suite. Then give me a short summary of what the codebase does and point out anything that looks unusual or inconsistent about how it's organized, without changing any files yet.
A read-first task like this is a good first run: it shows you how Codex explores a codebase before you ever let it edit anything.
Ask Codex to draft your project's AGENTS.md
Read through this repository and draft an AGENTS.md file for it: the commands to run tests and the linter, any formatting conventions you can detect from the existing code, directories that should not be touched automatically, and anything else a new contributor would need to be told before making a change here. Show me the draft before writing the file.
Asking it to draft the file rather than writing it unprompted keeps you in control of what instructions you're actually committing to the project.
Check your current approval and sandbox settings before trusting a session
Before we start, tell me plainly what sandbox mode and approval policy this session is currently running under, what that combination technically allows you to do without asking me first, and what it would still stop and ask permission for. I want to understand the boundary before I hand you a real task.
Running this once at the start of a session is a quick sanity check, especially on a machine or repository you don't fully trust yet.
What It Is
Codex CLI, in Plain Terms
Codex CLI is a coding agent from OpenAI that runs locally on your own computer from a terminal, according to its official GitHub repository. You type an instruction, and it reads your project, proposes or makes changes, and can run commands like a test suite or a linter, reporting back what it found and did.
It's one piece of a wider Codex product family rather than a single app: there's the terminal CLI covered in this guide, an IDE extension for editors like VS Code, a desktop app, and a separate browser-based, cloud-hosted version of the agent that runs tasks without using your own machine at all. They share some underlying technology but are genuinely different surfaces, and mixing them up is a common source of confusion when reading unofficial write-ups.
Access to Codex CLI is tied to an OpenAI account rather than sold completely separately. You can sign in with a ChatGPT Plus, Pro, Business, Edu, or Enterprise account to use it, or connect an API key instead if you'd rather pay per use and skip a consumer plan. Both the CLI and the IDE extension read from the same underlying configuration file on your machine, so a setting you change in one place carries over to the other.
Getting Set Up
Installing Codex CLI
OpenAI documents a few different ways in, depending on your platform and whether you'd rather not touch a package manager.
One-line installer (macOS/Linux)
A single curl command piped to a shell installs the latest release, pulling from OpenAI's own release server by default with GitHub Releases as a documented fallback.
One-line installer (Windows)
A PowerShell one-liner with an execution-policy bypass covers Windows directly; running Codex under WSL2 on Windows 11 is also documented and uses the Linux install path instead.
Package managers
An npm global install or a Homebrew cask are both documented alternatives to the installer script, for anyone who'd rather manage the tool the way they manage everything else on their machine.
Before you install
OpenAI's install documentation lists macOS 12 or newer, Ubuntu 20.04+ or Debian 10+ on Linux, or Windows 11 through WSL2, plus a recent Git install and a few gigabytes of free RAM, as the baseline you should already have in place.
Getting Started
Running Your First Task
Once it's installed, you run the `codex` command from inside the project folder you want to work in, and the first thing it asks for is how you'd like to sign in: with your ChatGPT account, or with an API key if you've set one up for a more pay-as-you-go setup. OpenAI's own quickstart frames the very next step as simply describing what you want in plain language, and even suggests a deliberately low-stakes example to try first: asking it to explain what the current project is and does.
The terminal interface that opens shows which model is currently active, a reminder of how to change it, and your working directory, along with a short list of built-in slash commands worth knowing from day one: one to generate a starting AGENTS.md file for the project, one to check your current status, one to review your permission settings, one to switch models, and one to request a code review of the current changes.
OpenAI's own guidance is to make a git checkpoint, meaning committing or at least noting the current state of your work, both before you hand Codex a non-trivial task and after it finishes, so that anything it changes can be cleanly reviewed or reverted. For anyone who wants to run Codex without the interactive terminal at all, there's also a non-interactive mode meant for scripts and automated pipelines, where you pass the whole task as a single command-line argument instead of typing into a live session.
Project Instructions
AGENTS.md: How Codex Reads Your Standing Instructions
Before Codex does any work on a task, it builds an instruction chain by reading AGENTS.md files, according to OpenAI's own developer documentation. There's a global copy you can keep in Codex's home configuration folder on your own machine, which applies no matter which project you're working in, and then a project-level search that walks down from the root of your repository toward your current folder, picking up an AGENTS.md at each level along the way.
When more than one file applies, they're combined from the top of the project down to wherever you're currently working, with instructions closer to your current folder taking precedence over the more general ones above them. There's also a documented size ceiling on how much combined instruction text Codex will read, so an AGENTS.md file is meant to be a working set of project conventions, not an unlimited dumping ground.
In practice, what goes into the file is ordinary Markdown: the command to run the test suite, a formatting or linting convention the project follows, a note about which package manager to use, or a warning about a folder that should never be touched without asking first. OpenAI's own documentation points to a separate, shared specification site for the AGENTS.md convention itself, and several other coding tools have been reported to read a file with the same name and a similar intent, though that cross-tool compatibility claim comes from third-party coverage rather than from OpenAI directly, so it's worth confirming against whatever other tool you're pairing it with rather than assuming identical behavior.
Safety and Control
Approval and Sandbox Modes
Codex splits safety into two independent dials, per OpenAI's own documentation: a technical boundary on what it can touch, and a separate policy on when it has to stop and ask.
Read-only sandbox
Codex can inspect your project and reason about it, but can't edit files or run commands without your explicit approval first. The safest starting point for a codebase you don't fully trust yet.
Workspace-write sandbox (the default)
Codex can read and edit files inside your project and run ordinary local commands on its own, but network access stays off by default inside this mode unless you separately turn it on.
Danger-full-access sandbox
No filesystem or network restriction at all. OpenAI's own naming for this mode is a deliberate signal about how much trust it requires before you turn it on.
Approval policy, on top of the sandbox
A default policy only interrupts you when Codex wants to go beyond whatever its current sandbox already allows; a separate policy removes approval prompts entirely and should be chosen deliberately, not by default.
Full bypass, if you really mean it
A documented flag turns off both the sandbox boundary and the approval prompts at once. OpenAI's own naming pattern for it is a plain warning in itself: treat it as an exception for a specific, trusted situation, not a convenience setting.
A Neutral Comparison
Codex CLI vs. Claude Code
Codex CLI and Claude Code are both terminal-native coding agents from different companies, built around the same basic idea: describe a task in plain language, let the agent read and change your code, and stay in the loop on anything risky. Neither tool is covered here as better than the other; the honest comparison is in how each one is put together, since the differences are more about philosophy than quality.
Codex CLI's safety model splits into the two separate dials covered above: a sandbox setting that's a hard, OS-enforced technical boundary (using Apple's Seatbelt sandboxing on macOS and a Linux sandboxing technology called bubblewrap on Linux, by OpenAI's own account), and a separate approval policy that's more of an interaction layer deciding when to interrupt you. Claude Code's permission model works differently: it centers on a settings file where you explicitly allow or deny specific tools and commands, plus a hooks system that lets you run your own scripts at specific points in a session, such as before a tool runs or after a file is edited, to enforce whatever rules you want in code rather than through a sandbox boundary alone.
Both tools read a standing instructions file from the project: AGENTS.md for Codex, a similarly-purposed project file for Claude Code. Both support a non-interactive mode for running tasks from a script instead of a live terminal session. Where they diverge most is in how literally they separate 'what's technically possible' from 'what needs a human's okay': Codex CLI treats those as two different settings you tune independently, while Claude Code leans more on an explicit allow-and-deny rule list plus hooks you write yourself. Neither approach is inherently safer; they're different defaults for the same underlying problem; agentic coding tools that can run real commands on a real machine need some way to bound what happens automatically versus what waits for a person.
A Fast-Moving Target
Why Specifics Here Will Go Stale Quickly
Coding agents in this category ship new defaults, renamed settings, and new underlying models on a timeline measured in weeks, not years. The exact flag names, default model, and even some of the terminology used for approval and sandbox settings in this guide reflect what OpenAI's own documentation stated at the time this page was written, and some of it has already changed once before: older unofficial write-ups describe an earlier approval-mode scheme with different names than the one documented today.
If something here doesn't match what you see on your own screen, trust the official documentation and your own running instance of the tool over this page or any other secondhand write-up, including ones that look authoritative. That habit, checking a primary source instead of trusting a confident-sounding secondary one, is worth more than memorizing any specific flag name, and it's the same habit worth building around any fast-moving AI tool, not just this one.
Giving an AI Agent Standing Instructions Is a Transferable Skill
Writing a clear AGENTS.md or CLAUDE.md file, and understanding what an agent is and isn't allowed to do automatically, matters whichever coding agent you're using. Nightschool AI's free lesson on building a project's instruction file walks through exactly that, using Claude Code as the example.
Frequently Asked Questions
Is Codex CLI free to use?
Access runs through either a ChatGPT Plus, Pro, Business, Edu, or Enterprise subscription, or an API key billed separately by usage. There is no free, no-account way to use it documented by OpenAI.
Do I need to know a specific command syntax to give Codex a task?
No. Once the tool is running, you type your task in plain language, the same way you'd describe it to a person. A handful of slash commands exist for things like checking status or switching models, but the task itself is just natural language.
What's the difference between Codex CLI and the Codex website or IDE extension?
They're related but distinct surfaces from the same product family. Codex CLI runs in your terminal on your own machine; there's also a separate IDE extension, a desktop app, and a cloud-hosted version that runs tasks without using your local machine at all.
What does AGENTS.md actually do?
It's a plain Markdown file Codex reads automatically before working, giving it standing project instructions like test commands or formatting conventions. A global copy applies everywhere, and project-level copies closer to your working folder can override it.
What's the difference between sandbox mode and approval policy?
Sandbox mode is a technical boundary on what Codex can actually do, such as whether it can edit files or reach the network. Approval policy is a separate setting for when it has to stop and ask you first. They're tuned independently, not as one combined setting.
Is it safe to use the full-bypass flag?
OpenAI documents it as a deliberate way to skip both the sandbox boundary and approval prompts at once. Treat it as an exception for a specific, trusted task and environment, not something to leave on by default.
Is this page affiliated with OpenAI?
No. This is an independent educational guide, not published or endorsed by OpenAI. Codex, Codex CLI, and ChatGPT are OpenAI's own products and trademarks, referenced here only to describe them accurately.
Does Codex CLI work the same way on Windows as on macOS and Linux?
Mostly, with platform differences underneath. OpenAI documents a native Windows sandboxing approach as well as support for running under WSL2, which uses the Linux sandboxing path instead. The day-to-day experience of typing a task is the same across platforms.
Will the specific settings and model names in this guide still be accurate later?
Probably not indefinitely. This space moves quickly, and some terminology here has already replaced an earlier naming scheme once. Check the current official documentation before relying on any specific flag or model name for something important.
Learn the Habits That Transfer Across Any AI Coding Tool
Reading the real docs, writing a clear instruction file, and understanding what you've actually granted an agent.