codex-cli-best-practice: A Working Reference for OpenAI Codex CLI Agentic Patterns
from vibe coding to agentic engineering - practice makes codex perfect
At a glance
- What is it?
- shanraisshan/codex-cli-best-practice is a GitHub repository that assembles configuration templates and conceptual guides for OpenAI's Codex CLI, covering subagents, skills, hooks, MCP servers, execution policies, and TOML-based config in one browsable structure. It targets engineers who want working examples rather than reading through the official documentation alone.
- Who is it for?
- Engineers new to Codex CLI's agentic layer will find this repository genuinely useful as a collection of copy-paste TOML examples and conceptual notes. It is not a library to install and it is not a substitute for the official docs when precise, versioned behavior matters.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 117 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 28, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What codex-cli-best-practice Solves and Who Uses It
OpenAI's Codex CLI ships with a large configuration surface: TOML files for subagents, skill packages, plugin bundles, MCP server registrations, execution policy rules, session settings, and memory toggles. The official documentation covers each of these, but it does not always provide copy-ready configuration files. Engineers who want to see how the pieces fit together in practice, rather than reading separate documentation pages for each concept, are the primary audience for this repository.
The repository is organized as a reference collection. It does not publish a package on npm or PyPI, and it has no release versions. Its value is in the file structure: working examples live under .codex/, skill definitions under .agents/skills/, and longer narrative guides under best-practice/. The repository description states the intent plainly: from vibe coding to agentic engineering, practice makes codex perfect.
Repository Layout: Where Each Concept Lives
The top-level structure divides content by concern. The .codex/ directory holds the primary configuration files: config.toml for global and profile settings, agents/ for subagent TOML files, hooks.json for shell hook definitions, and rules/ for Starlark execution policies. The .agents/ directory sits alongside .codex/ and holds skill packages in the format .agents/skills/<name>/SKILL.md. Plugin definitions follow a separate path: .codex-plugin/plugin.json.
The best-practice/ folder contains guide documents for concepts such as subagents, skills, MCP, config, memory, hooks, marketplace, and agents.md. The orchestration-workflow/ folder holds an end-to-end walkthrough. Examples live under examples/ci-cd/ and examples/profiles/, covering specific use patterns.
To use the repository, clone it from GitHub and browse the relevant subfolder. After cloning, copy the config patterns you need into your own project's .codex/ directory.
Subagent Configuration and Parallel Execution
Codex CLI supports custom agents registered in .codex/agents/<name>.toml. Each file follows the [agents.<name>] block structure and can define a dedicated role, a system prompt, and tool permissions for that agent. Global limits for the agents system go under a separate [agents] section and include max_threads, max_depth, and job_max_runtime_seconds.
Three built-in agents ship with Codex CLI: default, worker, and explorer. The best-practice/ guides document how to write custom agents on top of these and how to orchestrate parallel subagent calls with CSV batch processing. The .codex/agents/weather-agent.toml file in the repository serves as a concrete walkthrough of an end-to-end agentic workflow pattern.
This is one of the areas where the repository adds value over the official documentation: the TOML structure for a working subagent is visible in a single file, rather than assembled from separate documentation pages. The limitation is that these examples may not reflect the current Codex CLI version at any given time.
Skills, Plugins, and the Marketplace Pipeline
Skills are reusable instruction packages stored as SKILL.md files under .agents/skills/<name>/. Each skill requires a name and description at minimum, and can optionally include scripts/, references/, assets/, and an agents/openai.yaml file. Skills are invoked explicitly via the /skills command or by typing $skill-name. Implicit invocation happens when a description match occurs. Three built-in skills ship with the tool: $plan, $skill-creator, and $skill-installer.
Plugins bundle skills with app integrations and MCP server configurations. A plugin definition lives at .codex-plugin/plugin.json and is treated as a distributable unit. The marketplace system, introduced in version 0.121.0, manages plugin catalogs through entries under [marketplaces.*] in $CODEX_HOME. The CLI exposes commands for managing marketplaces including add, upgrade, and remove subcommands that accept GitHub shorthand, full git URLs, and local directory paths. Installed marketplaces appear in the /plugins TUI tabs. Browsing available plugins from within a session uses /plugins.
MCP Servers, Hooks, and Execution Policy Rules
MCP server registrations go under [mcp_servers.*] in config.toml. Codex CLI acts as an MCP client for external tools (supporting STDIO and Streamable HTTP), and it also exposes an MCP server interface of its own through codex mcp-server, which provides codex() and codex-reply() tools to other agents. OAuth is supported via codex mcp login.
Hooks inject shell scripts into the agentic loop. Hook definitions live in .codex/hooks.json and require setting codex_hooks = true in the features block. The best-practice/codex-hooks.md guide covers patterns for logging, security scanning, validation, and custom automation.
Execution policies use a Starlark-based rule system in .codex/rules/. Rules define allow, prompt, or forbidden decisions against command prefixes using the prefix_rule() function. The policy can be tested before deployment:
codex execpolicy checkThis command validates that rules evaluate correctly against sample commands without running a full session. Rules work alongside the approval_policy system already in config.toml.
What the Repository Covers Incompletely
The repository is a community reference, not an official product. Several areas are thin or absent. The AGENTS.md documentation notes that project-level context files are discovered hierarchically from the current working directory to the repo root and are capped at 32 KiB via project_doc_max_bytes, but no worked example of a multi-project hierarchy appears in the repository.
The memories system documentation notes cross-session memory is scoped per user, not per project, and requires the [features] memories = true setting. The guide exists but no example session logs or memory output samples are included. The code review feature (/review) receives only a brief mention; the repository does not show a worked configuration of review_model in config.toml.
Any engineer adopting patterns from this repository must verify them against the currently installed Codex CLI version. The repository makes no commitment to keeping pace with every release.
Alternative Approach and Maintenance
The direct alternative is the official Codex CLI documentation at developers.openai.com/codex. The official docs are the authoritative, versioned reference for every feature. The difference in approach is practical: the official documentation explains each concept in isolation; this repository shows how they combine in a single directory layout with named example files. For a team that prefers reading code over prose documentation, the repository is faster to orient in.
The repository has no GitHub releases and no versioned package. The last push was on June 4, 2026. The license is MIT, so copying any file into your own project's .codex/ directory is unrestricted. There is no upgrade path in the conventional sense: you pull the latest commit and copy what you need.
Editorial conclusion
Engineers new to Codex CLI's agentic layer will find this repository genuinely useful as a collection of copy-paste TOML examples and conceptual notes. It is not a library to install and it is not a substitute for the official docs when precise, versioned behavior matters. Before relying on any config pattern here, confirm the Codex CLI version you are running and check the setting against the official reference at developers.openai.com/codex, since the repository had its last push on June 4, 2026, and Codex CLI releases frequently.
Frequently asked questions
How do I install codex-cli-best-practice?
The repository is a reference collection, not an installable package. Clone it with git and copy the relevant configuration files into your own project's .codex/ directory. There is no npm or pip install step.
What are Codex CLI subagents and where do their config files live?
Subagents are custom agents registered in .codex/agents/<name>.toml under the [agents.<name>] block. Global limits such as max_threads, max_depth, and job_max_runtime_seconds go under the [agents] section. Three built-in agents ship with Codex CLI: default, worker, and explorer.
What is the difference between a Codex skill and a Codex plugin?
A skill is a reusable instruction package stored as a SKILL.md file under .agents/skills/<name>/, invoked by name or description match. A plugin bundles one or more skills with app integrations and MCP server configuration into a distributable unit defined in .codex-plugin/plugin.json.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/shanraisshan-codex-cli-best-practice)