~/.codex/ (personal). This shows every file type in one place — a real project uses only the parts it needs. Click any row for details, examples, and the source link. The 🔌 Plugins tab expands the plugin layout.
Select a file or folder
Click any item in the tree to see its description, usage examples, and source documentation.
Navigate with Tab and Enter, or close with Esc.
[mcp_servers] TOML, hook files, and manual app setup separately. A plugin collapses those pieces — skills, MCP servers, app connectors, hooks, scripts, and assets — into one versioned, installable, shareable bundle.
A plugin is a folder identified by a required .codex-plugin/plugin.json manifest. You install plugins from a marketplace (a repo, Git URL, or local source) through the Codex app or the codex plugin CLI. Layout follows the official build-plugins guide, the core-plugins loader, and the plugin-creator sample skill in openai/codex.
Plugin components
Click any item to see what it does and how it is packaged and distributed.
Every Codex file type, grouped by job. Cards carry the same descriptions as the tree — badges (scope, documented vs convention) and cross-links are added automatically. Click a card for the full detail and source link.
📋 AGENTS.md
The anchor instruction file and open standard. Read before any work, chained from project root down to your cwd.
📋 AGENTS.override.md
Read instead of AGENTS.md in the same directory. Override inherited guidance without editing the original.
📋 Nested AGENTS.md
An AGENTS.md in any subdirectory, scoped to that part of the tree. Deeper files refine shallower ones.
⚙️ Fallback filenames
Teach Codex extra instruction filenames via project_doc_fallback_filenames.
⚙️ config.toml
The main settings file. Model, approvals, sandbox, MCP, subagents, hooks, features — all here.
⚙️ .codex/config.toml
Per-project layer. Walks up to the project root; closest layer wins. Trusted projects only.
⚙️ <name>.config.toml
Named overlay loaded with --profile. Swap whole sets of settings on demand.
⚙️ /etc/codex/config.toml
System config layer for managed machines, below user config and above built-in defaults.
🏢 requirements.toml
Org-enforced constraints on managed machines. Some keys are only honoured here.
📌 project_root_markers
What counts as the project root (default: a .git directory).
📂 .agents/skills/
Repo skill discovery, scanned from cwd to project root. Progressive disclosure keeps context lean.
📂 ~/.agents/skills/
Current personal skill root for user-installed skills available across repos.
📂 .codex/skills/
Source-confirmed compatibility skill root; prefer .agents/skills/ for new repo skills.
📝 SKILL.md
The required skill file: name + "Use when…" triggers, then the instructions. Portable across agents.
📝 agents/openai.yaml
Optional Codex-only metadata in a skill — UI hints, invocation policy, tool deps.
🪝 scripts / references
Bundled resources loaded only when the skill activates.
⚙️ [[skills.config]]
Disable a discovered skill without deleting it.
📂 ~/.codex/prompts/
Custom prompt folder. Now deprecated in favour of skills, but still works.
📝 *.md prompt
A reusable prompt invoked as /prompts:<name>, with placeholders and named args.
🔌 [mcp_servers]
Connect external MCP tool servers (STDIO or HTTP). Manage with codex mcp.
🤖 [agents] subagents
Configure subagent roles. Spawned only when you explicitly ask.
🤖 custom agent TOML
One standalone agent file under ~/.codex/agents/ or .codex/agents/.
🪝 hooks.json / [hooks]
Run commands at lifecycle events. A PreToolUse hook can block a tool call.
🪝 hook script
Reads event JSON on stdin; can deny or rewrite a pending action.
🔌 a plugin
One bundle of skills + MCP + app connectors. Installable and shareable.
⚙️ plugin.json
The required manifest inside .codex-plugin/.
🔌 .mcp.json
Default plugin-bundled MCP server config file.
🌐 .app.json
Default plugin app connector manifest.
🪝 hooks/hooks.json
Default plugin lifecycle hook file.
🖼 assets/
Plugin icons, logos, screenshots, and templates referenced by manifests.
🛒 marketplace
Where Codex loads plugins from — a repo, Git URL, or local root.
📂 ~/.codex/
Your Codex home: config, credentials, prompts, skills, sessions, logs.
📂 skills/.system/
Codex-managed cache for OpenAI-bundled system skills.
📂 plugins/
A common local place to store plugin folders referenced by marketplace files.
🔑 auth.json
Credentials, unless stored in the OS keyring. Never commit.
📄 history.jsonl
Your prompt history for recall and search.
📂 sessions/
Dated transcripts; codex resume reopens them.
📂 logs/
The opt-in plaintext TUI log for troubleshooting.
-c key=value flags passed on the command line, for that invocation only..codex/config.toml layers, root → cwd (closest wins; trusted projects only).--profile → ~/.codex/<name>.config.toml.~/.codex/config.toml — your global defaults./etc/codex/config.toml — system defaults, if present.requirements.toml can constrain any of the above on managed machines.Per directory, first match wins: AGENTS.override.md → AGENTS.md → fallback filenames. Codex assembles the chain:
~/.codex/AGENTS.override.md, else ~/.codex/AGENTS.md.project_doc_max_bytes caps the combined size before truncation.🍎 macOS / 🐧 Linux / WSL
~/.codex/
Credentials: auth.json or the system keyring (Keychain / Secret Service).
🪟 Windows (native)
%USERPROFILE%\.codex\
Credentials: auth.json or Windows Credential Manager.
🔀 Override location
Set the CODEX_HOME environment variable to relocate the entire home directory.
📄 Sessions & logs
sessions/, logs/, and bundled skills/.system/ sit under the same home.
Precedence, made clickable
Click any underlined file to see what it does and where it sits in the resolution order.
Everything here is drawn from OpenAI's official Codex documentation, the openai/codex repository, openai/skills, and the AGENTS.md open-format project, verified June 12, 2026. Codex changes quickly — treat anything labelled ⚙ Convention as source-confirmed or community-observed behavior that is not the primary documented recommendation.
📘 Official documentation
- developers.openai.com/codex — docs home
- AGENTS.md guide — instruction chain & overrides
- Config basics & Advanced config
- Config reference — every key
- Agent Skills · Custom prompts · Subagents
- Hooks · MCP · Environment variables
- Plugins · Build plugins
- CLI reference · CLI features
🐙 Source repository
- openai/codex — the Codex CLI itself
- docs/config.md — config & directory reference
- core-skills loader — skill discovery roots, including compatibility paths
- core-plugins manifest parser & loader — plugin defaults and path overrides
- plugin-creator skill, plugin-json-spec.md, and create_basic_plugin.py
- openai/skills — OpenAI's skills catalog for Codex
- agentsmd/agents.md — AGENTS.md open-format project linked from OpenAI docs
⚠️ Things that catch people out
- Codex config is TOML (
config.toml) — not JSON like Claude'ssettings.jsonor YAML. - The instruction file is AGENTS.md, the open standard Codex co-created. It is not Codex-specific — Claude, Gemini, and Copilot read it too.
- Custom prompts (
~/.codex/prompts/) are deprecated; OpenAI points you to skills for reusable, shareable instructions. - Recommended repo skills live in
.agents/skills/; the current source also keeps.codex/skills/as a compatibility root. - Personal installed skills live in
~/.agents/skills/;~/.codex/skills/is a deprecated compatibility location plus the.systemcache for bundled OpenAI skills. - Skill UI metadata is
agents/openai.yamlinside the skill folder, not a top-level repo file. - Custom agents are standalone TOML files under
~/.codex/agents/or project.codex/agents/. - Plugin defaults are
skills/,.mcp.json,.app.json, andhooks/hooks.json;plugin.jsoncan point to alternate relative paths. - Two homes, two chains: config precedence and the AGENTS.md chain layer differently.
🔍 Boundary of this map
- This is a file-structure map, not a field-by-field schema for every TOML key — see the config reference for those.
- The full hook event list and payload fields live in the hooks reference; this page shows where hook files/config live.
- Exact app-data filenames evolve between CLI releases; verify on your installed version with
codex --version. - An independent reference — not affiliated with or published by OpenAI.