Migrating Between Codex, Cursor, and Claude Code

Your team uses Cursor for daily development, but you just saw a demo where someone fired off five Codex tasks in parallel and reviewed the results in twenty minutes. Or you have been using Codex for async refactoring but need the interactive debugging that Claude Code provides. Or you want to use all three tools for different scenarios — Cursor for IDE work, Claude Code for CLI-heavy operations, and Codex for background tasks — and you need them all reading from the same conventions.

This guide covers every direction of migration between the three tools, including how to run them simultaneously without configuration conflicts.

What You’ll Walk Away With

• Configuration translation between CLAUDE.md, AGENTS.md, and .cursor/rules/
• Workflow mapping for common tasks across all three tools
• Multi-tool setup that keeps conventions synchronized
• MCP configuration migration between tools
• Decision framework for which tool to use for which task

Configuration Translation

The biggest migration task is translating your project instructions between the three formats. Each tool reads conventions from a different location.

Tool	Config Location	Format	Scope
Cursor	.cursor/rules/*.md	Multiple markdown files	Per-rule files
Claude Code	CLAUDE.md (root)	Single markdown file	Entire project
Codex	AGENTS.md (root)	Single markdown file	Entire project

From AGENTS.md to CLAUDE.md

If you are moving from Codex to Claude Code, your AGENTS.md translates almost directly to CLAUDE.md. The formats are similar — both are markdown files at the repository root that the agent reads at session start.

cp AGENTS.md CLAUDE.md

Then make these adjustments:

# CLAUDE.md adjustments after copying from AGENTS.md

## What to change:

# 1. Add workflow commands that Claude Code can run locally
## Key Commands
- npm run dev         # Start dev server
- npm run test        # Run test suite
- npm run lint        # Check linting

# 2. Remove Codex-specific sandbox instructions
# (Codex runs in an isolated sandbox; Claude Code runs on your machine)
# DELETE: "You are running in a sandboxed environment"
# DELETE: "Do not attempt to access the network"

# 3. Add interactive workflow guidance
# Claude Code supports back-and-forth conversation,
# so add instructions about when to ask for clarification
## Workflow
- For ambiguous requirements, ask for clarification before proceeding
- Use extended-thinking keywords ("think", "think harder", "ultrathink") for complex architectural decisions
- Run tests after every significant change

Tip

Copy-paste prompt for AGENTS.md to CLAUDE.md conversion:

“Read AGENTS.md and convert it to a CLAUDE.md file. Remove any Codex-specific sandbox instructions. Add a ‘Key Commands’ section listing the build, test, lint, and dev commands from package.json. Add workflow instructions for interactive development (asking for clarification, triggering extended thinking with ‘think’/‘ultrathink’ for planning, running tests incrementally). Keep all coding conventions and architecture rules unchanged.”

From CLAUDE.md to AGENTS.md

Moving from Claude Code to Codex requires making instructions more prescriptive, because Codex runs autonomously without interactive feedback.

cp CLAUDE.md AGENTS.md

Adjustments:

# AGENTS.md adjustments after copying from CLAUDE.md

## What to change:

# 1. Add explicit verification commands
## Verification
- After making changes, run: npm test
- After modifying API routes, run: npm run type-check
- After changing database schemas, run: npm run db:migrate

# 2. Add boundaries for autonomous operation
## Boundaries
- Do not modify files in migrations/ that have already been applied
- Do not delete test files
- Do not change environment variable names without updating .env.example
- Do not install new dependencies without explicit instruction

# 3. Remove interactive instructions
# DELETE: "Ask for clarification if requirements are ambiguous"
# DELETE: "Use extended-thinking keywords for complex decisions"
# Codex cannot ask questions mid-task -- it must work with what it has

# 4. Be more explicit about patterns
# Instead of "follow our component pattern", show the exact pattern:
## Component Pattern
Every new component must follow this structure:
```tsx
interface ComponentNameProps {
  // props here
}
export function ComponentName({ ...props }: ComponentNameProps) {
  // implementation
}
```

From .cursor/rules/ to CLAUDE.md or AGENTS.md

Cursor uses multiple rule files. Claude Code and Codex use a single file. Consolidate.

To CLAUDE.md

# Concatenate all Cursor rules into CLAUDE.md
echo "# Project Instructions" > CLAUDE.md
echo "" >> CLAUDE.md
for file in .cursor/rules/*.md; do
  cat "$file" >> CLAUDE.md
  echo -e "\n" >> CLAUDE.md
done

Then edit CLAUDE.md to:

• Remove duplicate headers
• Organize into logical sections (Architecture, Conventions, Testing, Workflow)
• Add a Key Commands section
• Add Claude Code-specific workflow instructions

To AGENTS.md

# Concatenate all Cursor rules into AGENTS.md
echo "# Agent Instructions" > AGENTS.md
echo "" >> AGENTS.md
for file in .cursor/rules/*.md; do
  cat "$file" >> AGENTS.md
  echo -e "\n" >> AGENTS.md
done

Then edit AGENTS.md to:

• Remove duplicate headers
• Add verification commands for each type of change
• Add explicit boundaries for autonomous operation
• Remove any interactive/GUI-specific instructions

From CLAUDE.md or AGENTS.md to .cursor/rules/

Going the other direction, split a single file into focused rule files.

mkdir -p .cursor/rules

Create separate files for each concern:

.cursor/rules/
  architecture.md        # File structure, module boundaries
  code-conventions.md    # Naming, imports, TypeScript patterns
  testing.md             # Test file structure, frameworks, coverage
  git-workflow.md        # Commit messages, PR format, branching
  api-patterns.md        # Route structure, error handling, auth

Tip

Copy-paste prompt for splitting into Cursor rules:

“Read CLAUDE.md (or AGENTS.md) and split it into separate .cursor/rules/ files. Create one file per concern: architecture.md, code-conventions.md, testing.md, git-workflow.md, and api-patterns.md. Each file should be self-contained and focused on a single topic. Remove any CLI-specific instructions and add Cursor-specific guidance where appropriate (use @codebase for searching, use Agent Mode for multi-file changes).”

MCP Configuration Migration

MCP servers are configured differently in each tool, but the underlying servers are the same.

Cursor MCP Config

Cursor stores MCP configuration in .cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Claude Code MCP Config

Claude Code uses the claude mcp add command or .mcp.json:

# Add via CLI
claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres
claude mcp add context7 -- npx -y @upstash/context7-mcp

Or create .mcp.json in your project root with the same format as Cursor:

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

Codex MCP Config

Codex has full MCP support in both the CLI and the IDE extension, and the two clients share the same configuration. Add servers with codex mcp add:

codex mcp add github --env GITHUB_TOKEN=ghp_your_token -- npx -y @modelcontextprotocol/server-github
codex mcp add postgres --env DATABASE_URL=postgresql://localhost:5432/mydb -- npx -y @modelcontextprotocol/server-postgres
codex mcp add context7 -- npx -y @upstash/context7-mcp

Or edit the config directly. Codex stores MCP servers as [mcp_servers.<name>] tables in ~/.codex/config.toml (or a project-scoped .codex/config.toml in trusted projects):

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

[mcp_servers.github.env]
GITHUB_TOKEN = "ghp_your_token"

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]

[mcp_servers.postgres.env]
DATABASE_URL = "postgresql://localhost:5432/mydb"

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

List your active servers with /mcp in the TUI. The same JSON server names map across all three tools — only the wrapper format differs (JSON for Cursor/Claude Code, TOML tables for Codex).

Migration Script

Use this pattern to translate MCP config between tools:

# Copy Cursor MCP config to Claude Code
cp .cursor/mcp.json .mcp.json

# Copy Claude Code MCP config to Cursor
cp .mcp.json .cursor/mcp.json

The JSON format is compatible between Cursor and Claude Code. Verify that environment variables (API tokens) are set correctly for each tool’s runtime environment.

Workflow Translation

Interactive Development

Task	Cursor	Claude Code	Codex
Write a new feature	Agent Mode in Composer	Describe in conversation	Create a task
Debug a failing test	Agent Mode + terminal	Conversation + automatic test runs	Task with test output
Refactor across files	Agent Mode (auto-edits)	Conversation (auto-edits)	Task (returns diffs)
Review a PR	BugBot or manual review	claude "Review PR #123"	Task: “Review changes in PR #123”
Generate tests	Agent Mode: “Write tests for…"	"Write tests for…”	Task: “Write tests for…”

Background and Parallel Work

This is where Codex excels and the other tools have limitations.

Cursor

Cursor is interactive and single-threaded. You can only run one Agent Mode conversation at a time per window. For parallel work, open multiple Cursor windows.

# Window 1: Feature development
"Implement the user profile page with avatar upload"

# Window 2: Bug fix
"Fix the race condition in the payment processing queue"

This is clunky but works.

Claude Code

Claude Code supports running multiple terminal sessions. You can have parallel conversations in separate terminal tabs.

# Terminal 1
claude "Implement the user profile page with avatar upload"

# Terminal 2
claude "Fix the race condition in the payment processing queue"

Each session is independent. Be careful about both sessions editing the same files.

Codex

Codex is built for parallel execution. Fire off multiple tasks and they run simultaneously in isolated sandboxes.

# All three run in parallel
codex "Implement the user profile page with avatar upload"
codex "Fix the race condition in the payment processing queue"
codex "Refactor the notification service to use the event bus pattern"
codex "Add comprehensive tests for the billing module"
codex "Update API documentation for all v2 endpoints"

Each task runs in its own sandbox with a full copy of your repository. No conflict between tasks. Review and merge results when they complete.

Tip

Copy-paste prompt for multi-tool workflow planning:

“I want to use Cursor for interactive development, Claude Code for CLI automation and debugging, and Codex for background refactoring tasks. Given my current project (analyze the codebase), suggest which pending tasks should go to which tool. Prioritize interactive work for Cursor, terminal-heavy operations for Claude Code, and well-defined refactoring for Codex.”

The Multi-Tool Setup

Many teams use all three tools simultaneously. The key is keeping configurations synchronized.

Synchronized Configuration

Create a script that generates all three configuration formats from a single source of truth:

scripts/sync-ai-config.sh

#!/bin/bash
# Generates .cursor/rules/, CLAUDE.md, and AGENTS.md from a single source

SOURCE="docs/ai-conventions.md"

# Generate CLAUDE.md
echo "# CLAUDE.md - Auto-generated from $SOURCE" > CLAUDE.md
echo "" >> CLAUDE.md
cat "$SOURCE" >> CLAUDE.md
echo "" >> CLAUDE.md
cat docs/claude-code-specific.md >> CLAUDE.md

# Generate AGENTS.md
echo "# AGENTS.md - Auto-generated from $SOURCE" > AGENTS.md
echo "" >> AGENTS.md
cat "$SOURCE" >> AGENTS.md
echo "" >> AGENTS.md
cat docs/codex-specific.md >> AGENTS.md

# Generate Cursor rules
mkdir -p .cursor/rules
cp docs/cursor-rules/*.md .cursor/rules/

echo "AI configurations synchronized from $SOURCE"

Keeping MCP in Sync

# Use a single MCP source and copy to both tools
cp mcp-config.json .cursor/mcp.json
cp mcp-config.json .mcp.json

Skill Portability

Skills installed via npx skills add work across Cursor, Claude Code, and Codex. The skills CLI detects which agents are installed and writes the skill files into each agent’s own skills location (for example, .claude/skills/ for Claude Code):

# Detects installed agents and installs the skill to each one
npx skills add vercel-labs/agent-skills

Decision Framework: Which Tool for Which Task

Scenario	Best Tool	Why
Writing new features interactively	Cursor	IDE integration, visual feedback, inline edits
Debugging with terminal output	Claude Code	Direct terminal access, automatic command execution
Batch refactoring (5+ independent changes)	Codex	Parallel cloud execution, no local resource usage
Code review	Claude Code or Cursor	Both have strong review capabilities
Quick prototyping	Cursor	Fastest feedback loop with inline suggestions
CI/CD debugging	Claude Code	Terminal-native, can run pipelines locally
Documentation generation	Codex	Well-defined task, does not need interaction
Security audit	Claude Code	Deep analysis needs interactive follow-up
Legacy code migration	Codex	Large-scale changes run well in parallel
Pair programming	Cursor	Most like having a collaborator in the IDE

Tip

Copy-paste prompt for tool selection:

“I need to [describe task]. I have access to Cursor, Claude Code, and Codex. Based on whether this task is interactive or async, whether it involves terminal operations, and how well-defined the requirements are, which tool should I use? Explain why.”

Migration Path by Direction

Adding Codex to an Existing Cursor + Claude Code Setup

If you already use Cursor and Claude Code and want to add Codex for parallel background work:

1. Create AGENTS.md. Start from your CLAUDE.md and add Codex-specific instructions (verification commands, boundaries, explicit patterns).

2. Identify tasks for Codex. Look for well-defined, independent tasks: test generation, documentation updates, linting fixes, dependency upgrades, API client generation.

3. Start with low-risk tasks. Use Codex for tasks where incorrect output is easy to detect: test generation (run the tests), documentation (review the text), formatting (diff the changes).

4. Review Codex output carefully. Codex runs autonomously. It does not ask clarifying questions. Double-check that the output matches your expectations before merging.

5. Scale up gradually. As you learn which tasks Codex handles well, shift more background work to it. Keep interactive and exploratory work in Cursor and Claude Code.

Moving from Codex to Cursor for Daily Development

If you have been using Codex primarily and want the interactive experience of Cursor:

1. Install Cursor. Import your VS Code settings if applicable.

2. Translate AGENTS.md to .cursor/rules/. Split your single instructions file into focused rule files (architecture, conventions, testing, workflow).

3. Set up MCP servers in Cursor. Copy your MCP configuration, adjusting for Cursor’s .cursor/mcp.json format.

4. Learn the interactive workflow. Practice with Agent Mode (Cmd+I), Tab autocomplete, and @-mentions. The interactive loop is very different from async task submission.

5. Keep Codex for background work. You do not have to choose one tool. Use Cursor for interactive development and Codex for parallel batch work.

Moving from Codex to Claude Code for CLI Work

If you prefer the terminal and want more interactive control than Codex provides:

1. Install Claude Code. npm install -g @anthropic-ai/claude-code

2. Convert AGENTS.md to CLAUDE.md. Remove sandbox-specific instructions, add interactive workflow guidance and key commands.

3. Migrate MCP configuration. Use claude mcp add or copy to .mcp.json.

4. Adjust your workflow. Claude Code is synchronous and interactive. Instead of submitting tasks and reviewing later, you have a conversation and guide the work in real time.

5. Use extended thinking. Claude Code’s extended thinking (trigger with “think”/“think harder”/“ultrathink”, or toggle with Option+T / Alt+T) gives you the planning capability that Codex handles implicitly. Plan Mode (Shift+Tab) is a good alternative for scoping a complex task before any edits land.

When This Breaks

Configurations drift between tools. If you update CLAUDE.md but forget to update AGENTS.md and .cursor/rules/, the tools give different results. Use the synchronization script above or add a CI check that verifies the files are in sync.

MCP tokens expire in one tool but not another. Each tool manages MCP authentication independently. When a token expires, you may need to update it in multiple locations. Consider using environment variables that all tools read from the same .env file.

Codex produces different results than Claude Code for the same prompt. The tools run on different underlying models. Codex runs on GPT-5.5 by default across every surface (App, CLI, IDE, Cloud); API-key-authenticated Codex uses gpt-5.2-codex. Claude Code defaults to Claude (Opus 4.8 for complex work). Prompts that work well for one model may need adjustment for another. Be more explicit in Codex prompts since there is no opportunity for clarification mid-task.

File conflicts when running tools in parallel. If Cursor and Claude Code are both editing files in the same directory, you will get conflicts. Either work on different areas of the codebase or coordinate which tool is active on which files.

Skills install for one tool but not another. The skills CLI may not detect every installed agent. Verify the install by listing each agent’s skills directory (for example, .claude/skills/) after running npx skills add, and re-run it from the project root if a tool was missed.

What’s Next

Migrating from Windsurf Moving from Windsurf to any of the three major AI coding tools.

Migrating from GitHub Copilot Upgrading from autocomplete to full agent capabilities.

Project Conversion Playbook Make your project AI-ready with proper configuration for all tools.