Advanced usage

Effective Codex work combines suitable permissions, project context, profiles, MCP and non-interactive execution. See Commands for a quick reference.

#AGENTS.md project instructions

Place AGENTS.md at the project root to explain conventions, similarly to Claude Code's CLAUDE.md.

# Project conventions

Stack: Python + FastAPI
Package manager: uv, not pip

## Commands
- Start: uv run uvicorn app:main
- Test: uv run pytest

## Style
- Include type annotations.
- Run pytest after changes.

#Advanced config.toml settings

Common settings, with the full setup in Configuration:

Override a setting for one run with -c key=value, for example codex -c model_reasoning_effort=high.

#Switch settings with profiles

Store scenario-specific settings in a profile and select it with --profile:

# Profile files use top-level keys.
model = "gpt-6-sol"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

codex --profile fast "Add tests for this module"

Old [profiles.fast] examples should be migrated to the separate file. Retired approval values such as on-failure/untrusted should not be copied into new configuration.

#Connect tools with MCP

MCP connects external tools and data such as browsers, databases and internal APIs. Define the server in config.toml:

[mcp_servers.my-tool]
command = "npx"
args = ["-y", "@scope/my-mcp-server"]
# env = { API_KEY = "..." }

Use /mcp to inspect connectivity and available tools.

#Non-interactive scripts and CI

codex exec completes a task without entering the interactive TUI:

# One task
codex exec "Fix lint failures and run the relevant tests"

# Explain a staged diff
git diff --staged | codex exec "Summarize these changes as a commit message"

Use explicit, limited permissions for unattended work, such as read-only or a specific writable workspace.

#Approvals and sandbox

Codex combines approval policy with the sandbox boundary:

--full-auto is deprecated. New scripts should use explicit --sandbox workspace-write --ask-for-approval on-request. -a and -s override approval and sandbox settings; -C sets the working directory.

#Common workflow

#Continue reading