# Why Your Codex Config Isn't Working: The .codex/ Folder Problem > Author: Tony Lee > Published: 2026-04-01 > URL: https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ > Reading time: 4 minutes > Language: en > Tags: codex, openai, ai-agents, developer-tools, configuration ## Canonical https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ ## Rollout Alternates en: https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ ko: https://tonylee.im/ko/blog/codex-folder-structure-why-config-breaks/ ja: https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ zh-CN: https://tonylee.im/zh-CN/blog/codex-folder-structure-why-config-breaks/ zh-TW: https://tonylee.im/zh-TW/blog/codex-folder-structure-why-config-breaks/ ## Description I edited config.toml, wrote rules in AGENTS.md, and nothing stuck. Turns out the folder structure itself was the issue, not my settings. ## Summary Why Your Codex Config Isn't Working: The .codex/ Folder Problem is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - Two goals live in one repo - Project config and user config share the same name - Trust level is the real gate - The complexity isn't accidental ## Content 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..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. ## Related URLs - Author: https://tonylee.im/en/author/ - Publication: https://tonylee.im/en/blog/about/ - Related article: https://tonylee.im/en/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/en/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/en/blog/codex-inside-claude-code-openai-plugin-strategy/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/en/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.