title: "What Is Agentic Development? — Codex CLI" tested_with: codex-cli: "0.2.x" last_updated: 2026-03-21 status: proven difficulty: beginner prerequisites: []

What Is Agentic Development? — Codex CLI

What Codex CLI Is

Codex CLI is OpenAI's terminal-based agentic coding tool. Like Claude Code, it runs in your terminal, inside your project directory, and works directly with your codebase. You describe a task in natural language, and Codex reads files, writes code, runs commands, and iterates toward a solution.

Codex CLI is open source and designed around a principle of safe-by-default execution. Its defining characteristic is a sandboxed execution model — commands run in an isolated environment that limits what the agent can do to your system unless you explicitly opt out. This makes it a good fit if you want agentic capabilities with tighter guardrails out of the box.

The Architecture

Your Terminal
    |
    v
Codex CLI (local process)
    |
    v
OpenAI models (OpenAI API)
    |
    v
Sandboxed Execution: File Read | File Write | Command Execution

When you type a message, Codex CLI sends it — along with context about your project — to an OpenAI model (typically GPT-4.1 or o4-mini). The model decides what to do: read files, edit code, or run commands. Codex CLI executes those actions in a sandboxed environment on your machine and sends the results back to the model. The loop continues until the task is complete.

The sandbox is the architectural distinction. By default, Codex CLI uses platform-level isolation (network-disabled containers on Linux, or seatbelt sandboxing on macOS) to ensure that commands the agent runs cannot make network requests or modify files outside your project directory. This is a meaningful safety property, especially when running in more autonomous modes.

Key Capabilities

File reading. Codex CLI reads files from your project to understand context. It examines source code, configuration files, and project manifests to orient itself before making changes.

File editing. Codex CLI creates and modifies files in your project. Edits are presented as patches that you can review. In more autonomous modes, edits are applied directly.

Command execution. Codex CLI runs shell commands — tests, builds, linters, and other tools. By default, these commands run inside the sandbox, which means they have no network access and cannot modify files outside the working directory. This is a deliberate safety decision: even if the model decides to run something unexpected, the blast radius is contained.

Sub-agents. For multi-part tasks, Codex CLI can use sub-agents to handle specific pieces of work, similar to how Claude Code uses them. The main agent coordinates while sub-agents focus on individual steps.

The Sandbox Model

The sandbox is central to how Codex CLI works, so it is worth understanding clearly.

What the sandbox does:

  • Disables network access for all commands the agent runs.
  • Restricts file writes to your project directory (and temporary directories).
  • Uses OS-level isolation, not just permission checks — this is enforced at the kernel level.

Why this matters:

  • If the agent tries to curl something or pip install a package, it will fail inside the sandbox. This is by design.
  • If the agent tries to modify files outside your project, it will fail.
  • You can run in more autonomous modes without worrying that the agent will make unintended changes to your system.

When the sandbox gets in the way:

  • Tasks that require network access (installing dependencies, fetching data, calling APIs) will not work inside the sandbox.
  • You can disable the sandbox for specific sessions if you need network access, but you are then accepting the tradeoff.

The sandbox is the primary reason Codex CLI can offer a full-auto mode with reasonable safety properties. More on that below.

Approval Modes

Codex CLI offers three operating modes that control how much autonomy the agent has. Choosing the right mode is an important decision.

1. Suggest (default) The agent reads files and proposes changes, but does not apply them or run commands without your explicit approval. Every action requires a confirmation step. This is the safest mode and the right starting point for new users.

Use this when: you are learning the tool, working in an unfamiliar codebase, or doing anything where you want to review every step.

2. Auto-edit The agent can read and write files without approval, but command execution still requires confirmation. This is a good middle ground — the agent can move quickly on code changes while you retain control over what commands run.

Use this when: you trust the agent's edits on your codebase and want to move faster, but still want to approve shell commands.

3. Full-auto The agent reads files, writes files, and runs commands without asking. The sandbox is your safety net here — since commands cannot access the network or modify files outside your project, the blast radius of any mistake is contained.

Use this when: the task is well-defined, you have version control (so you can revert), and the sandbox restrictions do not conflict with what the agent needs to do. This mode is where you experience the full speed of agentic development.

The recommendation: start with suggest mode. Move to auto-edit once you are comfortable with the agent's editing behavior. Move to full-auto only for tasks where the sandbox provides sufficient guardrails and you can verify the result after.

How Codex CLI Differs from Claude Code

Both are terminal-based agentic coding tools, but they make different design choices.

Sandbox vs. permission model. Codex CLI defaults to sandboxed execution — commands are isolated at the OS level. Claude Code defaults to a permission-based model — you approve actions individually. The sandbox approach is more restrictive but requires less vigilance. The permission approach is more flexible but requires you to pay attention.

Underlying models. Codex CLI uses OpenAI models (GPT-4.1, o4-mini, and others in the OpenAI family). Claude Code uses Anthropic's Claude models. The models have different strengths: Claude tends to be strong at careful reasoning, following nuanced instructions, and producing well-structured prose. OpenAI models tend to be strong at code generation breadth and multi-language support. In practice, both are capable enough for most agentic coding tasks.

Configuration approach. Codex CLI uses AGENTS.md files for project-specific instructions — the equivalent of Claude Code's CLAUDE.md. The format and purpose are similar: you describe your project's conventions, preferred patterns, and constraints, and the agent follows them.

Network access. Codex CLI blocks network access by default inside the sandbox. Claude Code does not restrict network access (commands run in your normal shell environment). This matters for tasks that require dependency installation, API calls, or fetching resources.

Open source. Codex CLI is open source. You can read the code, understand exactly what it does, and modify it. Claude Code is not open source, though its behavior is well-documented.

Neither tool is universally better. The right choice depends on your workflow, your preferred model, and how much you value sandboxing vs. flexibility. Many developers use both.

Quick Install and First Run

Prerequisites: Node.js 22 or later.

Install:

npm install -g @openai/codex

Set your API key:

export OPENAI_API_KEY=your-key-here

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) so it persists.

First run:

cd /path/to/your/project
codex

Codex CLI starts an interactive session. You see a prompt where you can type your first message. Try:

> Explain the structure of this project and what each top-level directory contains.

Observe the agent's behavior. It will read your directory listing, examine key files, and synthesize a summary. Notice which files it chooses to read and in what order — this gives you insight into how the agent navigates.

Specifying approval mode:

codex --approval-mode full-auto

Or for suggest mode (the default):

codex --approval-mode suggest

One-shot mode (non-interactive):

codex -q "What does the main function in src/index.ts do?"

The -q flag (quiet) runs a single prompt and prints the result, useful for quick questions.

AGENTS.md

Codex CLI reads AGENTS.md files from your project root and subdirectories. This is where you put project-specific instructions that the agent should follow: coding standards, architectural patterns, libraries to prefer or avoid, and any context that is not obvious from the code itself.

If you are setting up Codex CLI on an existing project, creating an AGENTS.md with basic guidance is a worthwhile first step. Later modules in this curriculum will cover how to write effective agent instruction files in detail.