# codex-cli-best-practice
**Repository Path**: xiaoxinming123/codex-cli-best-practice
## Basic Information
- **Project Name**: codex-cli-best-practice
- **Description**: codex-cli-best-practice
- **Primary Language**: ε
Άδ»
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-04
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# codex-cli-best-practice
from vibe coding to agentic engineering - practice makes codex perfect
-white?style=flat&labelColor=555)
[](best-practice/) [](.codex/) [](orchestration-workflow/orchestration-workflow.md) [](https://developers.openai.com/codex/overview) [](#-tips-and-tricks) 
= Agents Β·
= Commands Β·
= Skills
## π§ CONCEPTS
| Feature | Location | Description |
|---------|----------|-------------|
|
[**Commands**](https://developers.openai.com/codex/cli/slash-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**](https://developers.openai.com/codex/subagents) | [`.codex/agents/.toml`](.codex/agents/) | [](best-practice/codex-subagents.md) [](.codex/agents/) Custom agents registered under `[agents.]` 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**](https://developers.openai.com/codex/skills) | [`.agents/skills//SKILL.md`](.agents/skills/) | [](best-practice/codex-skills.md) [](.agents/skills/) [Reference](docs/SKILLS.md) 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](https://developers.openai.com/codex/plugins) |
| [**Plugins**](https://developers.openai.com/codex/plugins) | `.codex-plugin/plugin.json` | Distributable bundles combining skills + app integrations + MCP servers β local/personal [marketplace](https://developers.openai.com/codex/plugins/build) system Β· Built-in: `$plugin-creator` Β· Browse via `/plugins` or Codex App |
| [**Marketplace**](https://developers.openai.com/codex/plugins)  | `$CODEX_HOME` β `[marketplaces.*]` | [](best-practice/codex-marketplace.md) 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**](https://developers.openai.com/codex/memories)  | `$CODEX_HOME/memories/` | [](best-practice/codex-memory.md) 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**](https://developers.openai.com/codex/workflows/) | [`.codex/agents/weather-agent.toml`](.codex/agents/weather-agent.toml) | [](orchestration-workflow/orchestration-workflow.md) 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**](https://developers.openai.com/codex/mcp) | `config.toml` β `[mcp_servers.*]` | [](best-practice/codex-mcp.md) [](.codex/config.toml) 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**](https://developers.openai.com/codex/config-basic) | [`.codex/config.toml`](.codex/config.toml) | [](best-practice/codex-config.md) [](.codex/config.toml) TOML-based layered config system Β· [Profiles](https://developers.openai.com/codex/config-basic) Β· [Sandbox](https://developers.openai.com/codex/cli/features) Β· [Approval Policy](https://developers.openai.com/codex/cli/features) Β· [Advanced](https://developers.openai.com/codex/config-advanced) (`[features]`, `[otel]`, `[shell_environment_policy]`, `[tui]`, model providers, granular approvals) Β· [Trust](https://developers.openai.com/codex/config-basic) system for project configs Β· `developer_instructions` Β· `model_instructions_file` for custom system prompts |
| [**Rules**](https://developers.openai.com/codex/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**](https://developers.openai.com/codex/guides/agents-md) | [`AGENTS.md`](AGENTS.md) | [](best-practice/codex-agents-md.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**](https://developers.openai.com/codex/hooks)  | [`.codex/hooks.json`](.codex/) | [](best-practice/codex-hooks.md) [](https://github.com/shanraisshan/codex-cli-hooks) User-defined shell scripts that inject into the agentic loop β logging, security scanning, validation, and custom automation Β· Requires `codex_hooks = true` feature flag |
| [**Speed**](https://developers.openai.com/codex/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**](https://developers.openai.com/codex/cli/features) | `/review` | Review branches, uncommitted changes, or specific commits β configurable `review_model` in config.toml Β· Custom review instructions |
| **AI Terms** | | [](https://github.com/shanraisshan/claude-code-codex-cursor-gemini/blob/main/reports/ai-terms.md) Agentic Engineering Β· Context Engineering Β· Vibe Coding |
| [**Best Practices**](https://developers.openai.com/codex/learn/best-practices) | | Official best practices Β· [Prompt Engineering](https://platform.openai.com/docs/guides/prompt-engineering) Β· [Codex Guides](https://developers.openai.com/codex/overview) |
[](orchestration-workflow/orchestration-workflow.md)
See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) for implementation details of
**Agent** β
**Skill** pattern. The agent fetches temperature from Open-Meteo and invokes the SVG creator skill.

```bash
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](https://github.com/shanraisshan/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](https://github.com/obra/superpowers) | 171k |
β
β
β
β
β
| 5 | 14 |
| [Spec Kit](https://github.com/github/spec-kit) | 92k |
β
β
β
β
| 0 | 0 |
| [gstack](https://github.com/garrytan/gstack) | 86k |
β
β
β
β
β
β
β
β
| 0 | 41 |
| [Get Shit Done](https://github.com/gsd-build/get-shit-done) | 58k |
β
β
β
β
β
β
| 33 | 0 |
| [oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex) | 27k |
β
β
| 19 | 36 |
| [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) | 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](https://github.com/shanraisshan/claude-code-best-practice/blob/main/development-workflows/cross-model-workflow/cross-model-workflow.md) [](https://github.com/shanraisshan/claude-code-best-practice/blob/main/development-workflows/cross-model-workflow/cross-model-workflow.md)
## π‘ TIPS AND TRICKS (50)
[Prompting](#tips-prompting) Β· [Planning](#tips-planning) Β· [AGENTS.md](#tips-agentsmd) Β· [Agents](#tips-agents) Β· [Skills](#tips-skills) Β· [Hooks](#tips-hooks) Β· [Memories](#tips-memory) Β· [Workflows](#tips-workflows) Β· [Advanced](#tips-workflows-advanced) Β· [Git / PR](#tips-git-pr) Β· [Debugging](#tips-debugging) Β· [Utilities](#tips-utilities) Β· [Daily](#tips-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](https://developers.openai.com/codex/cli/slash-commands) 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](https://github.com/shanraisshan/claude-code-best-practice/blob/main/development-workflows/cross-model-workflow/cross-model-workflow.md)) 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](https://developers.openai.com/codex/guides/agents-md) concise β 150 lines is a useful heuristic, but the actual limit is byte-based (32 KiB) |
| use [AGENTS.override.md](https://developers.openai.com/codex/rules) 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](https://developers.openai.com/codex/config-basic) 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](https://developers.openai.com/codex/subagents) with [skills](https://developers.openai.com/codex/skills) instead of general qa, backend engineer |
| use [multi-agent](https://developers.openai.com/codex/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](https://developers.openai.com/codex/skills) with clear name and description frontmatter for auto-discovery |
| skills are folders, not files β use references/, scripts/, examples/ subdirectories for [progressive disclosure](https://developers.openai.com/codex/skills) |
| 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](https://developers.openai.com/codex/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](https://developers.openai.com/codex/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](https://developers.openai.com/codex/config-basic) to switch between project-defined safety levels β in this repo, conservative and trusted are examples |
| start with [on-request](https://developers.openai.com/codex/cli/features) approval policy β only escalate to never when confident |
| use [/fork](https://developers.openai.com/codex/cli/slash-commands) in-session (or `codex fork`) to explore alternatives without losing your current thread, and [/resume](https://developers.openai.com/codex/cli/slash-commands) (or `codex resume`) to pick up where you left off |
β **Workflows Advanced (5)**
| Tip |
|-----|
| use [multi-agent](https://developers.openai.com/codex/multi-agent/) to spawn sub-agents for parallel fan-out work (GA β enabled by default) |
| use [codex exec](https://developers.openai.com/codex/noninteractive) for headless/CI pipelines |
| combine [sandbox modes](https://developers.openai.com/codex/cli/features) with [approval policies](https://developers.openai.com/codex/cli/features) β workspace-write + on-request is a good default |
| [git worktrees](https://git-scm.com/docs/git-worktree) 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](https://developer.chrome.com/blog/chrome-devtools-mcp), [Playwright](https://github.com/microsoft/playwright-mcp)) 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](https://github.com/shanraisshan/claude-code-best-practice) 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](https://iterm2.com/)/[Ghostty](https://ghostty.org/)/[tmux](https://github.com/tmux/tmux) terminals instead of IDE ([VS Code](https://code.visualstudio.com/)/[Cursor](https://www.cursor.com/)) | |
| [Wispr Flow](https://wisprflow.ai) for voice prompting (10x productivity) | |
| [codex-cli-hooks](https://github.com/shanraisshan/codex-cli-hooks) for Codex feedback |  |
| explore config.toml features like [profiles](https://developers.openai.com/codex/config-basic), [sandbox modes](https://developers.openai.com/codex/cli/features), and [MCP](https://developers.openai.com/codex/mcp) for a personalized experience | |
β **Daily (2)**
| Tip | Source |
|-----|--------|
| update Codex CLI daily |  |
| start your day by reading the [changelog](https://github.com/openai/codex/releases) |  |

| Article / Tweet | Source |
|-----------------|--------|
| How Codex is built β 90% self-built in Rust (Tibo, Pragmatic Engineer) \| 17 Feb 2026 | [](https://x.com/thsottiaux) |
| Skills in Codex β standardizing .agents/skills across agents (Embiricos) \| Feb 2026 | [](https://x.com/embirico) |
| Unrolling the Codex agent loop β how Codex works internally (Bolin) \| Jan 2026 | [Tweet](https://x.com/OpenAIDevs/status/2014794871962533970) |
| AMA with Codex team β CLI, sandbox, agents (Embiricos, Fouad, Tibo + team) \| May 2025 | [Reddit](https://www.reddit.com/r/ChatGPT/comments/1ko3tp1/ama_with_openai_codex_team/) |
| Codex CLI β open-source local coding agent, first look (Fouad + Romain) \| Apr 2025 | [Tweet](https://x.com/OpenAIDevs/status/1912556874211422572) |
## π¬ VIDEOS / PODCASTS
| Video / Podcast | Source | Link |
|-----------------|--------|------|
| The power user's guide to Codex β parallelizing workflows, planning, context engineering (Embiricos) \| 2026 \| How I AI | [](https://x.com/embirico) | [Podcast](https://open.spotify.com/episode/6RNqTaOb5ly3zgQCGB23fE) |
| Scaffolding is coping not scaling, and other lessons from Codex (Tibo) \| 2026 \| Dev Interrupted | [](https://x.com/thsottiaux) | [Podcast](https://linearb.io/dev-interrupted/podcast/openai-codex-thibault-sottiaux-agentic-autonomy) |
| How Codex team uses their coding agent (Tibo + Andrew) \| 18 Feb 2026 \| Every | [](https://x.com/thsottiaux) | [Podcast](https://every.to/podcast/transcript-how-openai-s-codex-team-uses-their-coding-agent) |
| Dogfood β Codex team uses Codex to build Codex (Tibo) \| 24 Feb 2026 \| Stack Overflow | [](https://x.com/thsottiaux) | [Podcast](https://stackoverflow.blog/2026/02/24/dogfood-so-nutritious-it-s-building-the-future-of-sdlcs/) |
| Why humans are AI's biggest bottleneck β Codex product vision (Embiricos) \| Feb 2026 \| Lenny's Podcast | [](https://x.com/embirico) | [Podcast](https://www.lennysnewsletter.com/p/why-humans-are-ais-biggest-bottleneck) |
| OpenAI and Codex (Tibo + Ed Bayes) \| 29 Jan 2026 \| Software Engineering Daily | [](https://x.com/thsottiaux) | [Podcast](https://softwareengineeringdaily.com/2026/01/29/openai-and-codex-with-thibault-sottiaux-and-ed-bayes/) |
## π SUBSCRIBE
| Source | Name | Badge |
|--------|------|-------|
|  | [r/ChatGPT](https://www.reddit.com/r/ChatGPT/), [r/OpenAI](https://www.reddit.com/r/OpenAI/), [r/Codex](https://www.reddit.com/r/Codex/) |  |
|  | [OpenAI](https://x.com/OpenAI), [OpenAI Devs](https://x.com/OpenAIDevs), [Tibo](https://x.com/thsottiaux), [Embiricos](https://x.com/embirico), [Jason](https://x.com/jxnlco), [Romain](https://x.com/romainhuet), [Dominik](https://x.com/dkundel), [Fouad](https://x.com/fouadmatin), [Bolin](https://x.com/bolinfest) |  |
|  | [Jesse Kriss](https://x.com/obra) ([Superpowers](https://github.com/obra/superpowers)), [Garry Tan](https://x.com/garrytan) ([gstack](https://github.com/garrytan/gstack)), [Kieran Klaassen](https://x.com/kieranklaassen) ([Compound Eng](https://github.com/EveryInc/compound-engineering-plugin)), [Lex Christopherson](https://x.com/official_taches) ([GSD](https://github.com/gsd-build/get-shit-done)), [Yeachan Heo](https://x.com/bellman_ych) ([oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)), [Andrej Karpathy](https://x.com/karpathy) |  |
|  | [OpenAI](https://www.youtube.com/@OpenAI) |  |
|  | [Lenny's Podcast](https://www.youtube.com/@LennysPodcast), [The Pragmatic Engineer](https://www.youtube.com/@pragmaticengineer) |  |
## 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