Configuration & Concepts

Customize Codex behavior, sandboxing, integrations, and agent workflows

Customization

Codex customization operates across several interconnected layers:

AGENTS.md

Persistent instructions embedded in repositories. Keep it concise — build/test commands, code review expectations, conventions. Supports hierarchy: global (~/.codex/AGENTS.md) for personal preferences, repo-specific for team standards.

Skills

Reusable workflows packaged as discoverable capabilities. Structure: SKILL.md (required), scripts/, references/, assets/. Store at user level ($HOME/.agents/skills) or repo level (.agents/skills).

Plugins

Installable bundles packaging skills, app integrations, and MCP server configuration.

Sandboxing

The sandbox lets Codex act autonomously without unrestricted machine access.

Permission modes

• read-only — File inspection only; editing and commands require approval
• workspace-write (default) — Read files, edit within workspace, run local commands
• danger-full-access — Full access without restrictions

Approval policies

• untrusted — Prompts before running non-trusted commands
• on-request — Works autonomously inside sandbox; asks before crossing boundaries
• never — No approval prompts

Configure via CLI /permissions command or config.toml.

Model Context Protocol

MCP connects models to tools and context. Use it to give Codex access to third-party documentation, or to let it interact with developer tools like your browser or Figma.

Codex supports MCP servers in both the CLI and the IDE extension.

Supported MCP features

STDIO servers

Servers that run as a local process (started by a command). Support environment variables.

Streamable HTTP servers

Servers accessed at an address. Support:

• Bearer token authentication
• OAuth authentication (run codex mcp login <server-name> for OAuth-supporting servers)

Connect Codex to an MCP server

Codex stores MCP configuration in config.toml alongside other settings. Default location: ~/.codex/config.toml. You can also scope MCP servers to a project with .codex/config.toml (trusted projects only).

The CLI and IDE extension share this configuration.

Configure with the CLI

Add an MCP server:

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Example (Context7):

codex mcp add context7 -- npx -y @upstash/context7-mcp

Run codex mcp --help for all available MCP commands. Use /mcp in the TUI to see active servers.

Configure with config.toml

Edit ~/.codex/config.toml for fine-grained control.

STDIO server options

Streamable HTTP server options

Other options

config.toml examples

STDIO server

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

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

HTTP server

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

OAuth configuration

mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

Advanced configuration

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

Useful MCP servers

• Context7 — Connect to up-to-date developer documentation (github.com/upstash/context7)
• Figma — Access your Figma designs (developers.figma.com)
• Playwright — Control and inspect a browser (npmjs.com/@playwright/mcp)
• Chrome DevTools — Control and inspect Chrome (github.com/ChromeDevTools/chrome-devtools-mcp)
• Sentry — Access Sentry logs (docs.sentry.io)
• GitHub — Manage pull requests, issues, etc. (github.com/github/github-mcp-server)

Subagents

Codex can run subagent workflows by spawning specialized agents in parallel and then collecting their results in one response.

Overview

Subagent workflows are enabled by default. They suit complex, highly parallel tasks like codebase exploration and multi-step feature planning. IDE Extension support coming soon.

Typical workflow

Codex orchestrates:

1. Agent spawning
2. Routing instructions to each agent
3. Result collection
4. Thread closure

Only spawns subagents when explicitly requested. Waits for all results before returning consolidated responses.

Example: PR review with parallel agents checking security, code quality, bugs, race conditions, test flakiness, and maintainability.

Managing subagents

• Use /agent CLI command to switch between active threads
• Direct Codex to steer, stop, or close subagents
• Approval requests surface from inactive threads with source labels

Built-in agents

Three default agents ship with Codex:

Custom agent configuration

Required fields

• name — agent identifier
• description — when Codex should use it
• developer_instructions — core behavioral guidelines

Optional fields

• nickname_candidates — display names (presentation-only)
• model — model override
• model_reasoning_effort — reasoning level
• sandbox_mode — sandbox configuration
• mcp_servers — MCP server access
• skills.config — skills configuration

Global settings ([agents] section)

[agents]
max_threads = 6          # concurrent open agent cap
max_depth = 1            # nesting depth
job_max_runtime_seconds = 300  # worker timeout for CSV jobs

Example: PR review pattern

Three specialized agents:

[agents.pr_explorer]
description = "Read-only mapping of changes"
sandbox_mode = "read-only"

[agents.reviewer]
description = "Correctness and security focus"
developer_instructions = "Focus on bugs, security issues, and race conditions"

[agents.docs_researcher]
description = "API verification against documentation"
mcp_servers = ["context7"]

Example: Frontend debugging pattern

[agents.code_mapper]
description = "Maps component tree and state flow"

[agents.browser_debugger]
description = "Inspects browser console and network"
mcp_servers = ["playwright"]

[agents.ui_fixer]
description = "Applies CSS and layout fixes"

CSV batch processing Experimental

The spawn_agents_on_csv tool processes repeated tasks at scale:

1. Reads CSV file
2. Spawns one worker per row
3. Waits for completion
4. Exports combined results

Parameters:

• csv_path — source file
• instruction — worker prompt template with {column_name} placeholders
• id_column — stable item identifiers
• output_schema — JSON object structure for results
• output_csv_path — output file path
• max_concurrency — parallel worker limit
• max_runtime_seconds — job timeout

Best Practices

Getting started with strong context

Treat Codex less like a one-off assistant and more like a teammate you configure over time. Effective prompts should include:

• Goal — what you want accomplished
• Context — relevant background information
• Constraints — boundaries and requirements
• Completion criteria — how to know the task is done

Choose reasoning levels based on task complexity:

Planning for difficult tasks

Three approaches for tackling complex work:

1. Plan mode — the easiest option, activated via /plan or Shift+Tab. Codex outlines steps before executing.
2. Interview mode — request Codex to interview you first, gathering requirements before proposing a solution.
3. PLANS.md templates — for advanced workflows, create structured planning documents that Codex follows step by step.

AGENTS.md for reusable guidance

AGENTS.md is an open-format README for agents that loads automatically when Codex starts in a repository. It should document:

• Repo layout and architecture
• Build and test commands
• Engineering conventions and style guidelines
• Constraints and things to avoid
• Completion verification steps

Configuration strategy

Store personal defaults in ~/.codex/config.toml and repo-specific settings in .codex/config.toml.

Start restrictive with permissions and loosen only when necessary. This protects against accidental destructive operations while you build trust with the tool.

Testing and review

Codex should create tests, run checks, confirm behavior, and review work. The /review command offers:

• PR-style reviews of staged changes
• Uncommitted change reviews
• Custom review instructions
• GitHub integration for automatic PR reviews

MCPs (Model Context Protocol)

Use MCPs when:

• Context lives outside the repo (databases, APIs, dashboards)
• Data changes frequently and needs live access
• Tools need integration with external services

Skills for repetitive work

Package instructions in SKILL.md files for recurring tasks:

• Log triage and analysis
• Release notes generation
• PR reviews and feedback

Store personal skills in $HOME/.agents/skills; team skills in .agents/skills within repos.

Automations for scheduled tasks

Use the Automations tab to schedule recurring work. Good candidates include:

• Commit summaries
• Bug scanning
• Release notes
• CI failure checks
• Standup summaries

Skills define the methodology; automations define the scheduling.

Session management

Keep one thread per coherent work unit. Useful slash commands for managing sessions:

Use subagents for bounded work like exploration or testing.

Common mistakes to avoid

• Embedding durable rules in prompts instead of AGENTS.md
• Not showing Codex how to run build/test commands
• Skipping planning on multi-step tasks
• Granting full permissions prematurely
• Running multiple threads on the same files without worktrees
• Automating before the manual workflow is reliable
• Over-monitoring instead of running tasks in parallel
• One thread per project (causes context bloat)