Codex for software and platform teams

Codex is OpenAI's coding agent that runs on your machine. It is open source, reads your repository, makes changes and runs commands based on natural language prompts. The current CLI is designed for agentic coding: it plans multi-file changes, executes commands and verifies results. This post covers installation, interactive and headless workflows, the memory feature and considerations for choosing Codex.

What Codex is

Codex CLI launches an interactive terminal session where you can talk to the agent about your code. You can ask it to implement features, refactor modules, write tests or explain unfamiliar logic. It understands project structure, coordinates changes across multiple files, and can run shell commands such as builds, tests and linters, then react to the output and iterate. The agent runs locally, so your code stays in your environment unless you choose to share context. If you do not specify a model, Codex uses a recommended default. OpenAI currently recommends starting with its flagship model for most coding tasks, and it is available whether you sign in with a ChatGPT account or use API key authentication.

Installation

Codex is distributed via npm. Install it globally:

npm install -g @openai/codex

A Homebrew cask (brew install --cask codex) and an official install script are also available. After installing, run codex and sign in when prompted (you can also authenticate explicitly with codex login). You can sign in with your ChatGPT account, which gives access to the latest models, or supply an API key for CI automation. Configuration lives in ~/.codex/config.toml, where you set keys such as model, model_reasoning_effort, approval_policy and sandbox_mode. Codex also looks for AGENTS.md files in its home directory, the project root and the working directory to load project-specific instructions.

Interactive workflow

Running codex launches the interactive session. You describe what you want, and Codex plans the steps, shows proposed edits, runs tests and iterates until the goal is met. You can control the agent with slash commands, change models, and resume earlier sessions. In the Codex app you can also use Worktrees, which run multiple independent tasks in parallel git worktrees so they do not interfere with each other; you can hand a thread off between local and worktree execution.

Headless workflows with codex exec

For automation and CI, use the headless codex exec command (alias codex e). You pass a prompt and Codex runs the task and prints its output to stdout. Capture just the final message with --output-last-message, and emit newline-delimited JSON events with --json when you need to parse progress. You can integrate it into CI pipelines, git hooks or cron jobs. A simple one-shot looks like this, with a Python wrapper for scripts that already run in Python:

codex exec "Update the version number in package.json to 2.1.0"

import subprocess
subprocess.run(["codex", "exec", "Update the version number in package.json to 2.1.0"], check=True)

On GitHub Actions, the official Codex GitHub Action is the recommended path: it installs and authenticates Codex for you, with the API key supplied from a repository secret rather than exported as a job-level variable. The following is a GitHub Actions workflow file, not a shell command:

jobs:
  update_changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "Update CHANGELOG for the next release based on commits since the last tag"

Control autonomy with --sandbox (read-only, workspace-write or danger-full-access) and --ask-for-approval (untrusted, on-request or never). For batch work you can loop over files and run codex exec once per file.

Memory

Codex has an opt-in memory feature that stores generated facts, preferences and project context across sessions. Memories live under ~/.codex/memories/, and you control them with the /memories command in the Codex app and TUI. The feature is off by default; enable it by setting memories = true under the [features] table in config.toml. Memory works best for personal conventions such as "use pnpm instead of npm" or "the auth module is in src/core/auth/". For team-wide instructions, use AGENTS.md, which Codex loads automatically, rather than memory.

Strengths

• Local first. Codex runs on your machine and modifies your code directly, so you keep privacy and low latency.
• Flexible workflows. You can work in the interactive TUI or run tasks headless with codex exec, including JSON output for automation.
• Standing instructions. AGENTS.md and the opt-in memory feature let you encode conventions so you do not repeat yourself.
• Parallel work. The Worktrees feature lets Codex run independent tasks in isolated git worktrees.

Limits

Codex is still evolving, and some features may change. The CLI requires Node.js for the npm install, and running with full access can modify files or run commands you did not expect, so review diffs or use approval policies. Memory and AGENTS.md live locally and are not shared across machines unless you sync them yourself. While Codex is open source, using it with hosted models incurs subscription or API costs.

When to choose Codex

Choose Codex when you want a local coding agent that can run offline, integrate into CI/CD and be scripted. It suits teams that value reproducible automation and headless runs. If you rely heavily on GitHub services or want built-in cloud integration, GitHub Copilot may fit better. For an approve-before-edit plan step and rich permission modes, Claude Code is worth a look. Codex excels at flexible scripting and local control.