OpenAI Codex CLI Integration

Delegate coding tasks to OpenAI's Codex CLI with flexible cost control.

Quick Start

Usage: /codex [preset] [task] or /codex [task] (will ask for preferences)

Presets (Cost-Optimized Shortcuts)

All presets use workspace-write sandbox and --full-auto mode.

Preset Commands

# turbo — fast, light reasoning
codex --search exec -m gpt-5.5 -c model_reasoning_effort="low" --full-auto "$ARGUMENTS"

# balanced — good default
codex --search exec -m gpt-5.5 -c model_reasoning_effort="medium" --full-auto "$ARGUMENTS"

# quality — deep analysis
codex --search exec -m gpt-5.5 -c model_reasoning_effort="high" --full-auto "$ARGUMENTS"

# max — highest capability
codex --search exec -m gpt-5.5 -c model_reasoning_effort="xhigh" --full-auto "$ARGUMENTS"

Note: --full-auto sets --sandbox workspace-write and runs without interactive approval prompts in exec mode. Global flags like --search must come before exec.

Custom Configuration (When No Preset Given)

If user doesn't specify a preset, ASK them to choose:

1. Model Selection

Tip: Run /model list during interactive sessions to see all available models.

2. Reasoning Effort

All current models default to medium. Supported levels vary by model.

Note: All currently listed models (gpt-5.2 through gpt-5.5) support low|medium|high|xhigh with default medium. The minimal effort is no longer offered by any visible Codex CLI model — drop it from automation that targeted gpt-5.

3. Sandbox Mode

Custom Command Template

When using a sandbox other than workspace-write, use explicit flags instead of --full-auto:

codex -a on-request exec \
  -m {model} \
  -c model_reasoning_effort="{effort}" \
  -s {sandbox} \
  "{task}"

Note: -a (approval policy) is a global flag and must come before exec. -s (sandbox) and -m (model) work on both global and exec level.

For workspace-write with auto-approval, use --full-auto:

codex --search exec \
  -m {model} \
  -c model_reasoning_effort="{effort}" \
  --full-auto \
  "{task}"

CLI Commands Reference

Core Commands

Cloud Tasks (Experimental)

codex cloud exec --env <ENV_ID> "task"    # Submit cloud task
codex cloud status <TASK_ID>              # Check task status
codex cloud list                          # List cloud tasks
codex cloud apply <TASK_ID>               # Apply diff locally
codex cloud diff <TASK_ID>                # View unified diff

MCP Servers (Model Context Protocol)

MCP lets Codex connect to external tools and services — Notion, Figma, databases, docs, browsers, and more.

Configuration

MCP config lives in ~/.codex/config.toml (global) or .codex/config.toml (project-scoped, trusted projects only).

Adding Servers

Via CLI:

# STDIO server (local process)
codex mcp add <server-name> --env VAR1=VALUE1 -- <command>

# HTTP server (remote)
codex mcp add <server-name> --url https://example.com/mcp

# With bearer token
codex mcp add <server-name> --url https://example.com/mcp --bearer-token-env-var MY_TOKEN

Via config.toml directly:

# STDIO server example
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

[mcp_servers.context7.env]
MY_ENV_VAR = "value"

# HTTP server example
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

# Advanced HTTP with tool filtering
[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
startup_timeout_sec = 20
tool_timeout_sec = 60

MCP Server Management Commands

codex mcp list              # List all configured servers
codex mcp list --json       # Machine-readable output
codex mcp get <name>        # Show specific server config
codex mcp get <name> --json # Machine-readable server config
codex mcp login <name>      # OAuth login for HTTP servers
codex mcp login <name> --scopes "scope1,scope2"  # With specific scopes
codex mcp logout <name>     # Remove OAuth credentials
codex mcp remove <name>     # Delete a server

Using Notion via MCP

Before first use, run this once to authenticate:

codex mcp login notion

This opens a browser — authorize Codex to access your Notion workspace. Only needed once (credentials are cached).

Config (add to ~/.codex/config.toml):

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

Usage examples:

# Interactive
codex
> search my Notion for "project roadmap"
> create a new page in my Tasks database

# Non-interactive
codex exec -m gpt-5.5 --full-auto "list my recent Notion pages"
codex exec -m gpt-5.5 --full-auto "create a meeting notes page in Notion for today"

If Notion tools aren't working:

codex mcp list              # Check if notion is listed and connected
codex mcp login notion      # Re-authenticate if needed
/mcp                        # In interactive mode — verify notion tools are active

Config Options Reference