OpenAI Codex CLI: an Open Source Coding Agent in the Terminal

The command line interface (CLI) remains the undisputed domain of many developers – a place of efficiency, power, and deep integration into the development lifecycle. Now, imagine augmenting that environment with an intelligent agent capable of understanding your code, editing files, running commands, and iterating on solutions, all without leaving the comfort of your terminal. This is the promise of the OpenAI Codex CLI, a lightweight coding agent available via npm (@openai/codex), designed specifically for developers who live in the terminal.

This isn't just another chatbot. The Codex CLI aims to provide ChatGPT-level reasoning combined with the practical ability to execute tasks directly within your local repository. It interacts with your files, runs shell commands (safely!), and integrates seamlessly with version control, making it a true partner in chat-driven development that understands your repo's context.

Getting Started with OpenAI Codex CLI:

Getting started with the Codex CLI is designed to be straightforward, reflecting its "zero setup" philosophy (beyond providing your API key).

To run Codex CLI, your system should meet these requirements:

• Operating Systems: macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2.
• Node.js: Version 22 or newer (LTS recommended).
• Git (Optional, Recommended): Version 2.23+ for full functionality, especially version control integration and potential PR helper features.
• RAM: 4 GB minimum, 8 GB recommended.

GitHub - openai/codex: Lightweight coding agent that runs in your terminal

Lightweight coding agent that runs in your terminal - openai/codex

GitHubopenai

Installation: As a Node.js tool, installation is handled via npm (or yarn). Install it globally to make the codex command available anywhere in your terminal:

npm install -g @openai/codex

(Remember the standard advice: avoid sudo npm install -g; configure npm permissions correctly if needed).

API Key Setup: Codex CLI requires your OpenAI API key to function. You need to set this as an environment variable:

export OPENAI_API_KEY="your-api-key-here"

Crucially, remember that this export command typically only sets the variable for your current terminal session. To make it permanent, you should add this line to your shell's configuration file, such as ~/.zshrc, ~/.bashrc, or ~/.bash_profile, depending on your shell.

Running Codex: You can interact with Codex in a few ways:

Interactive Mode: Simply type codex to start an interactive session (REPL - Read-Eval-Print Loop) where you can issue commands and instructions.

Direct Prompt: Provide an initial prompt directly from the command line:

codex "explain this codebase to me"

Automated Execution: Combine a prompt with an approval mode (more on this later) for more automated tasks:

codex --approval-mode full-auto "create the fanciest todo-list app"

Once invoked, Codex gets to work. It might scaffold files, run code within a sandbox, install any necessary dependencies it identifies, and present the results. You then review the proposed changes (file diffs, command outputs) and approve them to be committed to your working directory.

Why Choose OpenAI Codex CLI?

The Codex CLI carves out a specific niche for developers seeking AI assistance deeply embedded in their existing workflows. Its key selling points, derived directly from its design philosophy, include:

• Terminal-Native: Built for developers who prefer the CLI. It avoids context switching to web UIs or separate applications.
• Reasoning + Execution: Goes beyond just suggesting code or explaining concepts. It leverages powerful AI reasoning (like ChatGPT) but crucially adds the ability to run code, manipulate files, and iterate on solutions within your project.
• Repo-Aware: It understands it's operating within a specific codebase and can leverage that context.
• Zero Setup (Almost): Bring your OpenAI API key, install the package, and it's ready to go.
• Safe Automation: Offers configurable levels of automation, including a "Full Auto" mode, but implements security through network disabling and directory sandboxing.
• Multimodal Input: Explicitly mentions the capability to accept screenshots or diagrams as input for implementing features, leveraging the power of underlying multimodal models. ✨
• Open Source: The entire project is open source, fostering transparency, community contribution, and trust.

Three Modes of OpenAI Codex CLI, Explained:

Granting an AI tool the power to edit files and execute shell commands necessitates a robust security model. Codex CLI addresses this with transparency and user control via the --approval-mode flag (settable via command line or an interactive prompt during onboarding):

Suggest Mode (Default):

• Allowed without asking: Read any file in the repository.
• Requires Approval: ALL file writes/patches and ALL shell/Bash commands.
• Use Case: Safest mode, ideal for sensitive operations, learning the tool, or when maximum control is desired.

Auto Edit Mode:

• Allowed without asking: Read files AND apply patch/write changes to files.
• Requires Approval: ALL shell/Bash commands.
• Use Case: Balances automation for code changes while retaining manual control over potentially system-altering commands. Speeds up refactoring and code generation.

Full Auto Mode:

• Allowed without asking: Read/write files AND execute shell commands.
• Requires Approval: None (within the sandbox).
• Use Case: Maximum automation for trusted tasks.

Built-in Safeguards:

• Sandboxing: In Full Auto mode, commands are run with significant restrictions for defense-in-depth:
• Network Disabled: Prevents unexpected external communication (e.g., curl calls will fail by default).
• Directory Confinement: Operations are restricted to the current working directory ($PWD) and designated temporary/cache areas ($TMPDIR, ~/.codex, etc.).
• Git Awareness: Codex CLI checks if the target directory is tracked by Git. If you attempt to start in auto-edit or full-auto mode in an untracked directory, it will show a warning/confirmation prompt, ensuring you always have the safety net of version control to review and revert changes.
• Future Enhancements: The documentation notes plans to allow whitelisting specific commands for auto-execution with network enabled once additional safeguards are confidently implemented.

Platform-Specific Sandboxing:

The underlying hardening mechanism adapts to the host operating system, aiming for transparency in usage:

• macOS (12+): Uses the native Apple Seatbelt technology (sandbox-exec). The process is placed in a read-only jail with specific writable exceptions ($PWD, $TMPDIR, ~/.codex). Outbound network access is blocked.
• Linux: Recommends using Docker for sandboxing. Codex can launch itself inside a minimal container image, mounting the repository read/write. A custom iptables/ipset firewall script denies all network egress except for necessary communication with the OpenAI API. This provides deterministic and reproducible runs without requiring root privileges on the host machine (details in run_in_container.sh).
• Windows: Supported via Windows Subsystem for Linux 2 (WSL2), likely leveraging the Linux sandboxing approach within the WSL environment.

OpenAI Codex CLI Configurations

Beyond basic interaction, Codex CLI offers ways to tailor its behavior and integrate it into more complex workflows.

CLI Reference:

• codex: Interactive mode.
• codex "...": Interactive mode with an initial prompt.
• codex -q "..." or codex --quiet "...": Non-interactive "quiet mode," suitable for scripting. Outputs JSON if -json flag is added.
• Key Flags:
• -model / m: Specify the OpenAI model to use (e.g., gpt-4, o4-mini).
• -approval-mode / a: Set the automation level (suggest, auto-edit, full-auto).
• -quiet / q: Enable non-interactive mode.

Memory & Project Context:

Codex CLI can incorporate project-specific instructions and context from Markdown files, layering them in a specific order of precedence:

1. ~/.codex/instructions.md: Personal, global guidance applied to all projects.
2. codex.md (at repository root): Shared project notes, conventions, or high-level context for the entire repo.
3. codex.md (in current working directory): Specific instructions for sub-packages or directories.

This allows teams to embed project standards or provide hints directly within the codebase for Codex to use. This feature can be disabled using the --no-project-doc flag or by setting the environment variable CODEX_DISABLE_PROJECT_DOC=1.

Non-interactive / CI Mode:

Designed for automation, Codex CLI can run headlessly in Continuous Integration (CI) pipelines. By using the --quiet (or -q) flag or setting the CODEX_QUIET_MODE=1 environment variable, interactive UI elements are suppressed.

Example GitHub Action step:

- name: Update changelog via Codex
  run: |
    npm install -g @openai/codex
    export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
    codex -a auto-edit --quiet "update CHANGELOG for next release based on recent commits"

Configuration Files:

Codex looks for configuration in the ~/.codex/ directory:

~/.codex/config.yaml: Define defaults like the preferred model or behavior on errors in full-auto mode.

model: o4-mini # Default model for invocations
fullAutoErrorMode: ask-user # Behavior on error: ask-user or ignore-and-continue

~/.codex/instructions.md: As mentioned above, for global custom instructions (e.g., "Always respond with emojis", "Only use git commands if I explicitly mention you should").

Practical Applications: Recipes for Success

The README provides several concrete examples ("recipes") demonstrating the kinds of tasks Codex CLI is suited for:

1. Refactoring Code: codex "Refactor the Dashboard component to React Hooks" - Codex analyzes the class component, attempts the rewrite, potentially runs tests (npm test), and shows the diff for approval.
2. Generating Migrations: codex "Generate SQL migrations for adding a users table" - It might infer the ORM being used (e.g., Prisma, Sequelize), create the necessary migration files, and potentially run them in a sandboxed database environment.
3. Writing Unit Tests: codex "Write unit tests for utils/date.ts" - Codex generates test cases, executes them (likely via shell commands like npm test or jest), and potentially iterates, fixing the code or tests until they pass.
4. Bulk File Operations: codex "Bulk‑rename *.jpeg → *.jpg with git mv" - It formulates and executes the necessary git mv commands, potentially updating references/imports in the code as well.
5. Explaining Code/Regex: codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$" - Leverages the LLM's explanatory power to provide a human-readable breakdown.
6. High-Level Repo Analysis: codex "Carefully review this repo, and propose 3 high impact well-scoped PRs" - Demonstrates potential for strategic code review and suggestion generation.
7. Security Audits: codex "Look for vulnerabilities and create a security review report" - Uses the AI's knowledge base to identify potential security flaws and explain them.

Conclusion

By being open-source and built for the CLI-centric developer, Codex CLI aims to become an indispensable, trustworthy coding agent – enhancing productivity and allowing developers to focus on more complex challenges, right from their command line. As it continues active development, it holds the potential to significantly reshape how developers interact with AI in their daily workflows.