`npm i -g @openai/codex`
or `brew install codex`
Codex CLI is a coding agent from OpenAI that runs locally on your computer.
If you are looking for the cloud-based agent from OpenAI, Codex Web, see chatgpt.com/codex.
Install globally with your preferred package manager. If you use npm:
npm install -g open-codexAlternatively, if you use Homebrew:
brew install codexThen simply run codex to get started:
open-codexCodex CLI is built for developers who already live in the terminal and want ChatGPT‑level reasoning plus the power to actually run code, manipulate files, and iterate – all under version control. In short, it's chat‑driven development that understands and executes your repo.
- Zero setup — bring your API key and it just works!
- Multiple AI providers — use OpenAI, Gemini, OpenRouter, or Ollama!
- Full auto-approval, while safe + secure by running network-disabled and directory-sandboxed
- Multimodal — pass in screenshots or diagrams to implement features ✨
And it's fully open-source so you can see and contribute to how it develops!
Codex lets you decide how much autonomy the agent receives and auto-approval policy via the
--approval-mode flag (or the interactive onboarding prompt):
| Mode | What the agent may do without asking | Still requires approval |
|---|---|---|
| Suggest (default) |
• Read any file in the repo | • All file writes/patches • All shell/Bash commands |
| Auto Edit | • Read and apply‑patch writes to files | • All shell/Bash commands |
| Full Auto | • Read/write files • Execute shell commands |
– |
In Full Auto every command is run network‑disabled and confined to the current working directory (plus temporary files) for defense‑in‑depth. Codex will also show a warning/confirmation if you start in auto‑edit or full‑auto while the directory is not tracked by Git, so you always have a safety net.
Coming soon: you'll be able to whitelist specific commands to auto‑execute with the network enabled, once we're confident in additional safeguards.
The hardening mechanism Codex uses depends on your OS:
-
macOS 12+ – commands are wrapped with Apple Seatbelt (
sandbox-exec).- Everything is placed in a read‑only jail except for a small set of
writable roots (
$PWD,$TMPDIR,~/.codex, etc.). - Outbound network is fully blocked by default – even if a child process
tries to
curlsomewhere it will fail.
- Everything is placed in a read‑only jail except for a small set of
writable roots (
-
Linux – there is no sandboxing by default. We recommend using Docker for sandboxing, where Codex launches itself inside a minimal container image and mounts your repo read/write at the same path. A custom
iptables/ipsetfirewall script denies all egress except the OpenAI API. This gives you deterministic, reproducible runs without needing root on the host. You can use therun_in_container.shscript to set up the sandbox.
| Requirement | Details |
|---|---|
| Operating systems | macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2 |
| Node.js | 22 or newer (LTS recommended) |
| Git (optional, recommended) | 2.23+ for built‑in PR helpers |
| RAM | 4‑GB minimum (8‑GB recommended) |
Never run
sudo npm install -g; fix npm permissions instead.
| Command | Purpose | Example |
|---|---|---|
open-codex |
Interactive REPL | codex |
open-codex "…" |
Initial prompt for interactive REPL | codex "fix lint errors" |
open-codex -q "…" |
Non-interactive "quiet mode" | codex -q --json "explain utils.ts" |
open-codex completion <bash|zsh|fish> |
Print shell completion script | codex completion bash |
Key flags: --model/-m, --approval-mode/-a, and --quiet/-q.
Codex merges Markdown instructions in this order:
~/.codex/instructions.md– personal global guidancecodex.mdat repo root – shared project notescodex.mdin cwd – sub‑package specifics
Disable with --no-project-doc or CODEX_DISABLE_PROJECT_DOC=1.
Run Codex head‑less in pipelines. Example GitHub Action step:
- name: Update changelog via Codex
run: |
npm install -g open-codex
export OPENAI_API_KEY="${{ secrets.OPENAI_KEY }}"
open-codex -a auto-edit --quiet "update CHANGELOG for next release"Set CODEX_QUIET_MODE=1 to silence interactive UI noise.
Setting the environment variable DEBUG=true prints full API request and response details:
DEBUG=true open-codexBelow are a few bite‑size examples you can copy‑paste. Replace the text in quotes with your own task. See the prompting guide for more tips and usage patterns.
| ✨ | What you type | What happens |
|---|---|---|
| 1 | codex "Refactor the Dashboard component to React Hooks" |
Codex rewrites the class component, runs npm test, and shows the diff. |
| 2 | codex "Generate SQL migrations for adding a users table" |
Infers your ORM, creates migration files, and runs them in a sandboxed DB. |
| 3 | codex "Write unit tests for utils/date.ts" |
Generates tests, executes them, and iterates until they pass. |
| 4 | codex "Bulk‑rename *.jpeg → *.jpg with git mv" |
Safely renames files and updates imports/usages. |
| 5 | codex "Explain what this regex does: ^(?=.*[A-Z]).{8,}$" |
Outputs a step‑by‑step human explanation. |
| 6 | codex "Carefully review this repo, and propose 3 high impact well-scoped PRs" |
Suggests impactful PRs in the current codebase. |
| 7 | codex "Look for vulnerabilities and create a security review report" |
Finds and explains security bugs. |
From npm (Recommended)
npm install -g open-codex
# or
yarn global add open-codexYou can also go to the latest GitHub Release and download the appropriate binary for your platform.
Each GitHub Release contains many executables, but in practice, you likely want one of these:
- macOS
- Apple Silicon/arm64:
codex-aarch64-apple-darwin.tar.gz - x86_64 (older Mac hardware):
codex-x86_64-apple-darwin.tar.gz
- Apple Silicon/arm64:
- Linux
- x86_64:
codex-x86_64-unknown-linux-musl.tar.gz - arm64:
codex-aarch64-unknown-linux-musl.tar.gz
- x86_64:
Each archive contains a single entry with the platform baked into the name (e.g., codex-x86_64-unknown-linux-musl), so you likely want to rename it to codex after extracting it.
Run codex and select Sign in with ChatGPT. We recommend signing into your ChatGPT account to use Codex as part of your Plus, Pro, Team, Edu, or Enterprise plan. Learn more about what's included in your ChatGPT plan.
You can also use Codex with an API key, but this requires additional setup. If you previously used an API key for usage-based billing, see the migration steps. If you're having trouble with login, please comment on this issue.
Codex CLI supports MCP servers. Enable by adding an mcp_servers section to your ~/.codex/config.toml.
Codex CLI supports a rich set of configuration options, with preferences stored in ~/.codex/config.toml. For full configuration options, see Configuration.
- Getting started
- Sandbox & approvals
- Authentication
- Advanced
- Zero data retention (ZDR)
- Contributing
- Install & build
- FAQ
- Open source fund
This repository is licensed under the Apache-2.0 License.