codex-cli-best-practice: A Reference Layout for Codex CLI Configuration
from vibe coding to agentic engineering - practice makes codex perfect
At a glance
- What is it?
- This repository is not a tool you install. It is a working example of how to lay out a Codex CLI project: agents, skills, hooks, rules, MCP servers and TOML config, all committed to the repo so the agent inherits them. The value is in the file structure, and so is the risk.
- Who is it for?
- Adopt this as a structural template if your team already runs Codex CLI and wants agents, skills, hooks and rules committed alongside the code rather than living in each developer's home directory. Do not adopt it if you expect a runnable tool, a Python library, or anything that works outside Codex CLI, because the repository is documentation plus example config and the Python language tag reflects tooling around it, not a package you import.
- 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 103 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 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem Is Configuration Drift, Not Missing Features
Codex CLI already ships slash commands, subagents, skills, plugins, memories, MCP servers and a TOML config system. The gap this repository addresses is that none of those features help if each engineer configures them differently, or not at all. A new contributor clones the code and gets a bare agent that knows nothing about the project's conventions. The repository's answer is to commit the configuration: agents under .codex/agents/, skills under .agents/skills/, hooks in .codex/hooks.json, rules in .codex/rules/, and the layered config in .codex/config.toml. The audience is a team already using Codex CLI that wants the same behaviour on every machine. It is not aimed at someone evaluating whether to use Codex CLI at all, and it does not attempt to be editor-agnostic.
What Actually Sits in the Repository
The README is organised as a concepts table, and the table is the product. Each row names a Codex CLI feature, points at the official documentation, and points at a local path where the repository implements it. Commands live in the interactive session. Subagents live in .codex/agents/<name>.toml, registered under [agents.<name>] with global settings for max_threads, max_depth and job_max_runtime_seconds. Skills live in .agents/skills/<name>/SKILL.md with required name and description metadata and progressive disclosure through scripts/, references/, assets/ and an optional agents/openai.yaml. Plugins use .codex-plugin/plugin.json. Marketplaces are declared under [marketplaces.*] in $CODEX_HOME and catalogued at .agents/plugins/marketplace.json. Memories sit in $CODEX_HOME/memories/ and are enabled with [features] memories = true. MCP servers are declared under [mcp_servers.*] in config.toml. Rules are Starlark policies under .codex/rules/ using prefix_rule() with allow, prompt or forbidden decisions. AGENTS.md provides project context with hierarchical discovery from the current directory to the repository root, capped at 32 KiB by project_doc_max_bytes, with AGENTS.override.md for personal overrides. The Python tag on the repository is best read as covering the surrounding scripts and tooling, since nothing in the README describes an importable package.
The Mechanism Is File Discovery, Not a Runtime
Nothing here executes on its own. Codex CLI walks the filesystem and the TOML files, and the repository is arranged so that walk finds something useful. AGENTS.md is discovered hierarchically from the working directory upward and truncated at the byte cap. Skills are matched either explicitly through /skills or the $skill-name form, or implicitly by comparing the task against each skill's description field, which is why the README calls name and description required metadata rather than optional. Subagents are registered by TOML key and then orchestrated in parallel, with max_threads and max_depth bounding the fan-out and job_max_runtime_seconds bounding each job. Hooks fire on user-defined events. Rules are evaluated as command policies, and the README notes they can be checked ahead of time with codex execpolicy check, which is the one place the repository offers a verification step rather than a convention. MCP servers are either STDIO or Streamable HTTP, and Codex CLI can also act as an MCP server itself through codex mcp-server, exposing codex() and codex-reply() tools. The design assumes the agent's behaviour should be reproducible from the repository contents. That assumption holds only as long as the configuration is not overridden locally, and the README explicitly provides AGENTS.override.md for exactly that kind of local divergence.
Getting It Running Means Copying Paths, Not Installing
There is no installation command in the material. The practical route is to clone the repository, inspect .codex/config.toml and the example agents, and reproduce the parts you want in your own project. The commands the README does give are Codex CLI commands for managing the pieces: codex mcp add, get, list, login, logout and remove for MCP servers; codex mcp login for OAuth-protected servers; codex plugin marketplace add, upgrade and remove for marketplaces, accepting GitHub shorthand, git URLs and local directories; codex execpolicy check for testing Starlark rules. Configuration keys worth noting before you copy anything: [agents] with max_threads, max_depth and job_max_runtime_seconds; [features] memories = true; [memories] for the memory pipeline; [mcp_servers.*] with supports_parallel_tool_calls = true per server on v0.121.0 or later; project_doc_max_bytes for the AGENTS.md cap; developer_instructions and model_instructions_file for system prompt overrides. The README badges a baseline of Codex CLI v0.137.0 dated June 4, 2026, and several features are marked with version floors: marketplaces at v0.121.0, memories at v0.119.0, MCP Apps at v0.119.0, parallel MCP calls at v0.121.0. If your installed CLI predates those, the corresponding config keys will not do what the repository shows.
Where This Repository Stops Being Useful
The material is a README plus linked files, and it leans on the official Codex CLI documentation for every explanation of behaviour. That makes it a pointer collection as much as a guide. If the upstream documentation changes, the repository's concepts table can go stale while still looking authoritative, and the version badge is a date-stamped claim the maintainer has to keep refreshing. The hooks feature is marked beta, memories and marketplace are marked beta or new, so the parts most likely to save a team time are also the parts most likely to change shape. The configuration is also Codex-specific by construction. Skills, subagents, hooks, rules and the TOML layering have no meaning outside Codex CLI, so a team running a different agent harness gets nothing transferable from the directory structure. Finally, committing agent configuration to the repository is a governance decision as much as a technical one: rules that decide which commands are allowed, and hooks that run on events, are code paths that affect every contributor who clones the repo. The README describes the mechanisms but does not discuss review process for changes to them, and that omission is the largest gap for a team of any size.
Compared With a Plain AGENTS.md
The simplest alternative is to write a single AGENTS.md and stop there. That file is already supported by Codex CLI, it is discovered hierarchically, it is capped at 32 KiB, and it requires no TOML, no Starlark and no hook definitions. The difference in approach is scope. AGENTS.md carries prose context: conventions, build commands, things to avoid. This repository goes further by encoding behaviour as configuration, where a subagent is a TOML file with a role, a skill is a directory with metadata and optional scripts, and a rule is a Starlark policy with an allow, prompt or forbidden decision that can be tested with codex execpolicy check. The trade-off is that prose is easy to review and configuration is easy to get subtly wrong. A mistyped key in config.toml fails quietly in a way a paragraph of guidance does not. For a solo developer, a well-written AGENTS.md plus a couple of skills is probably the better ratio of effort to result. The repository's structure starts paying off when several people need identical agent behaviour and the configuration itself needs to be reviewed like code.
Maintenance Cost and the MIT Licence
The repository is MIT-licensed, which permits reuse, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement and it means copying the layout into a private repository is straightforward, but it also means no warranty and no support obligation from the author. Read the licence text in the repository rather than relying on this summary; it is not legal advice. The maintenance cost falls in two places. First, upstream drift: the README tracks Codex CLI versions, so every feature the repository documents can change independently of the repository, and the badge is evidence that the author updates it rather than a guarantee. Second, your own drift: once agents, skills, hooks and rules are committed, someone has to keep them consistent with the code they describe. A skill whose description no longer matches the task it is meant to trigger will simply stop being selected, and nothing will tell you. The codex execpolicy check command covers rules, but the material does not describe an equivalent check for skills or subagent definitions, so those need to be verified by using them.
Editorial conclusion
Adopt this as a structural template if your team already runs Codex CLI and wants agents, skills, hooks and rules committed alongside the code rather than living in each developer's home directory. Do not adopt it if you expect a runnable tool, a Python library, or anything that works outside Codex CLI, because the repository is documentation plus example config and the Python language tag reflects tooling around it, not a package you import. Before copying anything, verify three things in your own checkout: that your Codex CLI build matches the v0.137.0 baseline the README badges, that every path under .codex/ and .agents/ resolves after you rename the directory, and that the hooks and rules you take on do not conflict with the approval policy your team already set.
Community notes