Migrating from traditional IDEs

Migrating from VS Code, JetBrains, or Vim to Claude Code or Codex keeps your editor, keybindings, and git flow; Cursor replaces the editor but runs VS Code extensions. The unit of work changes: the developer states the end state and constraints, the agent edits files, and tests, type checks, and a review pass prove the diff before merge.

This guide is for a developer with years of muscle memory in one editor. A teammate hands a multi-file refactor to an agent and moves on to the next ticket while you are still on file three. You want the same speed without throwing away a setup you spent a decade tuning, and without merging code you cannot vouch for.

What you get from moving to an AI agent

• A decision on which tool fits the editor you already use, and an install that leaves that editor in place.
• One project instructions file (AGENTS.md or CLAUDE.md, plus Cursor rules) generated from your repo’s real conventions.
• Three copy-paste prompts for the first week: scaffold the instructions file, pin current behavior with tests, and run a scoped refactor that reports its own evidence.
• A verification routine that checks each agent diff through gates instead of line-by-line reading.
• A list of the week-one failures and how to recover from each.

Which tool fits the editor you use now?

None of the three tools asks you to give up your editor on day one. They differ in where the agent lives.

You use today	Lowest-friction path	Why
VS Code	Cursor, or Claude Code and Codex through their VS Code extensions	Cursor is built on VS Code and installs extensions from its Extensions view; the Codex extension lists Cursor as a supported host (OpenAI’s Codex README). The Claude Code and Codex extensions put an agent inside the editor you already have.
JetBrains (IntelliJ, PyCharm, WebStorm, and others)	Claude Code through its JetBrains plugin, or either CLI in the IDE terminal	Anthropic’s JetBrains plugin runs the Claude Code CLI inside the IDE, so your inspections, refactorings, and debugger stay. Codex also has a native JetBrains integration from 2025.3 (secondary: Neowin); the CLI in the terminal is the verified path.
Vim, Neovim, or Emacs	Claude Code or Codex in a split terminal or tmux pane	Both are terminal agents. Your editor stays unchanged, and you review results with git diff as you do today.

If you are still choosing a primary tool, read how to choose a primary AI engineering harness and the Cursor versus Claude Code comparison first.

Install the agent without replacing your editor

Cursor

Cursor is itself an editor, so this is the only path that moves your editing to a new application.

1. Install Cursor and follow Cursor installation and setup. Treat any imported settings as a starting point and audit them in the next step.

2. Before you retire VS Code, save a record of what you had. In a terminal, run:

   code --list-extensions > vscode-extensions.txt

   Compare vscode-extensions.txt with what Cursor’s Extensions view offers, and plan an alternative for each gap.

3. Coming from JetBrains, install the IntelliJ IDEA Keybindings extension (k--kato.intellij-idea-keybindings, MIT licensed). It maps IntelliJ shortcuts onto VS Code-family editors. It also binds keys such as Ctrl+I (Implement methods), so open the Keyboard Shortcuts editor and resolve any collision with an AI command.

4. Add project rules under .cursor/rules/. The format is covered in Cursor project rules.

Claude Code

Claude Code is a terminal agent with VS Code and JetBrains integrations. You add it next to your editor.

1. Install with the native installer, then start it in your repository root:

   curl -fsSL https://claude.ai/install.sh | bash
   cd your-repo && claude

2. Connect it to your editor. In VS Code, install the Claude Code extension for inline diffs and plan review. In a JetBrains IDE, install the Claude Code plugin, which runs the CLI in the IDE terminal. From a terminal session, /ide shows and manages the connection, and claude --ide connects on startup. Details are in Claude Code IDE integration.

3. Vim and Emacs users run claude in a split pane and review with git diff. Nothing about the editor changes.

4. Check your version with claude --version. Several behaviors below, including reading AGENTS.md, arrived on the latest release channel first (v2.1.283 on 2026-09-26); on 2026-10-17 stable is v2.1.292 and has them too.

Codex

Codex spans a CLI, an IDE extension, and cloud tasks. You keep your editor and hand well-defined work to the agent.

1. Install the CLI and sign in with your ChatGPT account:

   npm install -g @openai/codex
   cd your-repo && codex

2. For in-editor work, install the Codex IDE extension. OpenAI’s README names VS Code, Cursor, and Windsurf (now Devin Desktop) as hosts. In the terminal UI, /ide pulls your current selection and open files from the editor.

3. JetBrains and Vim users run the CLI in the IDE terminal or a split pane. Codex also has a native JetBrains integration from 2025.3 (secondary: Neowin). See Codex installation for Homebrew and the install script.

4. Keep the first sessions read-only while you learn how Codex plans. Permission profiles (beta, Codex CLI 0.138.0 or later) set the boundary: codex -c default_permissions=":read-only" lets Codex read and propose, and ":workspace" lets it edit inside the repository.

Teach the agent your conventions on migration day

Your old IDE enforced house style through formatter and linter config. Agents read that config too, but they also need the rules no config file captures: where things live, which patterns are banned, and which command proves a change works. That goes in a project instructions file, and it is worth doing before your first real task.

Write the content once. The file name depends on the tool:

Tool	File the agent reads	Scaffold command
Codex	AGENTS.md at the repo root	/init in the terminal UI
Claude Code	CLAUDE.md; from v2.1.277 it reads AGENTS.md when no CLAUDE.md exists	/init in a session
Cursor	AGENTS.md and CLAUDE.md in the project root and subdirectories; Rules under .cursor/rules/ for Cursor-only rules	See Cursor project rules

A mixed team can keep one AGENTS.md for Codex and Cursor, and for Claude Code on v2.1.277 or later. Migrating between Codex, Cursor, and Claude Code covers keeping the files in sync. Whatever the file, end it with a verification section like this one, because that section is what lets you stop reading every line:

## Verification (run before saying a task is done)
- npm run typecheck
- npm run lint
- npm test -- --run
- Report each command's exit status. Never edit or delete a test to make it pass.

## Boundaries
- Do not touch src/auth/ or applied migrations in db/migrations/ without asking.

Copy-paste prompt: scaffold the instructions file from your repo

Analyze this repository and draft a project instructions file for coding agents.
Infer conventions from the code, not from general best practice:
directory layout and naming, the test framework and where tests live, the lint
and formatter rules in the config files, the data-access and error-handling
patterns, and the commit message style from the last 50 commits in git log.
Where the codebase is inconsistent, state the dominant pattern and list the
exceptions with file paths. End with a "Verification" section that lists the
exact typecheck, lint, and test commands from package.json (or the equivalent
build file), and a "Boundaries" section for directories an agent should not
edit without asking. Keep it under 150 lines. Do not write any other file.

Review the draft as you would a teammate’s pull request, and commit it. See the project conversion playbook for the rest of what makes a repo agent-ready.

How do you hand a refactor to an agent?

In a traditional IDE you rewrite handlers one file at a time and lean on Find and Replace for the mechanical parts. In the agent workflow you state the end state, the scope, and the proof, and the agent produces a coordinated multi-file diff.

Take a task you would recognize: moving an Express route module from callback-style error handling to async/await with one shared error middleware. Do it in two passes. First pin today’s behavior with tests, so that “it still works” becomes a command rather than your opinion. Then refactor against those tests.

Copy-paste prompt: pin current behavior before a refactor

Before we refactor anything in src/routes/, write characterization tests that
pin the current behavior of every route in that directory: status codes,
response bodies, and error responses for invalid input and for a failing
downstream call. Put them in tests/routes/characterization/. Do not change any
file outside that test directory. Run the new tests against the current code
and show me that they all pass. If a behavior looks like a bug, keep the test
asserting the current behavior and list it separately as a suspected bug.

Cursor

Open Agent, switch to Plan Mode so Cursor writes an implementation plan before editing, and paste the refactor prompt below. Review the plan before Cursor edits. The tests from the first pass decide whether the resulting diff is right; the diff view only shows you what moved.

Claude Code

Start in plan mode so nothing is edited until you approve the plan:

claude --permission-mode plan

Paste the refactor prompt, read the plan, and approve it. If a step goes wrong, /rewind restores an earlier checkpoint. Interactive sessions on Pro, Max, and Team start in auto mode, where a classifier approves routine actions. From v2.1.283 (both release channels on 2026-10-12) that applies on every plan and provider, so choose plan mode on purpose for your first refactors.

Codex

Keep it to one session. Start read-only so Codex can read and plan but not edit:

codex -c default_permissions=":read-only"

Paste the refactor prompt and approve the plan. Then run /permissions in the terminal UI and switch to :workspace, so Codex edits in the same session with the plan still in context. The :workspace profile limits edits to the repository. If you already quit, codex resume --last -c default_permissions=":workspace" reopens the same session with edit rights.

Copy-paste prompt: scoped refactor that reports its own evidence

Refactor the route handlers in src/routes/ from callback-style error handling
to async/await. Thrown errors must reach one shared errorHandler middleware in
src/middleware/error.ts (create it if it does not exist). Scope: only files in
src/routes/, src/middleware/, and tests/routes/. Keep every route's public
behavior identical; the characterization tests in
tests/routes/characterization/ must pass unchanged.
Before editing, list the files you will change and a one-paragraph plan, then
wait for my approval. After editing, run the typecheck, lint, and full test
suite and report: each command with its exit status, the files changed, any
test you added, and anything you were unsure about.

The mechanics differ between tools, but the discipline is identical: name the end state, name the scope, and name the command that proves it.

How do you check the agent’s diff without reading every line?

If you read every line of a 20-file diff, the agent saves you typing but not time. Move the checking into things that run.

1. Behavior is pinned before the change. The characterization tests exist and pass on the old code. A refactor that changes behavior turns them red.
2. The gates run twice. The agent runs typecheck, lint, and tests and reports exit codes. You or CI run them again, because an agent’s summary is a claim, not evidence.
3. Test files are protected. Check git diff --stat -- tests/ after every task. A refactor that edited characterization tests has moved the goalposts; reject it. The pattern is described in protecting the test oracle.
4. A second agent reviews. Run /code-review in Claude Code, /review (or codex review) in Codex, or Bugbot on the pull request in Cursor. Read the findings, not the whole diff.
5. You read the risky parts. Spend your attention on the paths named in your Boundaries section, new dependencies, and anything the agent flagged as unsure.

You sign off on the evidence: green gates, untouched tests, and resolved review findings. The evidence bundle turns this into a standard manifest for every pull request, and why evidence replaces diff reading explains the principle.

Which model should you use after the switch?

Your old IDE had one completion engine. Now there is a model picker. Start on each tool’s default, raise the effort level before you change the model, and change models only when your own results say so.

• Claude Code: Claude Opus 5.5 is the default from v2.1.280, on both release channels (checked 2026-10-12); check the models hub for the default on your provider. Raise effort with /effort, and pick Claude Fable 5.1 with /model fable only for the longest, hardest tasks.
• Codex: GPT-6.1 Sol is the bundled default (since CLI 0.159.1). GPT-6 Luna in the picker costs less for routine work, and GPT-6 Astra suits the hardest work.
• Cursor: pick a model in the model picker; the models hub tracks what each tool offers.

Prices and plan details live on the models hub.

Map your IDE features to the new tools

Traditional feature	Cursor	Claude Code	Codex
Find and Replace across files	Agent edit from a description	Multi-file edit from one prompt	Multi-file edit from one prompt
Code completion	Cursor’s Tab completion	Your editor’s completion stays	Your editor’s completion stays
Debugger	The editor’s debugger	Your IDE’s debugger; the agent reads the stack trace and writes the failing test	Your IDE’s debugger; same pattern
Git integration	Built into the editor	git from the terminal; the agent can commit	git from the terminal; codex apply <task-id> applies a Codex Cloud task’s diff to your working tree
Code review	Bugbot on pull requests	/code-review	/review, codex review
Extensions	VS Code extensions	Plugins, skills, and MCP servers	Plugins, skills, and MCP servers

Caution

Inline completion is the feature that differs most. Claude Code and Codex are agents, not completion engines. If you rely on completions all day, keep your editor’s completion running beside them, or choose Cursor.

To connect the agent to GitHub issues, a database, or a browser, add MCP servers. MCP server setup across the three tools shows the per-tool commands (claude mcp add, codex mcp add, and Cursor’s MCP settings).

When an IDE migration breaks down

A critical extension has no counterpart. Check vscode-extensions.txt against what the new setup offers. If a debugger or language pack is missing, keep the old IDE for that one workflow. Do not sideload an extension whose licence limits it to Microsoft products; check the licence on its Marketplace page first.

The agent ignores a convention you wrote down. A vague rule gets vague compliance. Replace “use good error handling” with a 10-line example of the exact pattern, and add a lint rule where one exists; a gate enforces what prose only suggests.

The agent rewrites code you did not ask it to touch. Name the scope in every prompt, start in plan mode (Claude Code, Cursor) or a read-only profile (Codex), and reject any diff whose git diff --stat includes files outside the scope. To undo, use /rewind in Claude Code or git restore on the affected paths.

Week one feels slower. It can be. In METR’s 2025 randomized trial, experienced open-source developers took 19% longer on tasks where AI tools were allowed. METR’s 2026 follow-up points the other way (about 18% less time for returning developers), but the interval crosses zero and METR calls that data an unreliable signal (METR, Measuring-Late-2025-AI-on-OSS-Devs repository, 2026). Start on low-stakes tickets, keep a note of time per task, and judge after a few weeks rather than a few days.

Your old keys trigger AI commands. Keymap extensions and AI features compete for the same shortcuts. Remap the AI commands in the Keyboard Shortcuts editor and keep your editing keys.

You still read every line. If review takes longer than the change, the gates are too weak. Add characterization tests and a review agent before you add more tasks.

Where to go next after switching IDEs

Project conversion playbook Make the repository agent-ready: instructions, gates, and context.

Migrating between Codex, Cursor, and Claude Code One AGENTS.md, the import commands, and a parity run across tools.

Adding Claude Code or Codex alongside GitHub Copilot Keep Copilot and add an agent with the same CI gates.

Team onboarding and adoption Rolling the switch out to a whole team rather than one developer.