codex-cli-best-practice

from vibe coding to agentic engineering - practice makes codex perfect

= 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] (max_threads, max_depth, job_max_runtime_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	$CODEX_HOME → [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	$CODEX_HOME/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 → [mcp_servers.*]	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+): supports_parallel_tool_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], [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-level context for Codex CLI — hierarchical discovery from cwd to repo root, capped at 32 KiB (project_doc_max_bytes) · 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 → 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		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 request_user_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	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

• 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 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+)

■ Memories (2)

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

■ 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