Claude Code ↔ Codex CLI Cheat Sheet

(Been using Claude Code and Qwen Code for most of my projects so far, but heard good things about Codex, so I am just sharing the Cheat Sheet I am using, prepared by various AI agents.)

One-page reference for developers using both tools. Verified against current official docs.

🚀 Session lifecycle

🔍 Inspect & review changes

Portable fallback for both: git diff, git diff --stat, git diff --check

🔐 Permissions & safety

Claude Code permission modes (docs):

• Shift+Tab cycles: default → acceptEdits → plan
• /plan enters plan mode directly
• /permissions manages allow/ask/deny rules

Codex sandbox + approvals (docs) — two orthogonal axes:

# ~/.codex/config.toml
sandbox_mode    = "workspace-write"   # read-only | workspace-write | danger-full-access
approval_policy = "on-request"        # untrusted | on-request | never

• /plan toggles plan mode
• /approve approves one retry after an auto-review denial
• Sandbox is OS-enforced — stronger than Claude’s approval layer

⚠️ bypassPermissions ≠ danger-full-access. First skips prompts; second removes the OS sandbox. Different blast radius.

⌨️ Keyboard shortcuts

📁 File layout (portable repo)

project/
├── AGENTS.md              # Universal — both tools read this
├── CLAUDE.md              # Thin adapter: @import AGENTS.md
├── .agent/                # Tool-neutral collateral
│   ├── HANDOFF.md
│   ├── DECISIONS.md
│   └── workflows/*.md
├── .agents/skills/        # Codex skills
├── .claude/
│   ├── skills/            # Claude skills
│   ├── agents/            # Subagents
│   ├── settings.json      # Team, checked in
│   └── settings.local.json
├── .codex/
│   ├── hooks.json
│   └── config.toml
├── .mcp.json              # Claude MCP (project-scope)
├── scripts/               # Portable verbs
└── Makefile

Golden rule: AGENTS.md = source of truth. CLAUDE.md imports it via @AGENTS.md.

To make Codex fall back to CLAUDE.md:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]

🔧 Skills & subagents

Shared SKILL.md frontmatter:

---
name: review
description: When and how this skill triggers.
---

Skill instructions here.

🔌 MCP servers (not auto-shared between tools)

Claude Code — .mcp.json at project root:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN" }
    }
  }
}

Codex — ~/.codex/config.toml or .codex/config.toml:

[mcp_servers.github]
command = "npx"
args    = ["-y", "@modelcontextprotocol/server-github"]
env     = { GITHUB_PERSONAL_ACCESS_TOKEN = "$GITHUB_TOKEN" }

• Manage in-session: /mcp (both tools)
• Configure both — one config does not populate the other

☁️ Delegation & cloud

Codex has the more mature cloud-delegation model; Claude has the richer local harness.

🔄 Switching protocol (in 5 steps)

1. Commit or stash — clean working tree.
2. Write .agent/HANDOFF.md — objective, files changed, decisions, verification, next action.
3. Verify shared files — AGENTS.md current; CLAUDE.md still imports it; MCP servers present in both configs.
4. Start new tool fresh — read HANDOFF, run /status, git status, ./scripts/agent-review.
5. Run make verify before any change.

📝 .agent/HANDOFF.md template

# Agent handoff

## Objective
## Current status
## Files changed

- `path/to/file.py`: what changed
## Decisions
## Verification

- make lint  — passed
- make test  — 142 passed
## Known issues
## Next action
1.
2.

💬 Prompt patterns that survive tool changes

Before editing (both tools):

Do not edit files yet. Inspect the repository, identify relevant files,
list assumptions and risks, and propose a numbered implementation plan.
Wait for approval.

Review:

Review the current git diff. Prioritize correctness, security, data-loss risks,
missing tests, and backwards-compat problems. Do not modify files.
Report by severity with file:line references.

Handoff:

Write .agent/HANDOFF.md with objective, decisions, changed files,
verification results, known issues, and next steps.

Capability check (start of session):

Before beginning, report:

1. Which instruction files you loaded.
2. Which tools/MCP servers are available.
3. Your current permission/sandbox mode.
4. Verification commands you can run.

⚡ Portable shell verbs

Teach both tools the same vocabulary — survives every rename:

make verify       # lint + test + review
make test
make lint
make review
./scripts/agent-status   # git status + branch + diff --stat
./scripts/agent-review   # diff --check + full diff

Then either agent takes: “Run make verify. Report failures with file and line numbers.”

🚨 Emergency reset

Ctrl-C, Ctrl-C          # cancel
git status              # what did the agent touch?
git stash               # or: git checkout -- <file>
git worktree remove ..  # if in a worktree

⚠️ Top pitfalls

1. ❌ /clear and /resume don’t exist as Codex slash commands → use /new and codex resume
2. ❌ Codex doesn’t read CLAUDE.md by default → add to project_doc_fallback_filenames
3. ❌ MCP servers aren’t shared between tools → configure both
4. ❌ bypassPermissions ≠ danger-full-access → different blast radius
5. ❌ Shift+Tab and Ctrl-O do different things in each tool
6. ❌ Codex quarantines new hooks → use /hooks to trust them
7. ❌ mv CLAUDE.md AGENTS.md is not a migration → hooks, skills, MCP, subagents all lost
8. ❌ Never run both agents on the same working tree → use git worktree

🔗 Verify against your installed version

Claude Code:  /help   (or press ? in a session)
Codex CLI:    type / in composer, or codex --help

Interfaces change fast — re-verify these commands whenever either tool updates.