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 | | Sessions | $CODEX_HOME/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 request_user_input capability gated behind an under-development feature flag in codex-cli 0.115.0, but neither is