Why Your Codex Config Isn't Working: The .codex/ Folder Problem

My Codex config wasn’t applying. I edited config.toml, added rules to AGENTS.md, re-read the docs twice. Nothing changed. The agent kept ignoring everything.

I finally pulled apart the entire folder structure. The problem wasn’t what I wrote in the files. It was where the files were sitting.

Two goals live in one repo

Codex is trying to solve two things at once. One is rapid experimentation with its own beta features. The other is cross-agent compatibility, a shared standard that tools like Claude Code or OpenCode can also read.

This split produces two folders.

.codex/ is the Codex-only config space. Sandbox policies, approval rules, runtime guardrails go here. .agents/ is the shared format. Skills, plugins, and the marketplace registry live on this side, readable by any agent that follows the standard.

I didn’t know about this split at first. I dropped a SKILL.md file into .codex/ and the skill never loaded. Moving it to .agents/skills/ fixed it instantly. The boundary is strict: if another agent should be able to read it, it belongs in .agents/. Everything else goes in .codex/.

Both folders get read-only protection in workspace-write mode, same as .git/.

Project config and user config share the same name

There’s a .codex/ in your project root and a ~/.codex/ in your home directory. They do completely different things.

Project .codex/ holds settings you share with your team: sandbox policies, approval workflows, agent definitions. ~/.codex/ holds personal state: auth tokens, command history, worktree management files.

I made a reviewer agent in ~/.codex/agents/ and couldn’t figure out why teammates didn’t have it. It only existed on my machine. Moving the file to the project’s .codex/agents/reviewer.toml meant it traveled with the repo on clone.

The confusion gets worse because Codex is still in beta. Desktop app worktree files, session data, and auth credentials all pile into ~/.codex/ with no clear separation. The boundary between “my stuff” and “project stuff” blurs more than it should.

Config priority follows a specific order: managed config takes precedence over session overrides, which take precedence over user config. When something isn’t applying, check which level you’re editing.

Trust level is the real gate

This is where most people get stuck, and I burned real time on it before understanding why.

Codex does not load project .codex/ from untrusted repos. At all. You can edit config.toml as much as you want in a freshly cloned repo and nothing will apply. The file is there, the syntax is correct, and Codex silently ignores all of it.

The reason makes sense once you see it. .agents/ opens a path for external skills to flow into your environment. Any repo could ship a malicious config. So Codex made the trade: wider compatibility with the agent ecosystem, but stricter trust verification for repo-provided settings. You have to explicitly mark a project as trusted before its .codex/ config activates.

Set projects.<path>.trust_level = "trusted" in your user config. Network access is blocked by default too, with web search offering three modes: cached, live, or disabled. Even in workspace-write mode, .git/ and .codex/ stay write-protected.

I spent about an hour editing a project config.toml that was being completely ignored because I hadn’t set the trust level. No error message, no warning. Just silence. This is probably the single most common Codex setup frustration, and better error messaging here would save a lot of people a lot of time.

The complexity isn’t accidental

The folder structure is messy, but not randomly. Codex is chasing two goals that pull in opposite directions.

Fast beta iteration means .codex/ accumulates config files, rule definitions, hooks, and app management artifacts at a pace that outstrips documentation. Cross-agent compatibility means .agents/ needs a separate, portable structure for skills and marketplace content. And because .agents/ opens the door to external code, the trust verification layer had to exist.

When you’re unsure where a file goes, ask one question: is this Codex-specific, or should other agents read it too? The first answer points to .codex/. The second points to .agents/.

When your config isn’t working, don’t start by editing the file contents. Check which folder it’s in and whether the repo is trusted. That’s where the problem almost always is.