Codex CLI

OpenAI develops LLMs used across a wide range of applications. With the Codex CLI, you get a terminal-native coding assistant that can help supercharge your development workflows. In this topic, we will walk through how to set it up and use it in your development tasks.

Installation

You can access Codex through the web, the command line (CLI), IDE extensions, or the Codex desktop app. If you don't want to install anything, just open Codex Web and connect your GitHub repository. To install Codex for the CLI, you can use package managers like Homebrew and npm:

npm i -g @openai/codex

brew install codex

Once you finish installing Codex, you can use the codex command from anywhere on your system. On macOS and Linux, you also need to set up a sandboxing layer. This sandbox keeps Codex isolated, preventing it from accessing files outside its environment. On macOS, Apple Seatbelt handles this, and on Linux, you use bubblewrap (bwrap). If you are on Windows, Windows process isolation manages sandboxing, or you can use WSL.

If you use IDEs like VS Code or Cursor, you can add Codex through an extension. This extension gives you a chat sidebar where you can ask Codex to perform tasks, review code changes, and accept or reject file updates.

For JetBrains IDEs, Codex integrates with the JetBrains AI Assistant and is available as an Agent mode alongside Junie and Claude Agent:

When you select Codex for the first time, the system will prompt you to install the extension. After installation, you can start using Codex in your JetBrains IDEs right away.

Configuration

When you run Codex for the first time, you need to authenticate. You can use your ChatGPT subscription, and your usage will count toward your ChatGPT Plus, Pro, or Team plan. If you have API credits, you can use an API key instead. For JetBrains IDEs, Codex is also available as part of your JetBrains AI subscription.

Codex uses TOML files for configuration. Settings load as follows, in order of precedence:

• CLI flags: these always take the highest precedence.

• Project config: .codex/config.toml at the root of your repository. Here, we have team or project-specific overrides.

• Global config: ~/.codex/config.toml — your user defaults.

This setup lets your team add a .codex/config.toml file to version control so everyone uses the same settings. At the same time, each person can still adjust their own global settings if needed.

Your config.toml file can include many different options. Here are some of the main settings you might use:

# Default model for all sessions
model = "gpt-5.4-mini"

personality = "friendly" # none | friendly | pragmatic

# Controls how much "thinking" the model does:
# minimal | low | medium | high | xhigh
model_reasoning_effort = "medium"

# when to ask before running commands
# untrusted | on-request | never
approval_policy = "on-request" 

# isolation level for command execution
# read-only | workspace-write | danger-full-access (no sandbox here, very risky)
sandbox_mode = "read-only"

# use a different base URL; typically if using a proxy
openai_base_url = "https://int.hyperskill.org/openai/v1"

# allow Codex to query the web for up-to-date information
websearch = "live" # disabled | cached | live

[history]
persistence = "save-all" # save-all | none

# subagents — discussed later
[agents.database_migrator]
description = "Perform database migrations"
config_file = "./agents/database_migrator.toml"  # relative to the config.toml that defines it

Using profiles, you can quickly switch between different configurations based on the task you're working on.

[profiles.review]
model = "gpt-5.4"
approval_policy = "read-only"

[profiles.refactor]
model = "gpt-5.4-nano"
approval_policy = "on-request"

To use a specific profile, just run codex --profile refactor. You can also connect Codex to external MCP servers by adding them to your config.toml file:

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp"]

After you connect these tools, Codex can automatically use them whenever needed.

Working with Codex

How you develop with Codex primarily depends on how you installed it and your personal preferences. The CLI gives you the most detailed control over configuration, sandboxing, and scripting. If you use the web app, you get a cloud-based environment. In VS Code and Cursor, you have an integrated panel in the editor; in JetBrains IDEs, you work from the AI Chat window.

If you use the CLI, start by typing codex in your project directory without any arguments. This opens an interactive terminal UI. Here, you can type prompts in natural language, and Codex will work on your requests. You'll see changes in a diff view and can approve or reject them as needed. The terminal UI keeps a conversation history for your session, so you can ask Codex to adjust its approach, add tests, debug, and more.

Inside the terminal UI, you can use slash commands to perform common tasks:

• / — list all available commands.

• /model — switch models mid-session.

• /approvals — change the approval policy on the fly.

• /agent — switch between agent threads.

• /mcp — interact with connected MCP servers.

• /compact — summarize the conversation.

• /diff — view pending changes.

• /review — perform code review using preset prompts.

Codex automatically reads your project's file tree. If you want Codex to focus on certain files or folders, you can mention specific paths in your prompts using @file_path. You can also give Codex image inputs, such as when you want to write code based on a design:

codex --image wireframe.png "Let's build this."

Within the sandbox, Codex can create, edit, and delete files. You'll always see each proposed change before it applies, based on your approval policy:

The working directory is important. Codex operates relative to where you start it. If you run codex from a subdirectory in a monorepo, it will only work with that package.

If you want to experiment without affecting your main branch, Codex supports Git worktrees. You can point Codex at a separate branch so that it makes any changes there rather than in your main working copy. This way, you can test new ideas and keep your main branch clean.

Subagents

Subagents are specialized versions of the Codex agent that focus on a specific domain or task. Rather than having a single agent handle everything, you can define focused helpers, each with its own instructions, model, and approval policy. To define agents, add them as .toml files in ~/.codex/agents/ or .codex/agents/ directories. Codex defines global settings in your global or project config.toml files under an [agents] section.

Your agent definition must include:

• name

• description

• developer_instructions

If you leave out settings such as the model, Codex will use the values from your base configuration for that session. Here's what an agent definition looks like (.codex/agents/database_migrator.toml):

name = "database_migrator"
model = "gpt-5.4"
approval_policy = "on-request"
description = "Database migration specialist. "
developer_instructions = "Use Alembic conventions. Never drop columns without explicit confirmation."

Subagents help Codex focus on a specific role while still understanding your project. To set project conventions like coding standards, test frameworks, or architectural patterns, use an AGENTS.md file. You can place this file at the root of your repository or in subdirectories to control its scope. You can also reuse instructions from other tools, such as Junie or Claude Code.

Non-interactive mode

Up to this point, we have used Codex as a conversation partner. In some cases, though, we want Codex to run tasks automatically without our input. This is useful for scripting and automation, such as automated code review, documentation updates, linting, changelog updates, and other DevOps tasks on every push. In these situations, you can use the codex exec command:

$ codex exec "Refactor the auth module to use JWT tokens instead of session cookies."

In this mode, Codex reads your prompt, completes the task, and then exits. How you provide your OpenAI API key depends on your environment. For GitHub Actions, you can use the dedicated Codex action:

- name: Run Codex 
  id: run_codex
  uses: openai/codex-action@v1
  with:
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}
    prompt: |
      Review this pull request for correctness, security, and test coverage gaps.
      Return:
      - brief summary
      - prioritized findings with severity
      - concrete fix suggestions
    output-file: codex-output.md
    sandbox: workspace-write
    safety-strategy: drop-sudo

As an MCP server, Codex can also be called programmatically by other tools and agents.

Conclusion

In this topic, we introduced you to Codex CLI, a coding assistant that works right in your terminal. We covered the first steps, from installing Codex to configuring it with .toml files. You learned how Codex works and how to extend its capabilities with subagents. We also looked at how to use Codex in non-interactive mode for automation. By mastering these configurations, you can adapt Codex to fit different codebases, workflows, and CI/CD pipelines.