Codex CLI Best Practice
practice makes codex perfect
Ask AI about Codex CLI Best Practice
Powered by Claude Β· Grounded in docs
I know everything about Codex CLI Best Practice. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
codex-cli-best-practice
from vibe coding to agentic engineering - practice makes codex perfect
= Agents Β·
= Commands Β·
= Skills
π§ CONCEPTS
| Feature | Location | Description |
|---|---|---|
interactive session / slash popup | Built-in slash commands for session control β examples include /plan, /fast, /fork, /review, /status, /mcp, /agent, /apps, /model, and /permissions | |
.codex/agents/<name>.toml | [agents.<name>] with dedicated TOML role configs, parallel subagent orchestration, and CSV batch processing Β· Global settings live under [agents] (max_threads, max_depth, job_max_runtime_seconds) Β· Built-in: default, worker, explorer | |
.agents/skills/<name>/SKILL.md | 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 | $CODEX_HOME β [marketplaces.*] | 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 | $CODEX_HOME/memories/ | [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 | |
| MCP Servers | config.toml β [mcp_servers.*] | 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+): supports_parallel_tool_calls = true per server Β· CLI management: codex mcp add|get|list|login|logout|remove |
| Config | .codex/config.toml | [features], [otel], [shell_environment_policy], [tui], model providers, granular approvals) Β· Trust system for project configs Β· developer_instructions Β· model_instructions_file for custom system prompts |
| Rules | .codex/rules/ | Starlark-based command execution policies via prefix_rule() β 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_doc_max_bytes) Β· AGENTS.override.md for personal overrides |
| Hooks | .codex/hooks.json | codex_hooks = true feature flag |
| Speed | config.toml β service_tier | 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 review_model in config.toml Β· Custom review instructions |
| AI Terms | ||
| 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 fullCommand β
Agent β
Skill pattern is not possible. There is an experimental
tool/requestUserInputin the Codex App Server docs and an internalrequest_user_inputcapability 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 | 171k | 5 | 14 | |
| Spec Kit | 92k | 0 | 0 | |
| gstack | 86k | 0 | 41 | |
| Get Shit Done | 58k | 33 | 0 | |
| oh-my-codex | 27k | 19 | 36 | |
| Compound Engineering | 16k | 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
π‘ TIPS AND TRICKS (50)
Prompting Β· Planning Β· AGENTS.md Β· Agents Β· Skills Β· Hooks Β· Memories Β· Workflows Β· Advanced Β· Git / PR Β· Debugging Β· Utilities Β· Daily
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| Tip |
|---|
| use hooks for logging, security scanning, and validation β requires codex_hooks = 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+) |
| Tip |
|---|
| enable memories once and forget about it β consolidation runs between sessions, not mid-turn |
set no_memories_if_mcp_or_web_search = true for threads that touch secrets or untrusted content β reset via /memories β Reset if exposure happens |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 | |
| 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
