Mastering Codex: Essential Practices from OpenAI

01 Give the task full context

Codex is powerful enough to produce good results even with imperfect prompts, but in large or complex codebases providing sufficient task context is key. A good prompt should include four elements: the goal, relevant context (files, docs, errors referenced with @), constraints (standards, architecture, guidelines), and a completion marker (e.g., passing tests or bug resolution). Adjust inference strength based on task difficulty: low for simple tasks, medium‑high for complex debugging, highest for long, inference‑intensive jobs. Voice input can also be used to describe tasks quickly.

02 Plan complex tasks before execution

For ambiguous or hard‑to‑describe tasks, let Codex plan first. Three planning modes are offered: /plan (or Shift+Tab) – the simplest and most effective, where Codex gathers context, asks clarification questions, then creates a plan.

Interview mode – Codex asks the user questions to turn vague ideas into concrete requirements before coding.

Use a PLANS.md template for more elaborate multi‑step workflows.

03 Consolidate useful prompts into AGENTS.md

Once a prompt works reliably, store it in AGENTS.md instead of repeating it manually. This file acts as a README for AI agents, automatically loaded into context. It should cover repository structure, startup commands, build/test/lint commands, coding standards, PR requirements, constraints, and verification criteria. The CLI /init command can generate a starter AGENTS.md, which should then be edited to match team practices. Configuration hierarchy: global (~/.codex), repository‑level (.codex), and subdirectory‑level files, with more specific files taking precedence. Keep the file concise; when it grows, split sections into separate markdown files and reference them.

04 Keep behavior consistent through configuration

Configuration ensures stable Codex behavior across sessions and scenarios. Configurable items include default model, inference strength, sandbox mode, approval policy, and MCP settings. Personal defaults live in ~/.codex/config.toml; repository‑specific config resides in .codex/config.toml. Two key permission controls are approval mode (whether Codex needs confirmation before executing a command) and sandbox mode (which directories/files Codex can read/write). Start with strict permissions and relax them only after gaining confidence in the workflow.

05 Let Codex test and review its own code

Beyond making changes, Codex should be instructed to write or update tests, run test suites, perform linting, formatting, type checking, and verify that results meet the defined success criteria. Use the /review command for various review styles (PR‑style against a base branch, unstaged changes, specific commit, or custom directives). If a code_review.md file is referenced in AGENTS.md, Codex will follow those standards, enabling consistent review across repositories. OpenAI reports that 100% of its internal PRs are reviewed by Codex.

06 Connect external systems via MCP

When required context lies outside the codebase, use the Model Context Protocol (MCP) to link Codex with external tools and systems, avoiding repetitive copy‑paste of live data into prompts. MCP supports both STDIO and OAuth‑enabled HTTP servers. Configure MCP servers in the Codex app settings or add custom servers via codex mcp add. Integrate tools judiciously—start with a few that clearly reduce manual steps, then expand as needed.

07 Package reusable workflows as Skills

When a workflow becomes repeatable, encapsulate it in a SKILL.md file. Each skill should do one thing, start with 2‑3 concrete use cases, define clear inputs and outputs, and include trigger phrases users might say. Store personal skills in $HOME/.agents/skills and share team skills under .agents/skills in the repository. Skills are usable from the CLI, IDE plugins, and the Codex app.

08 Hand stable workflows to automation

Once a workflow is stable, schedule it for background execution via the Automation tab in the Codex app. Choose the project, prompt (or skill), frequency, and runtime environment. Suitable automation tasks include summarizing recent commits, scanning for potential bugs, drafting release notes, checking CI failures, generating daily stand‑up summaries, and running repeatable analysis pipelines. Distinguish between skill definition (what to do) and automation schedule (when to run).

09 Manage long‑running sessions

Codex sessions accumulate context, decisions, and actions, so managing them impacts quality. Use thread‑pinning and work‑tree creation features. Useful slash commands include: /experimental – toggle experimental features and write to config.toml. /resume – restore a saved conversation. /fork – create a new thread while preserving the original. /compact – generate a summary of early context for long threads. /agent – switch active agent when running multiple agents. /theme, /apps, /status – additional utilities.

Keep one thread per coherent work unit; only fork when the work truly diverges. Sub‑agents can handle bounded tasks (exploration, testing, classification) while the main agent focuses on the core problem.

10 Common pitfalls

New users often make mistakes such as embedding persistent rules directly in prompts instead of AGENTS.md or skills, neglecting to tell the agent how to run build and test commands, skipping the planning phase for multi‑step tasks, granting overly broad permissions too early, running parallel sessions without proper git work‑trees, automating unstable workflows, micromanaging the agent step‑by‑step, and using one thread per project rather than per task, which inflates context and degrades performance.

In summary, using Codex effectively is an engineering habit: provide ample context, codify standards in files, turn repetitive actions into tools, and hand stable tools to automation.