Moving to Cursor, Claude Code, or Codex: a migration guide

Migrating a team to Cursor, Claude Code, or Codex is a five-step project: choose the tool by where the team works, carry instructions and MCP configuration across with the built-in importers, prove the tool on the team’s own repository against its test suite, roll out in stages with exit criteria, and keep the old tool until measurements justify retiring it.

Your team has budget for a new coding agent. Half the developers want Claude Code in the terminal, the other half live in Cursor, the Copilot seats renew next month, and nobody has written down how you will know whether the switch worked. This guide is for the developer or tech lead who owns that switch, and for the CTO who signs it off.

What you’ll walk away with from this migration guide

• A decision table that maps how your team works to Cursor, Claude Code, or Codex.
• The import commands that carry instructions, MCP servers, and skills across, plus a prompt that audits what they missed.
• Copy-paste prompts that test the new tool on your own code, with the gates that decide pass or fail.
• A staged rollout with exit criteria instead of calendar weeks, a metric panel with a baseline, and a rollback plan.
• A checklist you can paste into the migration ticket.

Which tool should you move to?

Answer five questions. Most teams find two columns fit, and running two tools on one shared AGENTS.md is a normal outcome, not a failure to decide.

Question	Points to Cursor	Points to Claude Code	Points to Codex
Where does most coding time go?	An editor, with visual diffs	The terminal, scripts, and CI	Several surfaces: desktop app, CLI, IDE extension, cloud tasks
What do you most want to hand off?	Interactive multi-file edits you watch	Long autonomous sessions, hooks, headless runs	Parallel tasks and pull request reviews
Which integrations must keep working?	VS Code extensions, Bugbot on pull requests	GitHub Actions (anthropics/claude-code-action@v1), hooks, plugins	@codex review on GitHub, @ChatGPT in Slack, and @Codex in Linear (per OpenAI’s docs, checked 2026-10-12)
How comfortable is the team in a terminal?	Prefers a GUI	Terminal-native	Mixed
Which provider or data constraints apply?	Privacy Mode is on by default for teams, and self-hosted machines keep tool execution in your own network (Cursor’s docs, checked 2026-10-12); confirm model-provider terms with Cursor before the pilot	Runs on the Anthropic API, Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, and Claude Platform on AWS	ChatGPT plans or an API key, which covers the CLI, SDK and IDE extension only (OpenAI’s Codex pricing page, checked 2026-10-12); Amazon Bedrock provider

Start on each tool’s default model and change it only when your own evals say so. Model names and prices live on the models hub, plan prices on the pricing analysis, and a feature-by-feature view on the feature matrix. If you are also weighing agents outside the big three, the coding-agent landscape holds the site’s bake-off protocol.

What should you inventory before you switch?

Write the answers into the migration ticket before anyone installs anything. The inventory is what the importers and the audit prompt below are checked against.

• What you are leaving: tools, seat count, and the renewal date of each subscription.
• What you are moving to: one tool, or two with a shared instruction file.
• Configuration that exists today: instruction files (.cursor/rules/, CLAUDE.md, AGENTS.md), MCP servers and where their credentials live, skills, plugins, hooks, and CI jobs that call an agent.
• Compliance constraints: SOC 2, GDPR, HIPAA, data retention, and which model providers your contracts allow.
• People: two or three pilot volunteers of different seniority, and one owner for the shared configuration.
• Baseline and decision rule: the metrics in how do you know the switch worked, measured before the pilot, and the rollback triggers.

Carry your configuration across

Each tool keeps the same three layers in different places: project instructions, MCP servers, and skills. Plugins do not move; each tool has its own marketplaces, so reinstall the equivalent. The Agent Skills format is shared, so a SKILL.md folder works in all three tools once it sits in the right directory.

Claude Code

Claude Code (v2.1.296) imports from Codex, Gemini CLI, and Cursor. Run it in the repository, dry run first:

claude import cursor --dry-run   # or: codex, gemini
claude import cursor             # opens a picker; choose what to bring over
claude mcp list                  # confirm each imported server connects

Per Anthropic’s commands reference (checked 2026-10-12), the import brings instruction files, MCP servers, commands, subagents, and skills. It needs v2.1.213 or later, and v2.1.265 or later for Cursor. It is not available on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, Claude Platform on AWS, or through a Claude apps gateway.

To keep one instruction source, make CLAUDE.md a one-line file that contains @AGENTS.md. That import works on every release channel, while Claude Code’s own fallback (reading AGENTS.md when there is no CLAUDE.md) needs v2.1.277 or later (both release channels on 2026-10-12).

Codex

Codex CLI has /import (0.162.1, checked 2026-10-12). Start codex in the repository and run it, and it offers to “import setup, this project, and recent chats from Claude Code”. Per the 0.145.0 and 0.147.0 release notes the import covers Claude Code and Cursor setups: settings, MCP servers, plugins, sessions, commands, and Cursor-managed skills. Then check the servers from the terminal:

codex mcp list

Codex reads AGENTS.md natively; /init creates one if the import did not bring your rules across. Project skills go in .agents/skills/.

Cursor

Cursor reads most shared configuration where it already sits (Cursor’s docs and help, checked 2026-10-12). It supports AGENTS.md in the project root and in subdirectories, and it reads CLAUDE.md the same way and always applies it, so you need no generated project rule. It loads skills from .agents/skills/ and .cursor/skills/, and for compatibility from .claude/skills/ and .codex/skills/; npx skills add <owner/repo> still installs a skill from a repository. Put rules that apply only to some files in .cursor/rules/*.mdc (a plain .md file there is ignored, and .cursorrules is legacy); project rules covers the format. Write .cursor/mcp.json by hand. As of 2026-09-26 we could not confirm a built-in importer in Cursor, so treat the move as manual. Cursor needs no generated copy of AGENTS.md; one rules source for every agent covers keeping one shared rules file in sync across tools.

The step-by-step version for moving between the three, including MCP config per tool and a CI check that stops the instruction files from drifting, is on migrating between Codex, Cursor, and Claude Code.

Copy-paste prompt: audit what the importer missed

We are migrating this repository from Cursor to Claude Code. Compare the old
configuration with the new one and report every gap. Read everything under
.cursor/rules/, .cursor/mcp.json, AGENTS.md, CLAUDE.md, .mcp.json, and .claude/
(skills, agents, settings.json).

Produce a table with one row per rule, command, MCP server, and skill: where it
lived before, where it lives now, and one of MIGRATED, MISSING, DUPLICATED, or
CHANGED. Flag any instruction that now exists in two files, any MCP server whose
credential is written inline instead of read from an environment variable, and
any skill that did not come from this repository or a vendor marketplace.

Do not edit any file. End with the three gaps most likely to change how the
agent behaves on this codebase.

For a move to Codex, swap the target paths for ~/.codex/config.toml and .agents/skills/.

Prove the new tool on your own code

A vendor demo proves nothing about your repository. Pick three tickets closed in the last sprint, one simple, one medium, and one hard, whose merged fixes you trust. For each, cut a branch from the commit before the fix, give the new tool the ticket text, and judge the result by the same gates your CI runs, not by reading every line.

The result passes when the existing tests and the tests from the merged fix pass, the type checker and linter are clean, and the diff adds no dependency nobody asked for. Record for each task whether it passed on the first attempt, how many times someone had to intervene, and the usage it consumed (/usage in both Claude Code and Codex). If you are choosing between two tools, run the same three tasks in both. That record, not a feeling about the diff, is what the pilot decision uses. The evidence bundle defines what an agent’s pull request should hand a reviewer.

Copy-paste prompt: first-day validation with gates

Read AGENTS.md (or CLAUDE.md) and the src/services/ directory. For each service
file, check that every async function handles errors, that multi-step database
writes run inside a transaction, and that a matching test file exists under
tests/. Report the gaps as a table before changing anything.

Then fix the three gaps with the highest production risk, one commit each.
After each fix, run the test suite, the type checker, and the linter, and paste
the exact commands and their final output lines. If a gate fails, fix the cause
or revert that commit. Do not weaken, skip, or delete a test. Finish with every
file you changed and one line on why.

For developers who have never handed a task to an agent, start with work that cannot break production. Characterization tests are the safest first task, because they only add files and the test run shows whether the agent understood the code.

Copy-paste prompt: a safe first task for a new agent user

Look at src/services/UserService.ts and its existing tests. List the public
methods and edge cases that no test covers. Write tests that pin down the
current behaviour, including error paths. Do not modify any file outside
tests/. Run the new tests and show the output.

If a test fails against the current code, do not change the code. Leave the
test in place with a comment that describes the behaviour you found, and list
it for me as a possible bug.

What changes depends on the tool you are leaving

The configuration moves in an afternoon. The habits take longer, and they differ by starting point.

Leaving	What carries over	The habit to change	Detailed guide
GitHub Copilot	Agent Skills and MCP servers, which Copilot also supports. Copilot now has a cloud agent, a CLI, and a desktop app, so many teams add a second tool rather than replace it	Accepting completions line by line → handing over a whole task with acceptance criteria	Adding Claude Code or Codex alongside Copilot
ChatGPT in the browser	Nothing but your prompts	Pasting code and errors in → letting the agent read the repository and run the commands	From plain chat to integrated development
Devin Desktop (formerly Windsurf)	Rules, MCP servers; workflows become skills	Trusting rule triggers you never tested → proving the rules apply	Migrating from Devin Desktop
Another of the big three	Almost everything: through the importers above, and because Cursor reads AGENTS.md, CLAUDE.md and the Claude and Codex skill folders where they sit	Expecting the same permission and parallel-work defaults	Migrating between Codex, Cursor, and Claude Code
An IDE with no AI	Editor settings and keybindings	Writing every line → specifying behaviour and verifying it with gates	Migrating from traditional IDEs

Claude Code and Codex are agents first. If the team relies on inline completion while typing, keep an editor that provides it, such as Cursor with Tab, next to the agent.

Roll out to the team in stages

Move to the next stage when its exit criterion is met, not when a calendar says so. The criteria make the rollout self-checking: a stage that cannot meet its criterion tells you what to fix before more people depend on it.

1. Pilot with two or three volunteers. Choose different seniority levels and different parts of the codebase. They run the validation tasks above, then real tickets, and commit the shared configuration. Exit when the bake-off tasks pass the gates and the pilot has written down what broke. Designing a pilot that proves something covers cohorts and decision rules.

2. Early adopters, about a quarter of the team. Publish a short internal setup guide built from the pilot notes, open one channel for questions, and name the owner of AGENTS.md. Exit when a new joiner can set up from the guide alone in one sitting, and the review queue is not growing.

3. Everyone. Train on your own repository, not generic demos, and hold office hours for the first month. Every agent’s pull request goes through the same CI gates as a human’s. Exit when the metric panel below is at or better than baseline at a checkpoint.

4. Retire the old tool. Cancel the old seats after the final checkpoint, remove the old instruction files once the new ones are the only source, and move any remaining automation (review bots, CI jobs) across.

Caution

Do not skip the pilot. A rollout to everyone at once has no internal expert to answer questions, no shared configuration, and no baseline to compare against, so the first bad week becomes the verdict on the tool. For the people side of the rollout, see team adoption and helping the team stop reading every diff.

How do you know the switch worked?

Measure a baseline from the last one to three months of git and CI history before the pilot starts, then compare at each checkpoint. Set targets from that baseline and write the decision rule down before week one. Self-reported speed is not evidence. METR’s 2026 follow-up study of AI tools on open-source work produced confidence intervals that cross zero, and METR itself says the new results are “hard to interpret” (METR, study repository, read 2026-09-26). DORA’s 2025 report puts the risk plainly: “AI doesn’t fix a team; it amplifies what’s already there” (Google Cloud DORA blog, 2025-09-23).

Metric	How to measure it	What it tells you
Time from ticket to merged pull request	Issue tracker and git timestamps, median	Whether work actually flows faster
First-pass CI rate	Share of pull requests whose first CI run is green	Whether the agent meets your gates without rework
Revert or change failure rate	Reverts and hotfixes per merged pull request	Whether speed costs stability
Review time per pull request	Time from review request to approval	Whether review became the bottleneck
Cost per accepted change	Seats, usage, CI, and rework over merged, non-reverted changes	Whether the switch pays; the method is in the economics of agent-built software
Satisfaction and active use	A short anonymous survey (1 to 5) and daily active users	Whether people will keep using it

Definitions that survive agent-written code are on DORA, SPACE, DX Core 4 and AI measurement.

Copy-paste prompt: pull the baseline from git history

Using git and the gh CLI in this repository, build a baseline for the last 90
days. List merged pull requests with
`gh pr list --state merged --limit 500 --json number,createdAt,mergedAt,title`,
then compute: the median hours from creation to merge, the number of merged
pull requests per week, and how many commits on the default branch are reverts
(`git log --oneline --grep '^Revert'`). Show every command you ran and its
output, put the results in a table, and save it as docs/migration-baseline.md.
Do not change any other file.

Plan the rollback before you need it

A rollback plan written after the first bad week is a negotiation. Write it into the migration ticket up front:

1. Keep the old seats until the final checkpoint. Do not renew an annual plan for the old tool, but do not cancel it before the new one has passed its checkpoints.
2. Keep the old configuration in git. The old rule files stay in the repository until the new tool passes the same validation tasks, so reverting is a checkout, not a rewrite.
3. Define measurable triggers. For example: the revert rate stays above baseline at two consecutive checkpoints, the first-pass CI rate falls, or a compliance review blocks the provider.
4. Hold checkpoints at 30, 60, and 90 days. Decide from the metric panel, not from the loudest opinion in the retro.
5. Allow a dated exception. A developer who is blocked can stay on the old tool until a named date, which costs less than forcing a switch that stalls their output.

What breaks when a team switches AI coding tools?

The agent ignores the build commands the old tool always followed. Two instruction files disagree, or a teammate runs a Claude Code build older than v2.1.277 and does not get the AGENTS.md fallback. Recovery: keep one AGENTS.md, make CLAUDE.md contain @AGENTS.md, and add a CI check that fails when that line disappears (rules sync).

The importer is not available. Claude Code’s /import does not run on Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, Claude Platform on AWS, a Claude apps gateway, or with feature-flag fetching turned off. Recovery: run the dry run on a machine with direct API access, or migrate by hand and use the audit prompt as the checklist.

An MCP server works in one tool and fails in the other. Claude Code negotiates MCP spec 2026-07-28 with direct HTTP servers (and, from v2.1.292, with local stdio servers too; both release channels on 2026-10-17), while Codex 0.157.1–0.162.1 still uses the older protocol (mcp_2026_07_28 is under development and off in codex features list, checked 2026-10-12). Recovery: check each server with claude mcp get <name> and codex mcp get <name>, pin the server version, and read the server’s changelog for spec support.

Imported skills nobody reviewed. The importers copy skills wholesale. OWASP’s Agentic Skills Top 10 (pre-launch draft, last updated March 2026) lists cross-platform reuse and update drift as named risks. Recovery: read every SKILL.md before the pilot, keep only skills from your repository or a vendor marketplace, and pin versions.

Developers either accept whole diffs or rewrite everything. Both are trust calibration problems. Recovery: let the gates decide, start people on test-only tasks, and move review from the diff to the evidence as described in reading evidence instead of code.

The dip is invisible because nobody measured a baseline. Without one, the first slow week looks like proof the tool failed. Recovery: run the baseline prompt now; git history makes a retroactive baseline possible.

Usage limits run out mid-pilot. Claude Code and Codex subscriptions both meter usage in five-hour and weekly windows (Codex’s Pro plans currently have no five-hour limit, per OpenAI’s pricing page, read 2026-10-12). Recovery: watch /usage during the bake-off and size the plans on the pricing analysis before the full rollout.

Migration checklist for the ticket

Paste this into the migration ticket and tick it as you go.

• Inventory written: tools, seats, renewal dates, configuration, compliance constraints
• Target tool chosen with the decision table, and a feature matrix check for anything critical
• Baseline measured from git and CI history; decision rule and rollback triggers written
• Importer dry run reviewed; audit prompt run; one AGENTS.md committed
• MCP servers re-added and checked in each tool; credentials read from environment variables
• Skills reviewed and pinned; plugins reinstalled from the new tool’s marketplace
• Three closed tickets rerun in the new tool and judged by the gates
• Pilot volunteers named; internal setup guide and question channel ready
• Checkpoints at 30, 60, and 90 days in the calendar
• Old seats scheduled for cancellation after the final checkpoint

Where to go next with the migration

Migrating between Codex, Cursor, and Claude Code One AGENTS.md, the import commands, MCP per tool, and a parity run.

Designing a pilot that proves something Cohorts, baselines, and a decision rule signed before week one.

Pricing analysis Plan prices for the three tools, in one place.

Claude Code quick start From installation to the first task in the terminal.

Codex quick start Set up the CLI, the app, and AGENTS.md.

Cursor quick start Project rules, MCP, and the first feature in the editor.