OpenAI Codex CLI: how it works and when to use it

OpenAI's Codex CLI brings a capable AI coding agent directly into your terminal. No browser tab, no IDE plugin, no context switching. You describe what you want, and the agent reads your files, writes code, runs commands, and iterates — all from the command line.

This guide covers what the Codex CLI actually is, how it works under the hood, when it makes sense to use it, and what to think about when you want it running beyond your local machine.

What Is the OpenAI Codex CLI?

The Codex CLI is an open-source terminal agent built by OpenAI. It runs locally and connects to OpenAI's models to handle coding tasks through natural language prompts. Tell it something like "add input validation to the registration form" or "write tests for this module," and it reads your codebase, proposes changes, and can execute them directly.

Worth clarifying: this is not the older Codex API — the code-completion model OpenAI deprecated in 2023. The CLI is an agentic tool. It takes multi-step actions, not single-shot responses.

Codex separates filesystem and network sandboxing from approval policy. You choose what the agent may do inside the workspace and when it must ask before crossing a boundary. The exact configuration evolves, so use the current OpenAI Codex documentation rather than relying on older mode names.

That separation matters. A scoped refactor may permit workspace edits and test commands while still requiring approval for network access, changes outside the repository, or consequential operations.

How the Codex CLI Works

The Core Loop

When you run codex with a task, the agent follows a reasoning loop: read relevant files, plan the steps, apply changes, run commands to verify, and report back. Each step is visible in the terminal so you can follow along and interrupt if something looks off.

The agent has access to your local filesystem and can run shell commands inside a sandboxed environment. By default it uses a network-disabled, read-only root filesystem with only your working directory writable — which limits the blast radius of mistakes.

Authentication

Codex supports OpenAI's current documented authentication methods, which may include signing in with an eligible ChatGPT account or using an API key. Use the method and billing model appropriate for your organization; do not copy browser cookies or unrelated credentials into a remote environment.

Context Window and File Handling

The agent reads files from your working directory and passes relevant content into the model's context window. For large codebases, it selects files based on what seems relevant to the task rather than loading everything at once. Prompt quality matters here: the more specific your task description, the better the agent's file selection.

Installation

Follow OpenAI's current installation instructions. One supported distribution method is the npm package:

npm install -g @openai/codex

Once installed, authenticate through a supported method and run codex from a project directory.

What the Codex CLI Is Good At

The CLI handles a wide range of practical coding tasks well.

Refactoring and cleanup. Ask it to rename a function across the codebase, extract a class, or simplify a complex conditional. It reads the relevant files, makes the changes, and shows you a diff before applying anything.

Writing tests. Give it a module and ask for unit tests. It reads the implementation, infers expected behavior, and writes test cases for your review.

Bug fixes from descriptions. Describe the bug in plain language and the agent traces through the code to find and fix the cause. This works best when the bug is localized to a few files.

Scaffolding new features. Tell it to add an endpoint, a migration, or a new component following the patterns already in your project. It reads existing code for style and structure before generating anything new.

Documentation. Ask it to write docstrings, update a README section, or generate an API reference from your source files.

When the Codex CLI Is the Right Tool

The Codex CLI fits naturally into a focused work session where you're already in the codebase and want to delegate specific steps without switching tools. It's a good fit when tasks are well-scoped, local, and benefit from tight feedback loops — you see every step in the terminal and can approve or reject changes inline, which gives you more control than a background agent running asynchronously.

When It Gets Complicated

When the CLI runs locally, it depends on your machine staying awake and on working network access. For short tasks, that is usually fine. For longer-running work, it can become a real constraint.

Laptop sleep pauses useful work. A temporary network failure may interrupt an active model call even if the terminal process remains. If you want to start a task and inspect it from another device, run Codex on remote compute or use an appropriate managed Codex workflow.

This is where developers start looking at persistent cloud environments. If you've run into the same problem with Claude Code, the post on keeping Claude Code running after your laptop closes covers the same underlying issue from a different angle.

Running Codex CLI in a Persistent Cloud Environment

If you want Codex CLI to run continuously without depending on your local machine, the practical answer is to run it on a dedicated cloud computer where sessions persist across disconnects.

Matrix OS provisions a dedicated VPS for each user where AI coding agents — including Codex — run in persistent sessions. Start a Codex session, close your laptop, and the agent keeps working. Reconnect from any terminal or browser and pick up exactly where things left off.

This matters most for longer tasks: a large refactor, batch test generation across multiple modules, or a background bug triage workflow. These are exactly the situations where a local session becomes a liability.

Matrix OS also supports running multiple agents simultaneously on the same persistent machine with shared file state. If you use Codex for some tasks and Claude Code or Gemini CLI for others, they share the same codebase and environment without you rebuilding anything. That's the core idea behind what a cloud computer for agents actually means in practice.

Codex CLI vs. Other Agent Options

Codex CLI vs. Claude Code

Both are terminal-based coding agents with similar agentic loops. The main differences are the underlying model (OpenAI for Codex, Anthropic's Claude for Claude Code), the approval flow UX, and community tooling. Some developers prefer one for certain task types and use both. Neither is inherently better — they have different strengths depending on the codebase and the work.

Codex CLI vs. Cursor

Cursor is an IDE with AI features built in. The Codex CLI is a terminal agent with no IDE dependency. If you prefer working in a terminal or want to use the agent in CI or automation scripts, the CLI fits better. If you want inline suggestions and a visual editor, Cursor fits better. They serve different workflows.

Codex CLI vs. Devin

Devin packages the agent, managed environment, and task interface together. Codex CLI is a terminal agent that you can place on infrastructure you control. The tradeoff is managed delegation versus direct control of the runtime and tooling.

Practical Tips for Getting the Most Out of Codex CLI

Be specific about scope. The agent performs better when you tell it exactly which files or modules to work in. "Refactor the auth module in src/auth/" is better than "clean up the auth code."

Use full auto mode carefully. It's powerful for trusted, well-scoped tasks. For anything touching production configs or sensitive files, stick with auto-edit so you approve shell commands before they run.

Keep tasks atomic. Break large changes into smaller tasks rather than asking the agent to do everything in one prompt. Smaller tasks produce cleaner diffs and are easier to review.

Review diffs before merging. The agent writes code that's often good, but it's not infallible. Treat its output the way you'd treat a PR from a capable but new contributor: read it before you ship it.

Set your working directory intentionally. The agent reads from your current directory. Start it from the right project root so it has the context it needs.

FAQs

What models does the Codex CLI use? The CLI connects to OpenAI's API and uses the codex-1 model by default, which is optimized for agentic coding tasks. You can configure the model in the CLI settings if you want to use a different OpenAI model.

Is the Codex CLI free to use? The CLI itself is free and open-source. You pay for API usage through your OpenAI account at standard rates. Costs depend on how much you run it and the size of the tasks.

Can the Codex CLI access the internet? By default, the CLI runs in a sandboxed environment with network access disabled — an intentional safety measure. You can configure this if your tasks require network access.

Does the Codex CLI work on Windows? The CLI is designed for Unix-like environments and works on macOS and Linux. Windows users can run it through WSL (Windows Subsystem for Linux).

What happens if I close my terminal while the agent is running? A local terminal close may stop the attached process unless a session manager keeps it alive. If you want work to continue independently of the laptop, run the CLI inside tmux on a remote server or on a dedicated cloud computer. Preserve progress through Git rather than assuming the process will survive every failure.

Can I run Codex CLI alongside other agents like Claude Code? Technically yes. The practical challenge is managing shared file state and avoiding conflicts. Running them in isolated sessions on a persistent cloud machine with shared file access is a cleaner approach than trying to manage this locally.

How does the Codex CLI handle large codebases? It selects files relevant to your task rather than loading the entire codebase into context. For very large repositories, being explicit about which directories or files to focus on helps the agent work more accurately and efficiently.

Conclusion

The Codex CLI is a practical, well-designed terminal agent for developers who want AI help without leaving the command line. It handles refactoring, test writing, bug fixes, and scaffolding well, and its approval modes give you real control over how much autonomy the agent has.

The main limitation is that it runs locally. For tasks that need to outlast your laptop session — or workflows where you want Codex running alongside other agents on the same codebase — a persistent cloud environment solves the problem cleanly.

If you want to run Codex and other agents in persistent sessions without managing your own infrastructure, take a look at matrix-os.com.