Migrate from cursor to claude-code.
17 hands-on-verified translation patterns — what carries over and what to watch for. Cited to the Feature Parity Map; the audit tells you whether the move is worth it.
Claude Code is built on the Claude Agent SDK (TypeScript and Python references at docs.claude.com/en/docs/agent-sdk/), so you can lift the same loop — tool use, sub-agents, MCP, skills, hooks — into your own apps and authenticate with a Claude Pro/Max/Team/Enterprise plan or a Console API key. Cursor does NOT publish an equivalent programmable SDK that exposes its agent loop; Cursor's programmatic surface is the Cursor CLI (`cursor` headless mode, GitHub Action) and the MCP Extension API for plugging in tools. Building custom agentic apps that mirror Cursor's behavior is therefore much harder than mirroring Claude Code's.
- Warning: Reverse direction (Cursor -> Claude Code SDK) is N/A — you can't extract Cursor's agent into a redistributable SDK; the closest move is to call Cursor CLI as a subprocess in CI.
- Warning: Tab autocomplete is not exposed in any SDK on either side — it stays inside the Cursor product surface.
- Warning: Anthropic SDK plan-based auth (using a Pro/Max subscription) is documented in a support article but rate-limited the same way as Claude Code itself.
Both products implement the Agent Skills open standard (agentskills.io): folders containing `SKILL.md` with YAML frontmatter (`name`, `description`, `when_to_use`, `allowed-tools`, optional scripts/refs). Claude Code looks in `.claude/skills/<name>/SKILL.md` (project) and `~/.claude/skills/` (user); Cursor looks in `.cursor/skills/<name>/SKILL.md` (project, shipped in 2.4) plus user-scope. Skills are auto-loaded when relevant or invoked with `/skill-name` in either tool. To migrate, copy the SKILL.md verbatim and move the parent folder under the other tool's `skills/` directory.
- Warning: Claude Code ships several bundled skills (`/code-review`, `/batch`, `/debug`, `/loop`, `/claude-api`, `/run`, `/verify`, `/run-skill-generator`); Cursor ships its own (`/loop` added 2026-05-20 in 3.5) — overlap is partial, names may collide.
- Warning: Claude Code skill frontmatter keys like `context: fork`, `agent`, `effort`, `disable-model-invocation`, `paths`, `shell` are Claude-specific and may be ignored by Cursor.
- Warning: Cursor skills can attach hooks that run before/after agent actions; Claude Code skills attach hooks via the same `hooks` frontmatter key, but the hook event names differ slightly per product.
- Warning: Skills appear in the slash-command menu in both tools, but in Cursor there have been intermittent reports of skills visible in Settings yet not appearing as slash commands — refresh the Agents Window if so.
Claude Code background agents / Agent view (v2.1.139+, research preview Q1 2026) parallel Cursor Cloud Agents and Bugbot. Both let you dispatch many autonomous sessions, monitor progress on a dashboard, and resume conversations later. Cursor Cloud Agents run on Anysphere-managed VMs (Dockerfile-configurable since 2026-05-13), trigger from the Agents Window, web dashboard, Slack, GitHub, or Jira `@Cursor` mention, and deliver work as PRs on `agent/<slug>` branches. Claude Code's closest analog for PR-flavored automation is the `anthropics/claude-code-action@v1` GitHub Action — install via `/install-github-app`.
- Warning: Cursor Cloud Agents require Pro+ AND privacy mode DISABLED — privacy-mandated workspaces cannot use them.
- Warning: Claude Code Agent view is still a research preview as of May 2026 — feature names and gating may change before GA.
- Warning: Cursor 2.0 supports parallel multi-agent execution (up to 8 agents racing on git worktrees, best result wins); Claude Code's parallel surface is via multiple background sessions, NOT racing — they don't auto-select a winner.
- Warning: Bugbot is a Cursor-specific automated PR-review agent (now usage-billed at ~$1.20/review); Claude Code's equivalent is `/security-review` and `/review` skills triggered manually or via the GitHub Action — no native scheduled PR-review surface.
Claude Code's agentic edit loop (Read/Write/Edit tools, multi-file refactors, inline diffs, Plan mode, checkpoints) maps to Cursor's Composer / Agent mode (Cmd/Ctrl+I) plus Cursor's own Plan mode toggle (Shift+Tab between Agent/Ask/Plan). Both surfaces stage changes as per-hunk accept/reject diffs and offer rollback (Claude Code: VS Code 'Rewind code'; Cursor: agent checkpoints + Cmd/Ctrl+Z). For long-running autonomous work, both have parallel/multi-agent execution (Claude Code background agents / Agent view; Cursor 2.0 parallel agents on git worktrees, up to 8 candidates).
- Warning: Claude Code plan-mode review opens as an editable Markdown doc in the VS Code extension; Cursor's plan mode is interactive inside the Agents Window and does not produce a separate file.
- Warning: Cursor 'Cloud Agents' run on Anysphere VMs and deliver work as PRs on `agent/<task-slug>` branches; the analogous Claude Code surface is `claude-code-action` on GitHub Actions or Claude Code on the web (research preview).
- Warning: Cursor's per-hunk accept UI is part of the IDE; Claude Code in the bare terminal accepts whole-file diffs by default unless you run inside the VS Code/JetBrains extension.
Claude Code's official GitHub Action (`anthropics/claude-code-action@v1`) responds to `@claude` mentions in issues/PRs, runs on cron, and accepts pass-through CLI flags via `claude_args`. The Cursor analog is the Cursor CLI on GitHub Actions plus Cloud Agents triggered by `@Cursor` mentions in GitHub/Jira/Slack — both produce PRs and reply to threads. Migrating a workflow: swap `anthropics/claude-code-action@v1` for the Cursor CLI action, port `prompt`, model selection, and any `plugin_marketplaces`/`plugins` to Cursor rule/skill equivalents.
- Warning: Auth differs: Claude Code Action accepts `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` (from `claude setup-token`, for Pro/Max users); Cursor CLI in CI typically uses a Cursor API token tied to the team plan.
- Warning: Bedrock/Vertex/Foundry support is first-class in `claude-code-action` (`use_bedrock`, `use_vertex` inputs); Cursor's CI runs against Cursor-hosted models or BYOK to providers — no direct Bedrock toggle.
- Warning: `/install-github-app` from inside the Claude Code CLI sets up the action end-to-end; Cursor requires manual install of its GitHub App via cursor.com.
- Warning: Trigger phrase customization (`trigger_phrase` input in claude-code-action) has no documented equivalent in Cursor — `@Cursor` is the fixed trigger.
There is no Claude Code analog for Cursor Tab. Claude Code intentionally has no ghost-text completion — the docs' VS Code vs CLI comparison table marks 'Tab completion' as CLI-only and refers only to shell-style tab completion of commands and paths. Users who want Cursor-style inline next-action prediction while staying in Claude Code's world typically run GitHub Copilot or another completion product alongside the Claude Code extension. Reverse direction (Cursor -> Claude Code) is a hard loss: Cursor Tab's proprietary RL-trained model has no equivalent in Anthropic's product line.
- Warning: Cursor Tab is gated on Cursor's proprietary model and is NOT swappable via BYOK — you cannot rebuild Tab on top of Claude API keys.
- Warning: If you migrate from Cursor to Claude Code, prepare to lose multi-line ripple edits and cross-file Tab jumps entirely — the closest Claude Code analog is an explicit Edit/MultiEdit tool call, which is conversation-driven rather than keystroke-driven.
- Warning: Some Claude-Code-adjacent IDE extensions (Continue, Cline, etc.) add ghost-text on top of Anthropic APIs, but these are third-party and not part of Anthropic's Claude Code product.
Map Claude Code's terminal REPL (started with `claude`) to Cursor's Agents Window (Cmd/Ctrl+I for Composer/agent pane, Cmd/Ctrl+L for chat sidebar, Cmd/Ctrl+Shift+M for full-screen tab view added in Cursor 3.4). Both accept natural-language turns, @-mention files, run tools, and stream diffs back. To preserve a REPL feel inside Cursor, use the Agents Window's full-screen tab and keep the integrated terminal open; to get a Cursor-like graphical surface from Claude Code, install the Claude Code VS Code extension (it runs natively inside Cursor through Open VSX) and use the `/ide` command from the CLI to share state with the editor.
- Warning: Claude Code's slash-command surface (`/clear`, `/compact`, `/context`, `/cost`, `/usage`, `!bash`, Shift+Enter multi-line) is CLI-only; Cursor's Agents Window has its own slash menu but does NOT mirror Claude's commands one-for-one.
- Warning: Cursor unified Chat / Composer / Cmd+L into a single Agents Window in 2.0 (Oct 2025); older tutorials that show separate panes are stale.
- Warning: Claude Code REPL state lives in `~/.claude/` and can be resumed via `claude --resume`; Cursor agent state lives inside the workspace's Agents Window history and is not interchangeable.
Claude Code hooks (`PreToolUse`, `PostToolUse`, session start/stop, configured in `settings.json` or scoped to a skill/sub-agent via `hooks` frontmatter) map directly to Cursor hooks documented at cursor.com/docs/hooks (`PreToolUse`, `PostToolUse`, `stop`, and `beforeSubmitPrompt` for rewriting prompts before submission). The Jan 8, 2026 Cursor release made hook command startup 40x faster and added the `beforeSubmitPrompt` event, which has no first-class Claude Code analog. Both let you enforce policy, format-on-write, or block tool calls deterministically.
- Warning: Hook event names overlap but are not identical — `beforeSubmitPrompt` is Cursor-only; Claude Code has session-lifecycle hooks that Cursor's docs list differently.
- Warning: Both products execute hooks as shell commands; on Windows you must ensure shell semantics (PowerShell vs bash) match in each product's settings.
- Warning: Hook configuration files differ: Claude Code uses `~/.claude/settings.json` and `.claude/settings.json`; Cursor uses its own settings UI plus skill-scoped frontmatter — there is no shared schema to copy between them.
Both products are first-class MCP hosts. Claude Code uses `claude mcp add` (stdio/HTTP/SSE) and a `/mcp` slash command; Cursor reads `.cursor/mcp.json` (project) and `~/.cursor/mcp.json` (global) using a standard `mcpServers` object identical in shape to Claude Desktop's config. To move an MCP server between products, copy the server entry (command/args/env or url/headers) — variable interpolation is supported in both. Cursor additionally exposes a programmatic `vscode.cursor.mcp.registerServer()` extension API for dynamic registration.
- Warning: Claude Code's built-in `ide` MCP server (bound to 127.0.0.1 with a fresh per-activation token, exposing `mcp__ide__getDiagnostics` / `mcp__ide__executeCode`) has no equivalent in Cursor — Cursor talks to its IDE state directly, not through MCP.
- Warning: Per-skill / per-subagent MCP allowlists work via `mcpServers` frontmatter in Claude Code; Cursor's equivalent gating is at the agent/skill level but the YAML key names differ.
- Warning: On Windows, project-level `.cursor/mcp.json` has had path-resolution bugs reported in the community forum — verify with the `/mcp` panel that servers actually loaded.
- Warning: Cursor CLI in `-p` mode has had a race condition where MCP tools disappear when multiple stdio servers are configured (filed 2026-04-17); prefer HTTP transports for headless runs.
- Warning: Claude Code Pro/Max subscriptions auth MCP usage through the plan; Cursor requires either an API key or its credit-pool plan to invoke MCP-driven model calls.
Claude Code is Anthropic-only — `/model` switches between Opus 4.7, Sonnet 4.6, and Haiku 4.5 (plus the `opusplan` bundled mode that plans with Opus, executes with Sonnet). Cursor exposes a much wider picker: Cursor Composer (Standard and 2.5 Fast), Claude Sonnet 4.5 (regular + thinking), Claude Opus, GPT-5 / GPT-5.1 High, Gemini 2.5 Pro, Grok Code, plus 'Auto'. Migrating Claude Code -> Cursor: pick Claude Sonnet 4.5 or Claude Opus for the closest behavioral match; use Auto when you want Cursor to route to whichever model is cheapest/fastest (Auto doesn't debit the credit pool).
- Warning: Reverse direction is lossy: Cursor users relying on GPT-5, Gemini 2.5, Grok, or in-house Composer models have NO equivalent in Claude Code — the CLI only runs Anthropic models.
- Warning: Cursor's proprietary Tab autocomplete model cannot be swapped via BYOK and has no Claude Code analog at all (Claude Code does not do ghost-text completion).
- Warning: Anthropic model versioning differs across products: Cursor lists 'Claude Sonnet 4.5' in May 2026 while Anthropic's own pricing page lists Sonnet 4.6 — Cursor may lag the latest Anthropic point release by weeks.
- Warning: Claude Code `effort` levels (`low`/`medium`/`high`/`xhigh`/`max`) are per-skill and per-model; Cursor exposes 'thinking' variants as separate model entries rather than effort levels.
Both products use subscription-plus-overage models but the meters are shaped very differently. Claude Code's consumer plans (Pro $20, Max 5x $100, Max 20x $200) gate on TWO weekly usage windows (one all-model, one Sonnet-only) plus a 5-hour session cycle, with limits expressed as time-on-task rather than requests. Cursor's plans (Hobby free, Pro $20, Pro+ $60, Ultra $200, Teams $40/user, Enterprise custom) gate on a monthly credit pool whose dollar value equals the subscription price; Auto-mode requests don't debit the pool but manually picking a frontier model does. To budget across both: a Claude Code Max 5x ($100/mo) seat ~ a Cursor Pro+ ($60/mo) seat in raw spend on Anthropic-only frontier work, but Cursor adds Tab autocomplete and multi-vendor models for that price.
- Warning: Claude Code Pro/Max meters are TIME-based and not publicly numerical; Anthropic publishes only the 5x/20x multiplier and the in-app `/usage` view. Cursor meters are DOLLAR-based and visible on the pricing page.
- Warning: Cursor Bugbot pricing shifted from $40/seat/mo to usage-based (~$1.20/default-effort review) in May 2026 (seat fee removed June 8, 2026); some Cursor docs may still show legacy seat-fee language.
- Warning: Both products honor BYOK / API PAYG: Claude Code respects `ANTHROPIC_API_KEY` (overrides plan auth) and supports Bedrock/Vertex/Foundry; Cursor BYOK supports OpenAI/Anthropic/Google/Azure/Bedrock plus OpenAI-compatible providers but Tab is excluded.
- Warning: Team plans diverge: Claude Code Team is $20/seat annual ($25 monthly) with min 5 seats; Cursor Teams is $40/user/mo flat. Enterprise SSO/SAML/SCIM is on both but with different feature sets.
- Warning: Cursor Hobby (free) has no Claude Code equivalent — Anthropic's free Claude.ai plan does NOT include Claude Code.
Claude Code plugins bundle slash commands, sub-agents, skills, MCP servers, and hooks into one installable unit shipped through plugin marketplaces (Git repos / URLs / local paths) and managed via `/plugin`. Cursor does not yet ship a first-class plugin-bundle equivalent — community proposals (e.g., 'Agent Plugins' on the forum) exist but as of May 2026 the official primitives ship piecemeal (rules, skills, sub-agents, hooks, MCP each installed separately). To move a Claude Code plugin to Cursor, unpack it and copy each constituent into Cursor's matching directory (`.cursor/rules/`, `.cursor/skills/`, sub-agents settings, `.cursor/mcp.json`).
- Warning: Reverse direction is the easier path: Cursor Teams plans include a 'team plugin marketplace' but it lists rules/skills, not full multi-primitive bundles, so there's not much to move back.
- Warning: Claude Code plugin scopes (user / project / local) and the `plugin_marketplaces` / `plugins` inputs in the GitHub Action have no Cursor equivalent — automation pipelines must be rewritten per primitive.
- Warning: Plugin-namespaced slash commands (`/plugin:skill`) won't survive the move — rename to the un-namespaced form Cursor expects.
Claude Code's `CLAUDE.md` memory tree (`~/.claude/CLAUDE.md` user, `./CLAUDE.md` project, `./CLAUDE.local.md` local) maps to Cursor's Rules system (`.cursor/rules/*.mdc` Project Rules, Team Rules, User Rules) plus the cross-tool `AGENTS.md` convention that Cursor reads out of the box. @-mentions exist on both sides but Cursor has more granular @-symbols (@codebase, @file, @folder, @Code, @Docs, @Git, @Web, @Past Chats), while Claude Code leans on agentic Glob/Grep/Read tools and bare `@path` injection. To migrate: drop your `CLAUDE.md` into the repo as `AGENTS.md` (both tools will read it), or split it into focused `.cursor/rules/*.mdc` files with frontmatter that scopes when each rule applies.
- Warning: Cursor maintains a semantic AST embedding index (rebuild via Settings > Features > Compute Index); Claude Code does NOT pre-index — it explores agentically on each turn, so cold-start queries on huge repos are slower in Claude Code but cheaper in token-storage privacy.
- Warning: Cursor's Project Rules with `alwaysApply: true` behave like CLAUDE.md (always-on); rules with globs/`agentRequested` are loaded conditionally, which has no exact Claude Code analog (Claude relies on skills with `when_to_use` for similar behavior).
- Warning: Enterprise > project > user > local layering exists in Claude Code; Cursor analog is Team Rules + Project Rules + User Rules, but enterprise-managed override semantics differ.
- Warning: Claude Code `# <text>` quick-add syntax appends to CLAUDE.md from inside the REPL; Cursor has no equivalent in-chat memory-append shortcut (use `/rules` in the Cursor CLI or edit the .mdc file).
Claude Code sub-agents (`.claude/agents/<name>.md` with frontmatter for `prompt`, `tools`, `model`, `permissionMode`, `mcpServers`, `memory`, `effort`, `isolation`) map to Cursor's Sub-agents feature shipped in Cursor 2.4 (Feb 2026). In Cursor, sub-agents are defined in the Settings > Agents panel or as files alongside skills, and the orchestrator delegates tasks the same way Claude Code's `Explore` / `Plan` / `general-purpose` built-ins do. For cross-tool reuse, keep the prompt body identical and translate frontmatter fields by hand — the schemas are not interchangeable.
- Warning: Cursor sub-agent frontmatter does NOT support all of Claude Code's keys (e.g., `effort`, `permissionMode`, `context: fork`, `memory`, `isolation`); plan to drop or remap those when moving definitions.
- Warning: Claude Code's `Plan` built-in sub-agent intentionally skips CLAUDE.md to stay context-cheap — Cursor's plan mode behaves differently (it just toggles the model's reasoning style and does not spawn an isolated context).
- Warning: Cursor's most analogous 'autonomous worker' for long-running tasks is Cloud Agents (run on Anysphere VMs, deliver PRs), not in-session sub-agents — pick the right one based on whether you want a side worker (sub-agent) or a detached worker (Cloud Agent / Claude Code background agent).
Claude Code IS a terminal app whose agent loop natively calls a Bash tool; Cursor IS a VS Code-fork IDE that embeds a terminal panel plus an AI-prompt overlay (Cmd/Ctrl+K inside the terminal generates a command from natural language). Both expose terminal execution to the agent with approval prompts. To get IDE chrome around Claude Code, install the Claude Code VS Code extension into Cursor itself (it works on the fork via Open VSX). To get a CLI-shaped surface inside Cursor, use the Cursor CLI (`cursor` in the terminal) which runs the same agent loop headlessly.
- Warning: Claude Code's `!command` shortcut and Shift+Enter multi-line do not exist in Cursor's Composer prompt box.
- Warning: Cursor 'YOLO mode' / auto-run is the rough equivalent of Claude Code's `bypassPermissions` mode — both bypass per-tool prompts and should only be used in isolated/throwaway environments.
- Warning: Per-command allow/deny patterns (`Bash(git commit *)`) are Claude Code-specific; Cursor's tool allowlist is configured per agent/skill, not per shell command glob.
- Warning: Cursor as a VS Code fork lacks some Microsoft-proprietary extensions (Remote-SSH, official Pylance, Live Share) — if your Claude Code workflow depends on those, Cursor is a downgrade for remote dev.
Because Cursor is a VS Code fork, you can install the Claude Code VS Code extension INTO Cursor itself via Open VSX — the docs explicitly list Cursor (alongside Windsurf and Kiro) as supported. The result is a hybrid: Cursor's editor and Tab autocomplete plus a Claude Code panel with inline diffs, plan mode, checkpoints, and the full sub-agent/MCP/skills stack. This is the cleanest 'use both' path for developers who like Cursor's chrome but want Claude Code's agent loop and Anthropic plan billing.
- Warning: Spark icon location may move between Cursor versions; if the Claude Code panel doesn't appear, search 'Claude Code' in the Command Palette.
- Warning: Conflict risk: both products will try to handle agent edits to the same files — use Claude Code's `plan` mode and turn off Cursor Agent auto-apply when running them side by side.
- Warning: Permissions are duplicated: Cursor's YOLO/auto-run and Claude Code's `bypassPermissions` are independent; granting one does NOT grant the other.
- Warning: Reverse direction (running Cursor's stack inside Claude Code) is impossible — Cursor is a closed-source IDE, not an extension.
Claude Code on the web (Nov 2025 research preview, runs against connected GitHub repos on Anthropic-managed infra) and the iOS app correspond loosely to Cursor's web dashboard + Cloud Agents and the Cursor mobile experience. Both move the agent loop off the developer's laptop; both deliver work back as PRs or as resumable sessions. From the Claude Code VS Code extension, web sessions appear under Session history > Remote and can be downloaded to continue locally.
- Warning: Claude Code on the web is still research preview as of May 2026 — availability and plan gating may shift.
- Warning: No sync-back from local Claude Code sessions to the web surface; the path is one-way (web -> download to local).
- Warning: Cursor's mobile story is narrower than Anthropic's iOS app — Cursor leans on Slack/GitHub triggers for mobile usage rather than a full native client.