File-by-file comparison

Claude Code vs Codex project configuration

Claude Code and OpenAI Codex solve many of the same repository-configuration problems, but their filenames and schemas are not interchangeable. Map the purpose of each layer before you port it.

Configuration map

CLAUDE.md and AGENTS.md serve a similar purpose

Both are places for durable repository guidance: real commands, non-obvious architecture, conventions, boundaries, and verification expectations. Both support more specific guidance closer to the code it governs.

Renaming a file does not complete a migration. Review content for product-specific commands, tool names, invocation syntax, and assumptions about how nested guidance loads.

Settings must be translated, not renamed

Claude Code uses JSON project settings. Codex uses TOML configuration and loads project-scoped .codex layers only for trusted projects. Model choice, approvals, sandboxing, MCP, hooks, and agent roles therefore need a deliberate mapping.

Start from desired behavior—such as “allow tests locally but keep publishing interactive”—then implement it using the destination product’s current settings model.

Skills are the most portable concept

Both products use SKILL.md-based workflows. Directory locations differ, and product-specific metadata or tool assumptions may still need changes.

1. Copy one skill, not the entire library.
2. Check its metadata and referenced files.
3. Replace product-specific tool names and commands.
4. Invoke it explicitly with a small task.
5. Test automatic selection separately if you depend on it.

Hooks share a goal, not a configuration format

Both systems can run lifecycle hooks around agent activity. Their event schemas, trust behavior, configuration files, and output contracts differ. Port the policy and rewrite the integration for the destination product.

A practical migration sequence

1. Extract durable facts. List commands, architecture boundaries, generated paths, and completion checks independently of either product.
2. Create destination guidance. Put only frequently needed facts in CLAUDE.md or AGENTS.md.
3. Translate permissions and sandbox behavior. Rebuild the policy in the destination settings format.
4. Port one workflow at a time. Skills are a better first target than hooks or specialized agents.
5. Reimplement deterministic controls. Verify hook events, inputs, outputs, and trust behavior from current docs.
6. Test in a disposable branch. Exercise allowed, denied, and failing paths before consequential work.

Using both in the same repository

You can keep both configuration systems in one repository. Keep each entry file short and consistent, and avoid silently giving the two agents contradictory commands or definitions of done.

repo/
├── AGENTS.md
├── CLAUDE.md
├── docs/verification.md
├── .claude/settings.json
└── .codex/
    ├── config.toml
    └── hooks.json

A shared human-readable architecture or verification document can reduce duplication, but keep critical commands and safety boundaries visible in each product’s active guidance.

Current documentation

• Anthropic: the .claude directory
• OpenAI: custom instructions with AGENTS.md
• OpenAI: Codex configuration basics

References rechecked July 16, 2026. Verify behavior in the version and environment you deploy.

Configuration FAQ