codex-cli-best-practice

-white?style=flat&labelColor=555)

= Agents · = Commands · = Skills

🧠 CONCEPTS

| Feature | Location | Description | |---------|----------|-------------| | Commands | interactive session / slash popup | Built-in slash commands for session control — examples include /plan, /fast, /fork, /review, /status, /mcp, /agent, /apps, /model, and /permissions | | Subagents | .codex/agents/<name>.toml | Custom agents registered under [agents.<name>] with dedicated TOML role configs, parallel subagent orchestration, and CSV batch processing · Global settings live under [agents] (maxthreads, maxdepth, jobmaxruntime_seconds) · Built-in: default, worker, explorer | | Skills | .agents/skills/<name>/SKILL.md | Reference Reusable instruction packages with required name + description metadata and progressive disclosure via scripts/, references/, assets/, and optional agents/openai.yaml · Invoke explicitly via /skills or $skill-name, or implicitly by description match · Built-in examples: $plan, $skill-creator, $skill-installer · Distributed via Plugins | | Plugins | .codex-plugin/plugin.json | Distributable bundles combining skills + app integrations + MCP servers — local/personal marketplace system · Built-in: $plugin-creator · Browse via /plugins or Codex App | | Marketplace | $CODEXHOME → [marketplaces.*] | Plugin catalog system (v0.121.0+) — codex plugin marketplace add\|upgrade\|remove accepts GitHub shorthand, git URLs, and local directories · Manifest at .agents/plugins/marketplace.json · Browse installed marketplaces via /plugins tabs | | Memories | $CODEXHOME/memories/ | Cross-session memory pipeline (v0.119.0+) — enable via [features] memories = true and configure under [memories] · TUI control via /memories (use · generate · reset) · Per-thread toggle persists in state DB · Scope is per-user, not per-project | | Workflows | .codex/agents/weather-agent.toml | End-to-end usage patterns — explain codebase, fix bugs, write tests, prototype from screenshot, iterate UI, delegate to cloud, code review, update docs | | MCP Servers | config.toml → [mcpservers.*] | Model Context Protocol for external tools — STDIO + Streamable HTTP servers · OAuth support (codex mcp login) · Also acts as MCP server via codex mcp-server (exposes codex() + codex-reply() tools) · MCP Apps (v0.119.0+): resource reads, elicitations, file-parameter uploads · Parallel calls (v0.121.0+): supportsparalleltool_calls = true per server · CLI management: codex mcp add\|get\|list\|login\|logout\|remove | | Config | .codex/config.toml | TOML-based layered config system · Profiles · Sandbox · Approval Policy · Advanced ([features], [otel], [shellenvironmentpolicy], [tui], model providers, granular approvals) · Trust system for project configs · developerinstructions · modelinstructionsfile for custom system prompts | | Rules | .codex/rules/ | Starlark-based command execution policies via prefixrule() — allow, prompt, forbidden decisions with exact-prefix matching · Test via codex execpolicy check · Rules work alongside granular approval_policy controls and user-managed approvals | | AGENTS.md | AGENTS.md | Project-level context for Codex CLI — hierarchical discovery from cwd to repo root, capped at 32 KiB (projectdocmaxbytes) · AGENTS.override.md for personal overrides | | Hooks | .codex/hooks.json | User-defined shell scripts that inject into the agentic loop — logging, security scanning, validation, and custom automation · Requires codex_hooks = true feature flag | | Speed | config.toml → servicetier | Fast Mode (1.5x speed, 2x credits) on gpt-5.4 — toggle with /fast on\|off\|status · GPT-5.3-Codex-Spark for near-instant iteration (Pro subscribers) | | Code Review | /review | Review branches, uncommitted changes, or specific commits — configurable reviewmodel in config.toml · Custom review instructions | | Sessions | $CODEXHOME/sessions/ · /archive | Session lifecycle management — resume or fork prior threads · archive via /archive (TUI) or codex archive / codex unarchive (CLI); archived threads are protected from resume/fork until restored (v0.137.0+) · search local conversation history with case-insensitive content matches + result previews (v0.135.0+) | | AI Terms | | Agentic Engineering · Context Engineering · Vibe Coding | | Best Practices | | Official best practices · Prompt Engineering · Codex Guides |

See orchestration-workflow for implementation details of Agent → Skill pattern. The agent fetches temperature from Open-Meteo and invokes the SVG creator skill.

codex
> Fetch the current weather for Dubai in Celsius and create the SVG weather card output using the repo.

Note: This workflow is not 100% in sync with the Claude Code Best Practice orchestration workflow. Codex CLI does not yet support custom commands (.codex/commands/), so the full Command → Agent → Skill pattern is not possible. There is an experimental tool/requestUserInput in the Codex App Server docs and an internal requestuser_input capability gated behind an under-development feature flag in codex-cli 0.115.0, but neither is publicly available yet.

⚙️ DEVELOPMENT WORKFLOWS

All major workflows converge on the same architectural pattern: Research → Plan → Execute → Review → Ship

| Name | ★ | Workflow | | | |------|---|----------|---|---| | Superpowers | 218k | → → → → → | 5 | 14 | | Spec Kit | 108k | → → → → | 0 | 0 | | gstack | 107k | → → → → → → → → | 0 | 41 | | Get Shit Done | 64k | → → → → → → | 33 | 0 | | oh-my-codex | 30k | → → | 19 | 36 | | Compound Engineering | 20k | → → → → → → | 49 | 42 |

Note: yellow tags are sub-loops — steps that repeat inside a parent step (e.g. per task, per story, or until a verify condition passes).

Others

• Cross-Model (Claude Code + Codex) Workflow

💡 TIPS AND TRICKS (50)

Prompting · Planning · AGENTS.md · Agents · Skills · Hooks · Memories · Workflows · Advanced · Git / PR · Debugging · Utilities · Daily

■ Prompting (3)

| Tip | |-----| | challenge Codex — "prove to me this works" and have Codex diff between main and your branch | | after a mediocre fix — "knowing everything you know now, scrap this and implement the elegant solution" | | Codex fixes most bugs by itself — paste the bug, say "fix", don't micromanage how |

■ Planning (4)

| Tip | |-----| | use /plan when you want an explicit plan — Codex may also plan automatically for multi-step tasks | | always make a phase-wise gated plan, with each phase having multiple tests (unit, automation, integration) | | spin up a second Codex (or use cross-model) to review your plan as a staff engineer | | write detailed specs and reduce ambiguity before handing work off — the more specific you are, the better the output |

■ AGENTS.md (5)

| Tip | |-----| | keep AGENTS.md concise — 150 lines is a useful heuristic, but the actual limit is byte-based (32 KiB) | | use AGENTS.override.md for personal preferences without affecting the team | | any developer should be able to launch Codex, say "run the tests" and it works on the first try — if it doesn't, your AGENTS.md is missing essential setup/build/test commands | | keep codebases clean and finish migrations — partially migrated frameworks confuse models that might pick the wrong pattern | | use config.toml for harness-enforced behavior (approval policy, sandbox, model) — don't put behavioral rules in AGENTS.md when config.toml settings are deterministic |

Agents (3)

| Tip | |-----| | have feature specific sub-agents with skills instead of general qa, backend engineer | | use multi-agent to throw more compute at a problem — offload tasks to keep your main context clean and focused | | use test time compute — separate context windows make results better; one agent can cause bugs and another can find them |

Skills (7)

| Tip | |-----| | use skills with clear name and description frontmatter for auto-discovery | | skills are folders, not files — use references/, scripts/, examples/ subdirectories for progressive disclosure | | build a Gotchas section in every skill — highest-signal content, add Codex's failure points over time | | skill description field is a trigger, not a summary — write it for the model ("when should I fire?") | | don't state the obvious in skills — focus on what pushes Codex out of its default behavior | | don't railroad Codex in skills — give goals and constraints, not prescriptive step-by-step instructions | | use the built-in skill creator to scaffold new skills, and document one invocation style consistently across the repo |

■ Hooks (3)

| Tip | |-----| | use hooks for logging, security scanning, and validation — requires codexhooks = true feature flag | | use hooks for auto-formatting code — Codex generates well-formatted code, the hook handles the last 10% to avoid CI failures | | branch SessionStart on source (startup \| resume \| clear) — skip heavy context on clear so /clear stays snappy (v0.120.0+) |

■ Memories (2)

| Tip | |-----| | enable memories once and forget about it — consolidation runs between sessions, not mid-turn | | set nomemoriesifmcporwebsearch = true for threads that touch secrets or untrusted content — reset via /memories → Reset if exposure happens |

■ Workflows (4)

| Tip | |-----| | vanilla Codex is better than any workflows with smaller tasks | | use profiles to switch between project-defined safety levels — in this repo, conservative and trusted are examples | | start with on-request approval policy — only escalate to never when confident | | use /fork in-session (or codex fork) to explore alternatives without losing your current thread, and /resume (or codex resume) to pick up where you left off |

■ Workflows Advanced (5)

| Tip | |-----| | use multi-agent to spawn sub-agents for parallel fan-out work (GA — enabled by default) | | use codex exec for headless/CI pipelines | | combine sandbox modes with approval policies — workspace-write + on-request is a good default | | git worktrees for parallel development | | use ASCII diagrams a lot to understand your architecture |

■ Git / PR (3)

| Tip | Source | |-----|--------| | keep PRs small and focused — one feature per PR, easier to review and revert | | | always squash merge PRs — clean linear history, one commit per feature, easy git revert and git bisect | | | commit often — as soon as a task is completed, commit | |

■ Debugging (5)

| Tip | Source | |-----|--------| | always ask Codex to run the terminal (you want to see logs of) as a background task for better debugging | | | use MCP (Chrome DevTools, Playwright) to let Codex see browser console logs on its own | | | make it a habit to take screenshots and share with Codex whenever you are stuck with any issue | | | use a different model for QA — e.g. Claude Code for plan and implementation review | | | agentic search (glob + grep) beats RAG — code drifts out of sync and permissions are complex | |

■ Utilities (4)

| Tip | Source | |-----|--------| | iTerm/Ghostty/tmux terminals instead of IDE (VS Code/Cursor) | | | Wispr Flow for voice prompting (10x productivity) | | | codex-cli-hooks for Codex feedback | | | explore config.toml features like profiles, sandbox modes, and MCP for a personalized experience | |

■ Daily (2)

| Tip | Source | |-----|--------| | update Codex CLI daily | | | start your day by reading the changelog | |

| Article / Tweet | Source | |-----------------|--------| | How Codex is built — 90% self-built in Rust (Tibo, Pragmatic Engineer) \| 17 Feb 2026 | | | Skills in Codex — standardizing .agents/skills across agents (Embiricos) \| Feb 2026 | | | Unrolling the Codex agent loop — how Codex works internally (Bolin) \| Jan 2026 | Tweet | | AMA with Codex team — CLI, sandbox, agents (Embiricos, Fouad, Tibo + team) \| May 2025 | Reddit | | Codex CLI — open-source local coding agent, first look (Fouad + Romain) \| Apr 2025 | Tweet |

🎬 VIDEOS / PODCASTS

| Video / Podcast | Source | Link | |-----------------|--------|------| | The power user's guide to Codex — parallelizing workflows, planning, context engineering (Embiricos) \| 2026 \| How I AI | | Podcast | | Scaffolding is coping not scaling, and other lessons from Codex (Tibo) \| 2026 \| Dev Interrupted | | Podcast | | How Codex team uses their coding agent (Tibo + Andrew) \| 18 Feb 2026 \| Every | | Podcast | | Dogfood — Codex team uses Codex to build Codex (Tibo) \| 24 Feb 2026 \| Stack Overflow | | Podcast | | Why humans are AI's biggest bottleneck — Codex product vision (Embiricos) \| Feb 2026 \| Lenny's Podcast | | Podcast | | OpenAI and Codex (Tibo + Ed Bayes) \| 29 Jan 2026 \| Software Engineering Daily | | Podcast |

🔔 SUBSCRIBE

| Source | Name | Badge | |--------|------|-------| | | r/ChatGPT, r/OpenAI, r/Codex | | | | OpenAI, OpenAI Devs, Tibo, Embiricos, Jason, Romain, Dominik, Fouad, Bolin | | | | Jesse Kriss (Superpowers), Garry Tan (gstack), Kieran Klaassen (Compound Eng), Lex Christopherson (GSD), Yeachan Heo (oh-my-codex), Andrej Karpathy | | | | OpenAI | | | | Lenny's Podcast, The Pragmatic Engineer | |

Other Repos

codex-cli-hooks · claude-code-best-practice · claude-code-hooks

Sponsor My Work

If you like my work, buy me a doodh patti 🍵 on

Polar