Codex: OpenAI's Open-Source Coding Agent

1. Project Overview

Codex is OpenAI's open-source coding agent that runs locally in your terminal, letting developers chat with an AI that can read a codebase, edit files, run commands in a sandbox, and iterate on changes without leaving the command line.

2. Background & Positioning

Codex was built to bring OpenAI's agentic coding capabilities directly onto developers' own machines, rather than confining them to a cloud IDE or chat window. Its core mission is to give engineers a fast, scriptable, and privacy-respecting way to delegate real engineering work — reading unfamiliar code, drafting patches, running tests, debugging failures — to an AI agent that operates with the same terminal and file system a human developer would use.

Compared to other AI coding assistants, Codex differentiates itself in three ways:

Local-first execution: the agent runs as a lightweight binary on the developer's machine (originally in TypeScript, now rewritten in Rust for performance and reliability), rather than requiring a hosted container per session.
Configurable sandboxing and approvals: every command the agent wants to run passes through an explicit sandbox and approval policy, so users can dial the balance between autonomy and oversight — from "ask before every action" to "fully autonomous."
Multiple entry points, one agent: the same Codex engine is exposed as a terminal CLI, an IDE extension (VS Code, Cursor, Windsurf), and a desktop app, so teams aren't locked into a single workflow.

3. Feature Categories

🖥️ Terminal Agent — core interactive experience

codex — start an interactive session in the current repository
codex exec "<prompt>" — run a one-shot, non-interactive task (useful in scripts/CI)
Multi-turn conversation with full context of the working directory
Inline diffs and command output streamed directly to the terminal
Purpose: let developers drive real code changes without switching out of the shell.

🛡️ Sandboxing & Approvals — safety controls

Read-only mode: the agent can inspect files but not modify anything or run arbitrary commands
Workspace-write / auto mode: the agent can edit files and run commands confined to the project directory
Full-auto mode: the agent executes multi-step plans without per-command confirmation, inside the sandbox
Platform-native sandboxing (e.g. macOS Seatbelt, Linux containers/namespaces) to restrict filesystem and network access
Purpose: let users choose exactly how much autonomy to grant the agent.

🔌 Integrations — connecting Codex to your project and tools

AGENTS.md — a project-level file describing conventions, commands, and context the agent should follow
MCP (Model Context Protocol) server support for extending the agent with external tools
Skills stored under .codex/skills for reusable, project-specific agent capabilities
IDE extensions for VS Code, Cursor, and Windsurf
Purpose: make Codex aware of project-specific rules and extend it with custom tools.

☁️ Multi-Agent Orchestration — coordinating larger tasks

Task decomposition across multiple Codex instances
Agent-to-agent communication and shared context
Conflict resolution when several agents touch overlapping code
Purpose: scale the agent from single-file edits to coordinating larger, multi-part projects.

⚙️ Enterprise & Automation — running Codex outside a human terminal

Hooks system (e.g. user-prompt hooks) to intercept, audit, or augment agent prompts
CI/automation-friendly non-interactive mode
Configuration profiles for teams with shared policies
Purpose: let organizations embed Codex into pipelines and enforce governance.

4. Key Highlights

Rust-based rewrite: the CLI's execution engine (codex-rs) is implemented in Rust, prioritizing startup speed, low memory footprint, and reliability for long-running agent sessions.
Configurable autonomy: sandbox and approval settings range from strictly read-only to fully autonomous, so the same tool fits both cautious first-time use and hands-off automation.
Flexible authentication: sign in with an existing ChatGPT Plus, Pro, Business, Edu, or Enterprise plan, or authenticate with an API key — no separate account required for most users.
Project-aware context via AGENTS.md: teams can document conventions once in AGENTS.md, and the agent will consistently follow them across sessions.
Extensible through MCP: the Model Context Protocol lets Codex connect to external tools and data sources beyond the local filesystem and shell.
Multiple surfaces, one engine: the identical agent is available as a terminal CLI, IDE extension, and desktop app, so it fits into whichever workflow a team already uses.

5. Use Cases by Role

General Developers — use Codex to explore unfamiliar codebases, draft bug fixes, generate tests, or scaffold new features directly from the terminal, with diffs reviewed before they land.

DevOps / SRE — run Codex in non-interactive (codex exec) mode inside CI pipelines or scripts to automate routine maintenance tasks, config updates, or log-driven triage, gated by approval policies.

Project Managers — use Codex to quickly generate summaries of a codebase's structure or recent changes, lowering the barrier to understanding technical progress without reading raw diffs.

6. Getting Started

Find what you need

Browse the repository and documentation: github.com/openai/codex
Search existing issues and discussions before filing a new one

Install / integrate

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

# via npm
npm install -g @openai/codex

# via Homebrew
brew install --cask codex

# start a session in your project
codex

Contribute

git clone https://github.com/openai/codex.git
cd codex/codex-rs
cargo build

See the repository's contributing guide for coding standards and the pull request process.

7. Project Structure

codex/
├── codex-cli/    # CLI wrapper and npm packaging
├── codex-rs/     # Rust implementation of the agent engine
├── sdk/          # SDK for embedding Codex in other tools
├── docs/         # User and developer documentation
└── tools/        # Utility and release scripts

codex-rs/ contains the core agent loop, sandboxing logic, and model-interaction code — most engineering contributions land here.
codex-cli/ packages the compiled binary for distribution via npm.
docs/ holds configuration, sandboxing, and usage guides referenced throughout this document.

8. Related Ecosystem

ChatGPT plans (Plus, Pro, Business, Edu, Enterprise) — provide authentication and usage entitlement for Codex without a separate API key.
OpenAI API — an alternative authentication path for users who prefer key-based billing.
Model Context Protocol (MCP) — the open protocol Codex uses to connect to external tools and data sources.
IDE integrations — VS Code, Cursor, and Windsurf extensions that embed the same agent inside an editor.

9. License

Codex is released under the Apache-2.0 license.

✅ Free to use, modify, and distribute, including for commercial purposes
✅ Patent grant included, covering contributions from the project
❌ No warranty is provided; use is at your own risk
ℹ️ Modified versions must retain the original license and copyright notices, and state significant changes

10. FAQ

Q: Do I need an API key to use Codex?
A: No — you can sign in with an existing ChatGPT Plus, Pro, Business, Edu, or Enterprise plan, or use an API key if you prefer.

Q: Can Codex modify my files without asking?
A: Only if you configure it to. Sandbox and approval settings range from read-only to full-auto, so you control how much autonomy the agent has.

Q: Which platforms are supported?
A: macOS, Linux, and Windows, via prebuilt binaries, npm, or Homebrew.

Q: How do I run Codex in a script or CI pipeline?
A: Use the non-interactive command, e.g. codex exec "run the test suite and summarize failures".

Q: How does Codex learn my project's conventions?
A: Add an AGENTS.md file to your repository describing commands, style, and context; Codex reads it automatically each session.

11. Quick Links

Repository: https://github.com/openai/codex
Documentation: https://github.com/openai/codex/tree/main/docs
Contributing guide: https://github.com/openai/codex/blob/main/docs/contributing.md
Discussions: https://github.com/openai/codex/discussions

12. Summary

Codex brings OpenAI's coding agent into any developer's terminal, IDE, or CI pipeline, with configurable sandboxing so teams can choose exactly how much autonomy to grant. It's a strong fit for developers who want AI-assisted coding without leaving their existing command-line workflow, and for teams that need to automate routine engineering tasks under clear, auditable safety controls.