Codex vs Claude Code: instructions, skills, MCP, permissions and headless runs compared

Codex and Claude Code are the two terminal coding agents most teams evaluate side by side. On paper they look alike: both read your repository, edit files, run commands, load skills and talk to MCP servers. The differences that matter day to day are in how you configure them, and that is what this guide compares. It does not rank models or quote benchmarks, which change faster than any article.

At a glance

	Codex	Claude Code
Made by	OpenAI	Anthropic
Always-on instructions	AGENTS.md, merged from the repo root down to the working directory	CLAUDE.md in the project, plus ~/.claude/CLAUDE.md for you
Skills (Agent Skills format)	.agents/skills, ~/.agents/skills, /etc/codex/skills	.claude/skills, ~/.claude/skills
Configuration file	~/.codex/config.toml (TOML), project .codex/config.toml	settings.json in ~/.claude/ and .claude/ (JSON)
Add an MCP server	codex mcp add or [mcp_servers] in config.toml	claude mcp add, or a project .mcp.json
Safety model	OS sandbox (read-only, workspace-write, danger-full-access) plus an approval policy	Permission rules (allow, ask, deny) plus permission modes
Headless runs	codex exec	claude -p
Packaging	Plugins and marketplaces	Plugins and marketplaces

Instructions: AGENTS.md and CLAUDE.md

Both agents read a Markdown file of project rules at the start of every session: the test command, the package manager, conventions a newcomer would miss.

• Codex reads AGENTS.md. It walks from the repository root down to your working directory and merges every AGENTS.md it finds, so a monorepo can keep package rules next to the package. There is a size cap, covered in the AGENTS.md guide.
• Claude Code reads CLAUDE.md, from the project and from ~/.claude/CLAUDE.md, and can pull in other files with @path imports.

If your team uses both, keep one source of truth. Write the rules in AGENTS.md and make CLAUDE.md a one-line import:

@AGENTS.md

Add anything Claude-specific below that line. Both agents then follow the same rules, and a reviewer only has one file to keep current.

Skills: the same format, different folders

This is where the two agents are closest. Both implement the open Agent Skills specification: a skill is a folder with a SKILL.md file whose name and description are always visible to the agent, and whose body loads only when a task matches. The same folder works in both. Only the location differs:

Scope	Codex	Claude Code
Project	.agents/skills/<name>/	.claude/skills/<name>/
Personal	~/.agents/skills/<name>/	~/.claude/skills/<name>/
Machine-wide	/etc/codex/skills/<name>/	Distribute through a plugin

To share one set, keep the skills in .agents/skills and link that folder for Claude Code:

mkdir -p .claude
ln -s ../.agents/skills .claude/skills
git add .agents/skills .claude/skills

For personal skills the same idea works with ln -s ~/.agents/skills ~/.claude/skills, provided ~/.claude/skills does not already exist. On Windows, where symlinks need extra rights, copy the folder with a small sync script instead.

Invoking a skill by name differs slightly. In Codex you mention it with $skill-name or pick it from /skills; in Claude Code you name the skill in your request. In both, a well-written description lets the agent pick the skill on its own, which is why the description guide matters more than either syntax.

MCP servers

Both agents speak the Model Context Protocol, so the same server binaries and URLs work in either. Configuration is where they differ:

# Codex: stored in ~/.codex/config.toml
codex mcp add docs -- npx -y @modelcontextprotocol/server-filesystem ./docs

# Claude Code: local scope by default; --scope project writes .mcp.json for the team
claude mcp add docs -- npx -y @modelcontextprotocol/server-filesystem ./docs

Codex keeps servers in config.toml under [mcp_servers.<name>], with tool allow-lists and approval settings next to them; the Codex MCP guide covers every key. Claude Code lets a project commit .mcp.json so everyone gets the same servers. Either way, treat a third-party MCP server like any dependency: it runs code on your machine.

Safety: sandbox versus permissions

This is the largest practical difference.

Codex separates two controls. The sandbox decides what commands can touch at the operating-system level: read-only, workspace-write (edit the workspace, ask before anything outside it or before using the network) or danger-full-access. The approval policy decides when Codex stops to ask. The default in a git repository is workspace-write with on-request approvals. The CLI guide lists the flags for each combination.

Claude Code centres on permission rules written in settings.json, such as allowing Bash(npm run test:*) while denying edits to .env, and on permission modes that set how much it may do without asking, from asking for every edit to planning only. It also offers sandboxing for shell commands; check its documentation for the current platforms.

In practice: Codex’s sandbox gives you a hard boundary by default and you widen it deliberately; Claude Code’s rules let you describe in detail which commands are routine. Both reward the same habit, which is deciding up front what the agent may do unattended in this repository.

Headless runs and CI

Both run without a person at the keyboard:

codex exec "summarise the failing tests and propose a fix"     # Codex
claude -p "summarise the failing tests and propose a fix"      # Claude Code

codex exec defaults to a read-only sandbox, and can emit JSON events and write its final answer to a file, which suits CI gates; the codex exec skill covers schemas, exit codes and scoped keys. claude -p prints the answer and can return structured output with --output-format json. Both read the same instruction files and skills as an interactive session, so a repository set up for one works headless too.

Plugins

Both agents can install plugins from marketplaces: bundles that ship skills together with MCP servers and other extensions. Plugins are how you distribute a skill set to many repositories or many people; a single repository is usually better served by a committed skills folder. See Codex plugins for the Codex side.

Which should you choose?

Pick by circumstance, not by headline:

• The account you have. Codex comes with ChatGPT plans and OpenAI API keys; Claude Code with Claude plans and Anthropic API keys. Using what your organisation already pays for avoids a procurement cycle.
• How you want safety expressed. If you want an OS-level boundary that is on by default, Codex’s sandbox is the more conservative starting point. If you want fine-grained, per-command rules checked into the repository, Claude Code’s permission rules are very expressive.
• Your editor and workflow. Both have IDE integrations and cloud or background modes. Try each on a real task from your backlog for a day, using the same AGENTS.md and skills, and compare the diffs you get.

Because instructions can be shared through an import and skills through a symlink, choosing one does not lock you in. Teams that use both keep a single AGENTS.md, a single .agents/skills folder, and the same MCP servers.

Skills for both

Every skill in this directory follows the Agent Skills specification, so it works in Codex and, once linked or copied into .claude/skills, in Claude Code. Start with the Starter Pack, or browse all skills. For skills written with Claude Code in mind, the sister site claudeskills.page has its own catalog.