Codex CLI: OpenAI's terminal coding agent, installed and judged

The gap Codex CLI fills between chat and your shell

A chat window can explain a bug. It cannot read your working tree, apply a patch, and then run the test suite to see whether the patch held. Codex CLI is built for that second job. The README describes it as "a coding agent from OpenAI that runs locally on your computer", and the repository description adds the three capabilities that define the product: it can inspect a repository, edit files, and run commands.

The audience is narrow on purpose. This is a terminal tool for people who already live in a shell, who have a repository checked out locally, and who want an agent to operate on that checkout rather than on a pasted excerpt of it. If your workflow is a graphical editor with an inline assistant, the README points you elsewhere: it links to an IDE installation path for VS Code, Cursor and Windsurf, and to a separate desktop app entry point. Codex CLI is the third surface, not a replacement for the other two.

One distinction matters before anything else. The README separates three products that share the name. Codex CLI is local. Codex Web is "the cloud-based agent from OpenAI" at chatgpt.com/codex. The desktop experience is reached through the codex app subcommand. People searching for what Codex is will find all three under one brand, and the differences are not cosmetic: local execution means your files and your shell, cloud execution means someone else's machine.

How the agent is wired: Rust core, Bazel build, thin CLI surfaces

The repository is a monorepo, and its layout tells you where the weight sits. The top level holds codex-rs, codex-cli, sdk, docs, bazel, patches and scripts, plus Bazel files at the root: BUILD.bazel, MODULE.bazel, MODULE.bazel.lock, .bazelrc and .bazelversion. Rust is the primary language, and the agent logic lives under codex-rs as a set of Cargo crates.

The justfile confirms the shape of that workspace. It sets its working directory to codex-rs, and its aliases run binaries directly from source: the codex alias expands to cargo run --bin codex, exec expands to cargo run --bin codex -- exec, and there are separate targets for codex-file-search and codex-code-mode-host. A tui-with-exec-server target starts an exec server and then runs the TUI against it, which implies the terminal interface and the execution layer are separable processes rather than one monolith.

The Node side is maintenance scaffolding, not the product. package.json names the package codex-monorepo, marks it private, describes it as "Tools for repo-wide maintenance", and lists exactly one devDependency: prettier. The engines field requires Node 22 or newer and pnpm 10.34.5 or newer, and the packageManager field pins pnpm to 10.34.5 with an integrity hash. If you are reading this repository to understand the agent, codex-rs is where to look; the JavaScript tooling exists to format JSON, Markdown and workflow files.

That split has a practical consequence. The published npm package is @openai/codex, a distribution artifact, while the repository's own package.json is private and never published. The two are not the same thing, and the version you get from npm is not the version pinned in this workspace.

Installing Codex CLI and running your first task

The README gives a one-line installer for Mac and Linux. It pipes a script from chatgpt.com into sh:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows the equivalent is a PowerShell command that downloads and executes install.ps1:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The README states that these standalone installers download from releases.openai.com/codex by default and fall back to GitHub Releases if a metadata or asset download is unavailable. You can force the GitHub path by setting CODEX_INSTALLER_USE_RELEASES_OPENAI_COM to false; the README notes that 0 and no are also accepted. The shell form passes it inline:

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

If you prefer a package manager, the README lists two. The npm route installs the scoped package globally:

npm install -g @openai/codex

Homebrew users install it as a cask rather than a formula:

brew install --cask codex

After installation, the README says to run codex to get started. The first thing you will see is an authentication choice. The README recommends selecting Sign in with ChatGPT, which ties the tool to a Plus, Pro, Business, Edu or Enterprise plan. An API key path exists, but the README is explicit that it "requires additional setup" and links to a separate authentication page rather than describing it inline. For a first real use, start the agent inside a repository you already have checked out, let it read the tree, and give it a task scoped to one directory. The repository also carries an AGENTS.md at its root, which is the conventional place for project-level instructions the agent reads; the README does not document the file's semantics, so treat it as a convention to inspect rather than a documented contract.

The alpha release cadence is the real adoption risk

Look at the release feed rather than the README. The three most recent releases are rust-v0.151.0-alpha.12, rust-v0.151.0-alpha.9 and rust-v0.151.0-alpha.8, all published within roughly a day of each other in late August 2026. The last push to the repository was on 2026-08-29. Nothing here is archived, and the project is clearly moving, but the version numbers you would install carry an alpha suffix, and three alphas in under 36 hours is not a stabilisation pattern.

That matters for two reasons. First, reproducibility. If you install through the standalone script, you are pulling whatever the release endpoint currently serves, not a version you chose. Pinning means going to the GitHub Releases page and downloading a specific archive by name, for example codex-x86_64-unknown-linux-musl.tar.gz on Linux x86_64 or codex-aarch64-apple-darwin.tar.gz on Apple Silicon. The README notes each archive contains a single entry with the platform baked into the name, so you rename it to codex after extracting. Second, behaviour drift. An agent that edits files and runs commands is only as predictable as the model and prompt scaffolding behind it, and both can change between alphas without any change to the CLI flags you learned.

There is a second limitation the README is silent on: rollback. The documentation describes installation and authentication but does not document an uninstall path, a downgrade procedure, or a way to pin the installer to a specific version. If you need those, you are reading release notes and GitHub Releases yourself.

Codex CLI versus Claude Code, and when a chat window is the better tool

The comparison people actually search for is Codex versus Claude Code, and the difference is in where the agent runs and what it is allowed to touch. Codex CLI is a Rust binary installed on your machine that operates on a local checkout and executes shell commands there. The README's own framing separates it from Codex Web, the cloud agent, on exactly that axis: local versus remote execution. Any tool in this category makes the same fundamental trade: it gets real filesystem and shell access, and in exchange you are trusting an agent with write access to your working tree.

Against a plain ChatGPT session, the distinction is capability rather than quality. A chat session cannot run your tests. Codex CLI can, which is why the exec subcommand exists as a separate entry point in the justfile and why the README describes the tool as inspecting repositories and running commands. If your task is "explain this stack trace", a chat window is cheaper and involves no installation. If your task is "find why this test fails and fix it", you need something that can execute.

Where Codex CLI is the wrong tool: environments where the agent cannot be given shell access, teams that require a reviewed, versioned dependency with a stable interface, and anyone whose work happens in a browser or on a phone. The README offers no mobile path and no self-hosted server story. It also has nothing to say about running the agent against a remote machine, so if your code is not checked out locally, this is not the product you want.

Licence, upgrade cost, and what the build system implies for contributors

The repository is licensed under Apache-2.0, stated both in the README and in the LICENSE file at the root. Apache-2.0 is a permissive licence with an explicit patent grant and a NOTICE file requirement; the repository carries a NOTICE file, which is consistent with that. This is a statement about what the repository says, not legal advice, and the licence covers the source in this repository rather than any hosted service you reach through the ChatGPT sign-in path.

The upgrade cost is the part worth budgeting. Because releases are published as alpha versions and the installer resolves to a rolling endpoint, the honest position is that you upgrade when you choose to, and you should know which build you are on. The repository gives you the tooling to check: the justfile exposes fmt and fmt-check, which run scripts/format.py, and clippy and fix targets that wrap cargo clippy. Building from source requires the Rust toolchain plus Bazel, given the root BUILD.bazel, MODULE.bazel and .bazelversion files. That is a heavier contributor setup than a plain Cargo project, and it is the price of a monorepo that also ships an npm package, a Python SDK directory and a Bazel build graph.

Editorial conclusion

Adopt Codex CLI if you already pay for a ChatGPT plan and want an agent that works inside your existing terminal and shell rather than inside an editor plugin. Skip it if you need a frozen, versioned toolchain: the current release line is 0.151.0-alpha, and the install script pulls from a rolling release endpoint. Before you commit, verify two things on your own machine: that the binary your package manager installs resolves to the same build as the standalone installer, and that your project's AGENTS.md instructions are actually being read, since that file is the main lever you have over agent behaviour.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes