Composer 2.5 shipped on May 18, 2026 as a drop-in replacement for Composer 2 in the Cursor IDE, CLI, and SDK. The model name is the only thing that changes in most places. The behavior is not. Composer 2.5 follows complex instructions more reliably, calibrates effort better, and writes shorter higher-signal summaries (source).

That makes the migration low-risk for most teams, but not zero risk. Anything you built on top of Composer 2's specific quirks (the way it phrases summaries, when it stops a task, how aggressive its tool calls were) needs a quick audit. The pricing tier structure also changed: Fast is more expensive than Composer 2 Fast, while Standard kept the same numbers.

This guide walks through the full migration: the changes that matter, what to audit before flipping the switch, a phased rollout plan, and the eval-harness work that keeps regressions out of production.

1What Actually Changed Between Composer 2 and 2.5

Composer 2.5 is built on the same Moonshot Kimi K2.5 base checkpoint as Composer 2. The improvements come from continued training on top of that base, not a foundation swap. Cursor reports that 85% of the compute budget went to extra training and reinforcement learning, with 25x more synthetic tasks than Composer 2.

Three concrete changes you will feel in production:

• Benchmark gains: SWE-Bench Multilingual moved from 73.7% to 79.8%. Terminal-Bench from 61.7% to 69.3%. CursorBench v3.1 lands at 63.2% (Composer 2 was not measured on this version).
• Effort calibration: Composer 2 had a tendency to spin on small tasks and underspend on large refactors. Composer 2.5 matches effort to task difficulty more sharply.
• Tool call discipline: textual feedback during training reduced wrong-tool calls and recover loops. Expect cleaner trajectories with fewer wasted shell or grep calls.
• Communication style: shorter summaries on simple edits, more structured reasoning on multi-step changes, less hedging.

The harness, tool surface, hooks, rules, and permissions model are unchanged. Anything you wired around Composer 2 still works.

2Pricing Differences

Standard tier pricing is unchanged. Fast tier pricing roughly doubled. If your team uses Fast as the default for interactive IDE work, expect monthly spend on that tier to grow proportionally.

One mitigation: switch background agents and cloud agent runs to Composer 2.5 Standard, where the price is identical to Composer 2 Standard. Reserve Fast for live IDE sessions where latency matters. Cursor included double usage for the first week after the May 18 launch to soften the transition.

3Pre-Migration Audit Checklist

Run through this list before flipping production traffic to Composer 2.5.

• Cursor rules: Search your .cursor/rules directory for any reference to composer-2 by name. Many will continue to work without changes; some compensation rules (for example, "always re-check the test suite before declaring success" that exist because Composer 2 over-claimed completions) may be redundant under 2.5.
• Hooks: Audit pre-tool-use, post-tool-use, and agent-stop hooks. Any hook that filters on the model name needs an update. Any hook that depends on a specific output format needs a smoke test.
• Cursor SDK call sites: Find every Agent.create call with model: "composer-2" or model: "composer-2-fast" and decide which tier is right for that workload.
• Downstream parsers: If you parse Composer's output (run summaries, tool call traces, structured replies), check that your parser tolerates minor format shifts. Composer 2.5 writes shorter summaries on simple changes.
• Eval harness: If you do not have one, build a small one before the switch. Even 20-30 representative tasks with pass/fail outputs is enough to catch most regressions.
• Cost dashboards: Update budgets and alerts. Fast tier is now twice as expensive. If alerts were calibrated to Composer 2 spend, they will fire late.

4Phased Rollout Plan

A practical four-phase rollout that keeps risk manageable:

1. Phase 1 (day 0-3): Update Cursor for one or two engineers as canaries. Have them switch to Composer 2.5 in the IDE, run their normal day, and report unusual behavior. No SDK changes yet.
2. Phase 2 (day 3-7): Roll Composer 2.5 to the rest of the team for interactive IDE use. Keep all background agents and SDK code on Composer 2.
3. Phase 3 (day 7-14): Migrate background and cloud agents to Composer 2.5 Standard one by one. Run the eval harness against each before promoting. Watch cost dashboards for any unexpected jumps.
4. Phase 4 (day 14+): Audit your Cursor rules and hooks for compensations that are no longer needed and remove them. Composer 2.5 needs less hand-holding than Composer 2 in many cases, and over-engineered prompt scaffolding can hurt more than help.

5Updating the Cursor IDE

1. Update Cursor to the latest stable build (May 2026 or later) via Cmd+Shift+P > Cursor: Check for Updates.
2. Restart Cursor.
3. Open the Composer panel with Cmd+I on macOS or Ctrl+I on Windows and Linux.
4. Click the model picker and select Composer 2.5. The Fast variant is the default for interactive sessions.
5. For background agents and cloud agent runs, go to Settings > Models > Composer 2.5 and pick the Standard variant.
6. Verify the active model name in the chat header before starting a long run.

6Updating the Cursor SDK

Update the SDK package, then change the model identifier on every Agent.create call.

# Update the SDK
npm install @cursor/sdk@latest

# Or with pnpm / yarn
pnpm up @cursor/sdk
yarn upgrade @cursor/sdk

Before:

const agent = await Agent.create({
  model: "composer-2",
  workspace: "./",
  systemPrompt: "...",
});

After:

const agent = await Agent.create({
  model: "composer-2.5",
  // or "composer-2.5-fast" for interactive workloads
  workspace: "./",
  systemPrompt: "...",
});

Most production agents should use composer-2.5 (standard) since they run in the background where latency does not matter. Reserve composer-2.5-fast for code paths driven by a developer waiting in front of the screen.

7Eval Harness for Regression Detection

A minimal eval harness for the migration:

// scripts/eval-composer.ts
import { Agent } from "@cursor/sdk";
import tasks from "./eval-tasks.json";

const MODELS = ["composer-2", "composer-2.5"] as const;

for (const model of MODELS) {
  let pass = 0;
  for (const task of tasks) {
    const agent = await Agent.create({
      model,
      workspace: task.workspace,
      systemPrompt: task.systemPrompt,
    });
    const run = await agent.run({
      task: task.prompt,
      maxIterations: 60,
    });
    if (await task.assert(run)) pass += 1;
  }
  console.log(`${model}: ${pass}/${tasks.length} passed`);
}

Pick 20-30 representative tasks for your codebase: a small refactor, a bug fix from a recent issue, a multi-file feature addition, a test scaffolding task, a doc generation job. Write a deterministic assert for each (run tests, grep for expected files, check exit codes).

Compare the pass rate. If Composer 2.5 matches or beats Composer 2 on your eval set, promote it. If a specific task class regresses, you have a clear signal of where to focus the migration audit.

8Common Behavior Shifts to Expect

• Shorter run summaries on small tasks. Composer 2 often wrote a paragraph for a one-line change. Composer 2.5 will write one or two sentences.
• More aggressive task continuation. Composer 2 sometimes declared completion early. Composer 2.5 keeps going if the test suite is still red, even on tasks Composer 2 would have stopped on.
• Fewer redundant tool calls. Tool selection is tighter, especially for grep, file reads, and shell commands. Trajectories are cleaner.
• Sharper effort scaling. Easy tasks finish faster. Hard tasks consume more tokens than they did under Composer 2, because the model is no longer prematurely stopping.
• Different output ordering on multi-step plans. Composer 2.5 tends to lay out the full plan before executing, where Composer 2 sometimes interleaved planning with execution. Downstream parsers that expect the latter pattern need an update.

9Rollback Plan

If Composer 2.5 introduces a regression you cannot fix in the rules layer:

1. In the IDE, switch back to Composer 2 via the model picker.
2. For SDK code, revert the model field to "composer-2" on the affected Agent.create calls. Composer 2 remains supported.
3. File a bug report with Cursor support including the eval task that regressed and the trajectory output.
4. Rerun the eval harness in a few weeks: Cursor pushes regular improvements to Composer 2.5 in place.

10Why Lushbinary for Cursor Migrations

We do model migrations as a service. That includes evaluating the before-and-after on real tasks, finding the rules and hooks that need updating, and tuning per-task model routing so the cheaper tier is the default.

• Eval harness setup tailored to your codebase and review process
• Rules and hooks audit for compensations that are no longer needed
• SDK call-site migration with safe defaults for Standard vs Fast
• Cost dashboards calibrated to the new tier pricing so budget alerts still fire on time
• Multi-model routing so Opus 4.7 or GPT-5.5 only get called on tasks where the cost premium pays back

Sources

• Cursor: Introducing Composer 2.5
• Cursor: Composer 2.5 changelog
• Cursor: Composer 2 technical report
• Cursor: Introducing Composer 2
• Cursor Composer 2.5 Developer Guide (Lushbinary)

Content was rephrased for compliance with licensing restrictions. Pricing and feature availability sourced from official Cursor announcements as of May 19, 2026 and may change. Always verify on cursor.com before committing budget.

Frequently Asked Questions