Guide

How to set up OpenAI's Codex CLI

Andrew Mercer June 15, 2026 · 5 min read

Codex is OpenAI's open-source terminal coding agent. It lives in your shell, reads your repo, edits files, and runs commands — the same shape as Claude Code or the Cursor CLI, just from a different vendor. If you already run one agent and want a second opinion in another tab, or you have a ChatGPT plan and want to use it for code, getting Codex installed takes about two minutes.

The setup has four moving parts: install the binary, authenticate, run it once to confirm it works, and — the part most people skip — configure its notify hook so it can ping you when a long task finishes instead of leaving you staring at a spinner.

Install, authenticate one of two ways, run it once, then wire up notify so it can tell you when it's done.

Install the CLI

Codex ships as an npm package. The global install is straightforward:

npm install -g @openai/codex

That gives you a codex command on your PATH. Confirm it landed with codex --version. A few notes before you run it:

Node version: you'll want a current LTS release of Node (18+). If codex errors on launch, an outdated Node is the usual cause.
Homebrew alternative: on macOS you can install it as a cask with brew install --cask codex instead of via npm. Package and command names move occasionally, so check the official docs for the current command rather than trusting a copy-pasted snippet from a forum.
"command not found": if your shell can't see codex after install, your npm global bin directory isn't on PATH. Run npm prefix -g, then add that /bin to your shell profile.

Authenticate: ChatGPT or API key

Codex has two sign-in paths, and which one you pick affects how you're billed.

Sign in with ChatGPT — run codex (or codex login) and choose the ChatGPT option. It opens a browser, you log in, and an access token is handed back to the CLI. This uses your existing plan's included credits, so it's the easiest path if you already pay for ChatGPT.
API key — authenticate with an OpenAI API key instead, which bills at standard API rates. This is the right choice for CI jobs, scripts, or any non-interactive run where a browser flow isn't possible. The documented way to hand Codex your key is to pipe it into login, for example printenv OPENAI_API_KEY | codex login --with-api-key.

export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key

Either way, Codex caches your credentials locally at ~/.codex/auth.json (or your OS credential store). Treat that file like a password — never commit it, never paste it into a chat. The flow does change as the product evolves, so if the sign-in screen doesn't match what you expect, check the official docs for the current authentication steps.

First run

Drop into a project and start it:

cd ~/your-project
codex

Codex reads the directory it's launched in, so always start it from the repo root. On the first interactive run it'll ask how much autonomy you want to grant — whether it can run commands and edit files on its own, or has to ask first. Start conservative. Let it propose a small change, watch how it edits and what commands it wants to run, and loosen the leash once you trust its judgment. If you're new to working this way, our notes on build vs plan mode and what vibe coding actually is apply directly here, even though they're framed around other agents.

Wire up the notify hook

This is the step that turns Codex from "a thing you babysit" into "a thing that tells you when it's done." Codex can run an external program at the end of a turn via the notify key in ~/.codex/config.toml. Set it to a command array:

notify = ["python3", "/Users/you/.codex/notify.py"]

Codex invokes that program with a single JSON argument. The payload includes these fields:

type — the event, currently agent-turn-complete.
thread-id and turn-id — session and turn identifiers.
cwd — the working directory the turn ran in.
input-messages — the user messages that kicked off the turn.
last-assistant-message — the final text from the agent, ideal for a notification body.

Note the kebab-case field names (last-assistant-message, not last_assistant_message) — that trips people up. Your script can parse the JSON and fire a desktop notification, hit a webhook, or post to Slack. The notify external program is set at the user level in ~/.codex/config.toml; project-local config files don't override it, which is a sensible guardrail. Separately, the built-in tui.notifications setting handles in-terminal alerts — useful, but only if the terminal is actually visible. The external notify hook is the one that reaches you when it isn't.

This is the same pattern Claude Code exposes through its event hooks. If you've read our breakdown of Claude Code hooks, the mental model carries straight over: the agent emits an event, you turn that event into a signal you'll actually notice.

Where Backgrind fits

A notify hook is only half the answer — it gets the event out of Codex, but you still need somewhere for that event to land and a terminal you can glance at without alt-tabbing away from whatever you're doing. Backgrind is the always-on-top window that floats Codex (or Claude Code, or its own hosted agent) over any app, catches those agent-turn-complete events, and turns them into ambient toasts — so you can run an agent in the background and stop babysitting it. See the demo or read more on the homepage.