19 min read

.codex/ folder explained

Source: http://x.com/i/article/2038286031057715200

If you are trying to understand how Codex is configured, .codex/ is the first place to look. It is also the point where a lot of confusion starts.

.codex/ is Codex’s own configuration directory. But it is not the whole model. Codex is also shaped by instruction files such as AGENTS.md, by repository and user configuration, by reusable skills and custom agents, and by the trust boundary that decides whether repo-provided settings are loaded at all.

The same underlying agent can run through the CLI, the desktop app, or the IDE extension. Those surfaces share the same core layering. Once you can see the pieces, the setup gets much easier to reason about.

Some setups also include .agents/. That is better understood as an adjacent cross-agent layer than as a second Codex configuration directory. So this guide stays centered on .codex/ and treats .agents/ as context you may or may not need.

The short answer

If you only remember one distinction, make it this:

  • AGENTS.md tells Codex how to work in a project or directory
  • .codex/ holds Codex-specific configuration, rules, custom agents, hooks, and local state
  • project .codex/ is repo-shared Codex configuration; user ~/.codex/ is your personal Codex home across repos
  • .agents/ holds reusable skills and plugin marketplace files in a shared format, so they can stay portable across Codex and some other compatible agents, for example Claude Code or OpenCode
  • Trust determines whether repository-provided .codex/ config is considered at all

The split between .codex/ and .agents/ is intentional:

Image

At the repo level, both directories are protected by the sandbox and can be committed to version control for team sharing. User-level directories such as ~/.codex/ and ~/.agents/ are personal and should not be committed. The .codex/ directory is only read by Codex; the .agents/ directory can also be read by other compatible agents that support the same shared format.

A practical mental model is: instructions tell Codex what you want, config and rules determine what Codex may do without asking, and trust determines whether repository-provided config is considered at all.

A placement rule that covers most cases is:

  • If it is instructions for how Codex should work, put it in AGENTS.md
  • If it is Codex-specific configuration or policy, put it in .codex/
  • If it should follow the user across repositories, put it in ~/.codex/
  • If it should stay portable across different agents, put it in .agents/

Do not keep both directories just for completeness. Keep both only when you need both kinds of things:

  • Use AGENTS.md when you want to give Codex working instructions
  • Use .codex/ when you want Codex-specific configuration, guardrails, rules, agents, hooks, or app-managed project files
  • Use .agents/ when you also want portable skills or plugin marketplace entries that should remain usable beyond Codex

Many small setups only need AGENTS.md and maybe .codex/. Teams usually add .agents/ when they want reusable workflows that are not locked to Codex alone.

There are two .codex/ scopes

This is the first place people get tripped up: “the .codex/ folder” can mean two different locations with two different jobs:

Image

A good rule of thumb is:

  • Anything that travels with the repo belongs in project .codex/
  • Anything that follows you across repos belongs in user ~/.codex/

This also lines up with trust and precedence. User ~/.codex/ is the base layer. Project .codex/ is the repo-specific layer that Codex only loads for trusted projects.

Some concrete examples:

  • A shared sandbox or approval policy for this codebase belongs in project .codex/config.toml
  • Your personal auth, history, caches, or global defaults belong in user ~/.codex/
  • A reviewer agent the whole team should use in this repo belongs in project .codex/agents/
  • A personal agent or rule you want available everywhere belongs in user ~/.codex/agents/ or ~/.codex/rules/

Typical layout across the repo and home directory

Here is the setup on one screen. It spans the repository, the user’s home directory, and, if you use it, the shared skills layer:

plaintext

your-repo/
├── AGENTS.md
├── .codex/
│   ├── config.toml
│   ├── hooks.json (if hooks enabled)
│   ├── agents/
│   │   └── reviewer.toml
│   ├── rules/
│   │   └── default.rules
│   └── (Codex app-managed files, e.g. app-generated local-environment config)
└── .agents/
    ├── skills/
    │   └── code-review/
    │       ├── SKILL.md
    │       ├── references/
    │       └── scripts/
    └── plugins/
        └── marketplace.json (repo-scoped plugin marketplace)

~/.codex/
├── config.toml
├── AGENTS.md (or AGENTS.override.md)
├── hooks.json (if hooks enabled)
├── rules/
├── agents/
├── worktrees/ (Codex app-managed git worktrees for parallel threads)
├── plugins/
│   └── cache/ (installed plugin cache)
│       └── $MARKETPLACE/$PLUGIN/$VERSION/
├── prompts/ (deprecated custom prompts)
├── auth.json (if using file-based credential storage)
└── history.jsonl (if enabled)

$HOME/.agents/
├── skills/
│   └── (your personal skills)
└── plugins/
    └── marketplace.json (personal plugin marketplace)

This is the shape the model takes once you put the main directories side by side.

How the pieces fit together

Once the folders are visible, the next question is what each one actually controls. If you find yourself asking “is this instructions, config, or a shared skill?”, this is the map:

Image

Where AGENTS.md fits

Once the folders are clear, the next confusion is usually whether something belongs in AGENTS.md or .codex/. The split is simple: if .codex/ is config, AGENTS.md is instructions.

Codex reads AGENTS.md files before doing work, and it supports layering so global defaults and local project guidance can be combined:

  • Global scope: in the Codex home directory (by default ~/.codex), Codex reads AGENTS.override.md if it exists; otherwise it reads AGENTS.md, with the first non-empty file winning at that level
  • Repo scope: you can add AGENTS.md at the repo root and additional AGENTS.md files in subdirectories for local rules; if an AGENTS.override.md exists in a directory, it overrides the AGENTS.md there
  • Load limits: Codex concatenates discovered instruction docs with blank lines until it hits the configured byte limit project_doc_max_bytes, which defaults to 32 KiB

There is also a fallback mechanism for organisations that already use a different filename. With project_doc_fallback_filenames, you can tell Codex to treat files such as TEAM_GUIDE.md as instruction sources.

Codex can scaffold (generate) a starter AGENTS.md via the CLI slash command /init. It is a starting point. Treat it as a scaffold to build on.

The most useful AGENTS.md files usually cover:

  • How to run the project: build, test, and lint commands (among others)
  • Key directories and ownership boundaries
  • Constraints and do-not rules that are not already enforced elsewhere
  • Links to deeper docs, review playbooks, or planning templates instead of inlining everything

A minimal example:

markdown

# Project instructions

## Commands

- Install: pnpm install

- Test: pnpm test

- Lint: pnpm lint

- Build: pnpm build

## Repo layout

- packages/api/ is the backend

- packages/web/ is the frontend

- shared/ contains cross-package utilities

## Working agreements

- Prefer adding or adjusting tests when changing behaviour.

- Don't introduce new production dependencies without asking first.

- Never commit secrets; treat *.env as sensitive.

Keep AGENTS.md short enough that a human will maintain it. Concrete instructions age well. Long policy prose usually does not.

What belongs in .codex/

Once the boundaries are clear, the next decision is placement: what belongs in .codex/ rather than AGENTS.md or .agents/? The simplest way to think about .codex/ is as Codex’s repo-level configuration directory. Teams use project .codex/ for shared project configuration, shared rules, project-scoped custom agents, and app-managed project files. At the user level, ~/.codex/ stores personal defaults and state such as auth, history, logs, caches, plugin state, and legacy prompt files. It sits next to AGENTS.md, which provides instructions, and next to .agents/, which is the cross-agent shared directory for skills and plugin marketplaces.

From there, the useful way to read .codex/ is from the common pieces outward: first the parts most teams touch, then the extension layers that sit on top.

The core .codex/ pieces most teams touch first

This is the path most setups actually use: configuration layers, config.toml, rules, project-scoped agents, and app-managed files.

Configuration layers and trust boundaries

Codex configuration uses multiple layers rather than a single file. At minimum, you are dealing with:

  • A user layer in ~/.codex/config.toml
  • Optional project layers in .codex/config.toml files inside the repository, loaded from the repo root down toward the current working directory, with the closest file winning
  • An optional system layer such as a managed config file (managed_config.toml, meaning a config file enforced by the system or organisation) on supported platforms

Codex resolves values by precedence, meaning it decides which layer wins when the same setting is defined in more than one place, with higher-precedence managed and session layers taking priority over user defaults. The precedence order is: MDM managed preferences on macOS (organisation-enforced settings on managed Macs), system managed config, session or CLI overrides (temporary per-run overrides), and user config. Project-scoped .codex/config.toml files are loaded for trusted projects and merged into this hierarchy. Values not set in any layer fall back to hardcoded defaults.

Trust is the boundary that matters. Codex loads project-scoped .codex/ config only when the project is trusted; untrusted projects skip those layers. Repositories are untrusted input until you explicitly trust them.

In current Codex config, project trust can be recorded explicitly via projects..trust_level, with values such as "trusted" and "untrusted".

.codex/config.toml and runtime guardrails

AGENTS.md says how Codex should work. config.toml sets the guardrails around that work.

Codex stores user configuration at ~/.codex/config.toml and project overrides in .codex/config.toml, with project config applying only for trusted projects.

Two settings dominate the security model:

  • Sandbox mode: what the agent can do technically, including filesystem scope and network access
  • Approval policy: when Codex must stop and ask before executing actions

By default, network access is off, and workspace-write sandboxing, a mode that lets Codex write in the workspace while still protecting certain paths, is intended to confine actions to the active workspace.

Codex also exposes web search configuration with three modes: cached, live, or disabled. Cached mode uses an OpenAI-maintained index; live mode fetches fresh pages. That distinction matters because browsing introduces prompt-injection risk from untrusted content, meaning malicious instructions can be hidden inside fetched pages.

One detail that often affects real projects is that, in workspace-write mode, some environments keep .git/ and .codex/ read-only even when the rest of the workspace is writable. That can force approvals for operations such as git commit that need to cross the sandbox boundary. If you want Codex to skip, gate, or block specific commands outside the sandbox, rules are the mechanism for doing that.

Codex stores local state under CODEX_HOME, which defaults to ~/.codex. Typical files there include auth.json when file-based credential storage is enabled, history.jsonl when history persistence is enabled, and other logs or caches.

If you want a separate automation identity with different config, instructions, and local state, you can point CODEX_HOME somewhere else, including a repository-local .codex directory. Codex will then resolve instruction sources relative to that location.

Rules Rules control which commands Codex may run outside the sandbox. They are experimental. They use a small rule language based on Starlark, a Python-like configuration language, implemented in starlark-rust. Rules can match command prefixes and assign decisions such as "prompt".

Codex scans rules/ directories under its team-config locations at startup. When you add a command to the approved list interactively, Codex writes that decision into a user-layer rules file, ~/.codex/rules/default.rules, so later runs can skip the same prompt.

A minimal example:

python

# Prompt before running gh pr view outside the sandbox
prefix_rule(
  pattern = ["gh", "pr", "view"],
  decision = "prompt",
  justification = "PR metadata can include untrusted content; keep it explicit."
)

That is the value of rules: they turn command safety into policy instead of habit.

Subagents and app-generated project state

Codex also supports subagent workflows. It can spawn parallel specialised agents and then consolidate their output. It only does this when you explicitly request it, and it is more token-expensive than single-agent work.

Codex ships with built-in agents such as explorer and awaiter.

You can define custom agents as standalone TOML files in:

  • ~/.codex/agents/ for personal agents
  • .codex/agents/ for project-scoped agents

Global subagent execution limits are configured under [agents] in config. The defaults include agents.max_threads = 6 and agents.max_depth = 1, along with a warning that deeper recursion can increase cost and unpredictability substantially.

A custom agent file must include description, and standalone agent files discovered in the agents/ directory must also include developer_instructions. name is optional and defaults to the filename. Agent files can also override settings you might otherwise place in config, including model, reasoning effort, sandbox mode, MCP servers, and skills configuration.

The desktop app adds another project-scoped use of .codex/: local environments. This is specific to the Codex desktop app and does not apply to the general CLI. You configure it in the app settings UI. There you define setup scripts that run automatically when a worktree, a fresh working copy of the repo, is created for a new thread. You can also define actions such as running the dev server or tests from the app UI (user interface). The app stores its generated local-environment config inside the .codex folder at the project root, and you can commit that generated config to Git for sharing.

The project-vs-user split shows up here again. Project .codex/ stores the shared setup definition. The actual worktrees live centrally under

$CODEX

_HOME/worktrees/, which defaults to ~/.codex/worktrees/, in the user’s Codex home. Those worktrees run in a different directory from the local project and only inherit files checked into Git. So setup scripts configured through local environments are what install dependencies, build artifacts, or restore any other state that .gitignore excludes. Setup scripts also support platform-specific variants for macOS, Windows, and Linux. The dedicated Worktrees section below covers the checkout mechanics in more detail.

Codex manages local-environment files under project .codex/. The app creates and updates those files through its settings UI. OpenAI does not currently document a hand-edited filename or public file syntax for this feature, so the supported way to manage it is through the app rather than by editing .codex/ files directly. You can still commit the generated files if you want shared setup and actions.

Codex cloud workflows often rely on connected repositories and integrations such as GitHub, Slack, and Linear. Skills can also declare tool dependencies, including MCP servers, through optional metadata so the UI can guide setup more clearly.

Up to this point, you have the part of .codex/ most teams use day to day. What follows is the extension layer.

Advanced .codex/ capabilities

The rest of .codex/ is the extension and integration layer. You only need it when you want external tools, lifecycle automation, or legacy command surfaces. Most teams can understand the core .codex/ model first and come back to this later.

MCP server configuration

MCP is the main extension mechanism. Codex acts as a Model Context Protocol (MCP) client. MCP servers extend what Codex can do by exposing external tools, data sources, and integrations such as filesystem access, GitHub, databases, browser automation, or documentation services. MCP configuration lives in config.toml at both the user level (~/.codex/config.toml) and the project level (.codex/config.toml, loaded only for trusted projects).

You need this when Codex has to reach outside the repo and use external tools or data sources.

Each server is declared under [mcp_servers.]. Most teams only need to keep four things in view:

Image

A minimal example looks like this:

yaml

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
enabled_tools = ["search_repositories", "get_file_contents"]

For a remote server, you typically replace the command with a url and optional auth headers or bearer-token env vars.

If you do not want to edit TOML by hand, codex mcp list, codex mcp add, codex mcp get, and codex mcp remove manage user-level entries in ~/.codex/config.toml. Project-scoped servers are usually clearer when edited directly in project .codex/config.toml.

Custom agent TOML files can also include their own [mcp_servers] tables, which is useful when one specialised agent needs a tool that the rest of Codex should not see. Codex itself can also run as an MCP server via codex mcp-server.

Because the CLI, desktop app, and IDE extension all read the same config.toml, MCP server configuration only needs to be done once. The references section points to the full schema and official docs if you need every field.

Hooks Hooks are different. They let you inject custom scripts into Codex’s cycle of planning, running tools, observing results, and continuing. They complement plugins: plugins package reusable capabilities, while hooks let you enforce policies, add logging, or customise behaviour at specific lifecycle points.

You need hooks when you want lifecycle automation or enforcement around what Codex is doing beyond just adding more tools.

Hooks are currently disabled on Windows and are off by default. To enable them, add this to config.toml:

yaml

[features]
codex_hooks = true

Codex looks for hooks.json next to active config layers, typically ~/.codex/hooks.json and/.codex/hooks.json. Hook files organise handlers by event, matcher, and command. The main events are SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, and Stop.

Common uses include:

  • Logging and analytics
  • Prompt scanning for secrets
  • Guardrails around shell commands
  • Post-run validation or feedback
  • Forcing an additional pass before Codex stops

Hooks can influence behaviour by returning JSON to Codex, for example to deny a command or inject follow-up guidance. They are useful guardrails, but not a perfect enforcement boundary. A determined model can sometimes work around them indirectly. The references section links to the full event list and JSON schema.

Worktrees and **$CODEX** _HOME/worktrees/

If you use the desktop app, worktrees matter a lot. The app uses git worktrees to run multiple threads and automations in parallel without interfering with your local checkout. A git worktree is simply a second checkout of the same repository: it has its own files on disk, but it shares the underlying git history and branch metadata with the main repo.

This is an app feature. If you only use the CLI, this section is mostly background rather than something you need to configure directly.

Again, the scope split matters:

  • Project .codex/ stores the app-generated local-environment config that tells the Codex app how to set up new worktrees
  • User ~/.codex/worktrees/ stores the app-managed checkout copies themselves

When you start a new thread on a worktree, Codex creates a separate checkout from the selected branch, can apply uncommitted changes from the source checkout, and often uses a detached HEAD state, meaning the worktree is pinned to a specific commit rather than actively attached to the branch name, to avoid checkout conflicts across multiple working copies.

There are two broad worktree modes:

Image

Codex-managed worktrees are the lightweight default for individual threads. Permanent worktrees are the long-lived version you keep around on purpose.

The app can hand work off between the local checkout and a worktree. Automations can also run either in the local project or in dedicated background worktrees. For git repositories, worktree mode is usually safer because it isolates automation changes from active development work.

Worktrees inherit trust from the main repository rather than needing a separate trust decision. In workspace-write mode, their .git pointer files, small files that point back to the repo’s real git metadata, remain protected by the sandbox just like .git/ in a normal checkout.

Because a worktree only starts with files that exist in Git, it may not contain dependencies, build outputs, or other ignored state. That is where local environments come in: they let the Codex app run the project’s saved setup scripts automatically when a new worktree is created. If a worktree behaves strangely, the first thing to check is usually whether those setup scripts are present and still correct.

Legacy custom prompts as commands

Codex used to support custom prompts that turn Markdown files into reusable slash commands, but that feature is now deprecated in favour of skills.

Most readers can treat this as migration context rather than an active part of the setup model.

Deprecated custom prompts live under ~/.codex/prompts/ and can be invoked as /prompts: in the CLI and IDE extension after restart. They support YAML frontmatter metadata blocks at the top of the file, and placeholder substitution such as

$ARGUMENTS, $1..$9, and KEY=value.

For practical use today:

  • Use skills for shareable, structured workflows and for workflows you want Codex to invoke implicitly
  • Use custom prompts only for legacy workflows or lightweight personal shortcuts that do not need implicit invocation

Addendum: When .agents/ belongs alongside .codex/

So far the focus has been .codex/, because that is the Codex-specific part of the setup. Once that is clear, the remaining question is why .agents/ exists at all. .agents/ enters the picture when you also want a cross-agent shared layer in the same repository or home directory. You add .agents/ alongside .codex/ when Codex-specific configuration is not enough on its own, and you also want portable skills or plugin marketplace entries that other agents can understand.

.codex/ is Codex-specific configuration. .agents/ is a cross-agent shared directory that multiple coding agents recognise. It exists at both the repository level (.agents/ at the repo root) and the user level ($HOME/.agents/ or ~/.agents/). Codex treats it as a first-class directory: the skills loader, the plugin marketplace system, and the sandbox all reference it directly.

Directory structure plaintext

your-repo/
└── .agents/
    ├── skills/
    │   └── code-review/
    │       ├── SKILL.md
    │       ├── references/
    │       ├── scripts/
    │       ├── assets/
    │       └── agents/openai.yaml
    └── plugins/
        └── marketplace.json

skills-lock.json

~/.agents/
├── skills/
├── plugins/
│   └── marketplace.json
└── .skill-lock.json

.agents/ exists separately from .codex/ so skills and marketplace files can stay portable across different agents beyond Codex alone. That shared location follows the same convention, which is why other agents can recognise it too.

Skills Skills are reusable workflow packages. Each skill lives in its own directory with a required SKILL.md file that contains YAML frontmatter, metadata at the top of the file between --- lines, plus the instructions themselves. Optional directories such as scripts/, references/, assets/, and agents/openai.yaml add helper scripts, reference material, images, and richer metadata.

You need this section when you want shared workflows that are richer than a plain AGENTS.md note and more portable than Codex-only config.

For most readers, the key frontmatter fields are simple:

  • description is required and drives skill matching
  • name is optional and defaults to the directory name
  • optional metadata can provide shorter descriptions or mark a skill as internal

A minimal SKILL.md looks like this:

markdown

---
name: code-review
description: Review code changes for style, correctness, and test coverage
---

# Code Review

Instructions the agent follows when this skill is activated.

The optional agents/openai.yaml sidecar can add UI metadata, MCP dependencies, and policy such as whether implicit invocation is allowed. If it is missing or malformed, the skill still loads from SKILL.md alone.

Codex can invoke skills in three ways:

  • Explicitly, for example by $-mentioning a skill
  • Implicitly when it detects commands or file reads inside the skill’s own directory
  • By description match, when the task clearly matches a skill’s description

For current setups, treat .agents/skills/ as the main repo location and ~/.agents/skills/ as the personal one. Older references may still mention .codex/skills. One practical edge case is file encoding: if SKILL.md seems correct but will not load, save it as UTF–8 without BOM.

Why a skill shows up here

This is the part that matters when a skill appears in one repo but not another, or when Codex picks up a skill you forgot was installed.

Codex discovers repo skills by walking from the current working directory up to the project root and looking for .agents/skills/. It also loads user-level skills from ~/.agents/skills/, plus admin, system-bundled, and plugin-provided skill roots. Symlinks, filesystem shortcuts that point somewhere else, are supported because the skills CLI often installs that way.

Specific skills can be enabled or disabled in config.toml by name or path. Codex also protects .agents/ with the same sandbox treatment as .git/ and .codex/, so in workspace-write mode it is normally read-only unless you explicitly approve changes.

The .agents/plugins/marketplace.json file registers plugins for discovery. Codex reads marketplace files from the official curated source, the repo-level marketplace, and the user’s personal marketplace.

The

skills CLI, used via npx skills, manages the shared skills directory and registry. For most teams, the commands that matter are:

bash

npx skills add vercel-labs/agent-skills
npx skills list
npx skills check
npx skills update
npx skills init my-skill

It treats .agents/skills/ as the shared project-level directory for many agents, including Codex. Project installs are tracked in skills-lock.json, which is the project lock file and is meant to be committed; global installs are tracked in ~/.agents/.skill-lock.json. Codex can also migrate some older agent setups into .agents/skills/ and translate instruction files such as CLAUDE.md into AGENTS.md.

Relationship to .codex/

The split remains clean: Codex-specific configuration such as config.toml, rules, agent definitions, hooks, and files the app manages stays in .codex/; shared, portable skills and marketplace files go in .agents/.

Where plugins fit

Plugins only make sense once both .codex/ and .agents/ are in view, because they are the point where distribution cuts across the boundary between them.

You need plugins when you want to package and distribute skills, app integrations, or MCP setup as one installable unit.

Plugins sit across the .codex/ and .agents/ split rather than living cleanly inside one side of it. The manifest lives in .codex-plugin/plugin.json, discovery usually happens through .agents/plugins/marketplace.json, installed plugin caches live under ~/.codex/plugins/cache/, and on/off state is stored in ~/.codex/config.toml.

A plugin is an installable bundle that packages skills, app integrations, and MCP server configurations into a single distributable unit. Skills are the authoring format for workflows. Plugins are the distribution format.

Plugin structure plaintext

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── .app.json
├── .mcp.json
└── assets/

Only .codex-plugin/plugin.json is required. A minimal manifest names the plugin, declares its version and description, and points to bundled skills or optional app and MCP config.

Discovery, installation, and invocation

Codex discovers plugins from three marketplaces: the official curated directory, the repo’s .agents/plugins/marketplace.json, and the user’s ~/.agents/plugins/marketplace.json.

When a plugin is installed, Codex caches it under ~/.codex/plugins/cache/ and loads from that cached copy. Local plugins typically use the version label local.

Plugins can be installed through the app’s plugin directory or from the CLI via /plugins. For local authoring, the built-in

$plugin

-creator skill can scaffold the manifest and marketplace entry. Plugin enable/disable state is stored in ~/.codex/config.toml.

Plugins can then be used either by description, where you ask for the outcome you want, or explicitly with @-mention.

How plugins relate to the rest

Plugins sit above the lower-level pieces in this guide. Skills remain the authoring format for reusable workflows. MCP servers remain the tool-connection layer. Rules still apply to commands triggered through plugins. AGENTS.md still provides project instructions; it complements plugins rather than being bundled inside them.

If you want to build a plugin manually, the path is straightforward: create the plugin folder, add .codex-plugin/plugin.json, place any bundled skills under skills/, optionally add app or MCP config, then register the plugin in a marketplace file.

References

Configuration, agents, and rules

AGENTS.md and system prompts

MCP and hooks

Plugins

Skills and .agents/

Desktop app: worktrees, environments, and automations