1.1 Mental map — Claude Code vs Codex

🎯What you get in this module

Leave knowing what each piece (CLAUDE.md, AGENTS.md, skills, sub-agents, MCP) means in each runtime. You’ll never be lost reading the docs for one without a mental reference for the other.

Detailed content

🤖 What a coding agent is (and what it ISN'T)

A coding agent is a LLM that runs an autonomous loop: reads code, plans an action, edits files, runs commands in the terminal, observes the result, and decides the next step — all without you dictating every move. It's not autocomplete or a chatbot. It's an iterative collaborator.

✓ Is a coding agent

✓Carries out a task end to end (read, plan, act, review)
✓Has access to tools (shell, file edit, web, MCP)
✓Maintains session context and iterates
✓You can delegate to specialized sub-agents
✓Runs event hooks (PreToolUse, Stop, etc.)

✗ Is not a coding agent

✗Autocomplete (Copilot inline) — suggests a line
✗Pure chatbot (standard ChatGPT) — no tools
✗Linter/formatter — static rule
✗Snippet expander — fixed template
✗Code search — queries only, takes no action

🔬The ReAct loop (Reason + Act)

It’s the engine behind any coding agent. It runs in short cycles:

1. Observe — read the message, available tools, and context

2. Think — what’s the next action that will bring you closer to the goal?

3. Act — execute the action (read file, run bash, edit, etc.)

4. Observe — action result. Return to step 2 or stop.

Key concepts

ReAct loop
Iterative Reason + Act

Tool use
Bash, Edit, Read, Web, MCP

Permissions
Allow/deny/ask by tool

Hooks
Harness events

📘 CLAUDE.md vs AGENTS.md — the “project system prompt”

Both agents read a Markdown file at the project root in start of every session and inject into the system prompt. Same function, two names:

Aspect

Claude Code

Codex

File in the root

CLAUDE.md

AGENTS.md

Global version

~/.claude/CLAUDE.md

~/.codex/AGENTS.md

Per-folder version

✓ Yes, concatenated

✓ Yes, similar

Dynamic injection (backtick-bang)

✓ Supports

✗ Does not support

Ideal size

~2-3 KB

~1-2 KB (more conservative)

💡Practical tip

Keep CLAUDE.md/AGENTS.md focused on 3 things:

Build/test/lint commands at the top (literal format for copying)
Non-obvious code conventions (don’t repeat what the linter already enforces)
Links to in-depth internal docs (ADRs, runbooks)

Key concepts

Hierarchy
Global → project → subdir

Concatenation
Everything goes into the system prompt

Precedence
Specific beats generic

Size
Watch out for inflation

📁 .claude/ vs .codex/ vs .agents/ — the anatomy

Hidden folder in the project where the agent customization lives. Claude uses a single folder. Codex uses two folders with separate responsibilities. This is the most important structural difference:

Claude Code — a single folder

.claude/
├── CLAUDE.md            ← também pode ficar na raiz
├── settings.json        ← permissões, modelo, env, hooks
├── settings.local.json  ← override local (.gitignore)
├── agents/              ← sub-agents em Markdown
│   ├── code-reviewer.md
│   └── doc-writer.md
├── skills/              ← skills auto-invocáveis
│   └── my-skill/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── commands/            ← slash commands
│   └── review.md
└── hooks/               ← scripts de evento

Codex — two folders, distinct responsibilities

.codex/                  ← config específica do Codex
├── config.toml          ← settings em TOML
├── agents/              ← sub-agents em TOML
│   ├── code-reviewer.toml
│   └── doc-writer.toml
└── commands/            ← slash commands específicos

.agents/                 ← spec ABERTA (compartilhada)
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── agents/openai.yaml  ← sidecar Codex
        ├── scripts/
        └── references/

AGENTS.md                ← na raiz, system prompt do projeto

⚠️Migration pitfall #1

People coming from Claude put the skill in .codex/skills/ thinking it’s the direct equivalent of .claude/skills/. Wrong. Codex skill lives in .agents/skills/ — because .agents/ is the convention used by the open Agent Skills spec, and Codex follows it.

Key concepts

Hidden folder
. at the beginning = hidden

Convention
Right Name, Right Folder

Config × extension separation
.codex vs .agents

Partial gitignore
Commit the skill, ignore local files

🧩 Skills — the shared concept, with small differences

A skill is a "packaged expertise": folder with SKILL.md + YAML frontmatter + Markdown body + conventional folders. Both runtimes implement the Agent Skills standard (agentskills.io), so the core is portable. Where they differ:

The 4 pillars that ALWAYS match

File Name SKILL.md — always

Frontmatter fields name e description in YAML

Body in standard Markdown

Folder conventions scripts/, references/, assets/

Minimal SKILL.md

---
name: minha-skill
description: Use when you need to process X. Common triggers: "process X", "clean up Y".
---

# My Skill

Markdown instructions explaining how to perform the task.

You can reference relative files: see `references/exemplo.md` for more details.

🔷 Claude Code adds

• allowed-tools in frontmatter
• disable-model-invocation (explicit opt-in)
• Dynamic injection with `!comando` (backtick-bang)
• Automatic invocation by description
• Slash: /nome-skill

🟣 Codex adds

• Sidecar agents/openai.yaml (branding, MCP)
• Hidden ~8K-character limit on description
• No native dynamic injection (use fallback prose)
• Automatic invocation by description (also)
• Dollar: $nome-skill

🦜This is exactly where polyskill comes in

You write ONE skill in the portable format. polyskill generates two versions: one with Claude’s conventions, the other with Codex’s conventions (including the sidecar and description adjustment). See the Track 5 for details.

Key concepts

SKILL.md
Canonical file

YAML frontmatter
name + description

Semantic match
Activation by description

Sidecar
Specific metadata

👥 Sub-agents — two opposing philosophies

A sub-agent is a "specialized persona" that the main agent can delegate tasks. This is where the trickiest difference between Claude Code and Codex lies — it catches almost everyone who migrates:

🔷

Claude Code — automatic invocation

Markdown format in .claude/agents/. The main agent READS the description and decides whether to delegate, on its own.

You write a description rich in triggers ("Use proactively when..."), and the main Claude agent discovers the sub-agent when the context matches. You can run several in parallel via the Task tool.

🟣

Codex — explicit invocation

TOML format in .codex/agents/. You HAVE to call it by name in the prompt.

Description helps you remember, but it doesn’t trigger automatically. “Use the agent code-reviewer to review X” — without that, it won’t run. Trade-off: more predictable, less ergonomic.

🚨The #1 mistake people make when migrating from Claude → Codex

Copy the sub-agent, translate it to TOML, and expect it to run on its own like it does in Claude. Doesn't trigger. You spend hours thinking "it’s broken"—it isn’t. Codex requires explicit invocation by design.

Key concepts

Auto-dispatch
Claude reads the description and decides

Explicit call
Codex requires a name

Isolation
Separate context

Parallelism
Multiple at once

🔌 MCP — the protocol they both speak

Model Context Protocol (MCP) is the common denominator of the stack. An open standard for connecting LLMs to external tools (Slack, Gmail, GitHub, databases). An MCP server runs as an independent process — Claude and Codex speak the same protocol.

The MCP architecture

┌──────────────┐ ┌──────────────┐

│ Claude Code │────┐ │ MCP Server │

└──────────────┘ │ │ (slack-api) │

├──→ │ │

┌──────────────┐ │ │ Exposes tools │

│ Codex CLI │────┘ │ via stdio │

└──────────────┘ └──────────────┘

Both clients use the SAME server.

Server is independent, declared in the client config.

🔷 Declaration in Claude Code

// .mcp.json
{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@mcp/slack"],
      "env": { "TOKEN": "$SLACK_TOKEN" }
    }
  }
}

🟣 Declaration in Codex

# config.toml
[mcp_servers.slack]
command = "npx"
args = ["-y", "@mcp/slack"]

[mcp_servers.slack.env]
TOKEN = "${SLACK_TOKEN}"

💡The good news

Configured an MCP server once? Both runtimes can use it. Only the declaration format changes (JSON×TOML). Server, env, exposed tools — all the same. This is the part of the stack that survives the MOST across runtimes.

Key concepts

Open standard
MCP is a spec, not proprietary

Independent server
Separate process

stdio vs HTTP
Two transports

mcp__server__tool
Naming convention

🎯Module summary

✓

Coding agent = ReAct loop — it's not autocomplete, it's not a chatbot. It's an iterative collaborator.

✓

CLAUDE.md ≡ AGENTS.md — same function, two names. Global → project → subdirectory hierarchy.

✓

.claude/ one folder; .codex/ + .agents/ two — Codex separates proprietary config from the open spec.

✓

Skills = SKILL.md + YAML + body — 4 shared pillars; the rest is runtime-specific.

✓

Sub-agents: Claude invokes automatically, Codex requires a name — migration mistake #1.

✓

MCP is the common denominator — the server is independent; only the declaration changes.

Next module:

1.2 — Why use both together (complementarity, redundancy, tool-agnostic)

← Back to Track 1 Next: 1.2 →