Getting Started with the Composer Model

Composer is Cursor's own frontier agentic coding model, trained in-house and optimized for one thing: getting real coding work done fast. It plans, edits multiple files, runs terminal commands, and loops through tools with unusually low latency, all at a fraction of the cost of the large frontier models. This guide explains what Composer is, how to select it, where it shines, where you should still reach for Claude or GPT class models, and how to get the most out of it in daily work.

What Is the Composer Model?

Composer is a family of custom models built by the Cursor team rather than licensed from a third party. It is trained specifically for agentic coding: reading your codebase, forming a plan, calling tools, applying edits across files, and verifying results. Unlike general-purpose chat models that were adapted for coding, Composer was optimized from the start for the agent loop.

The design goals behind the model line are:

• Low latency: responses start fast and tool calls execute without long gaps, so the edit-test loop feels immediate.
• Agentic efficiency: the model is tuned to chain tool calls sensibly instead of asking you to micromanage each step.
• Price efficiency: Composer is significantly cheaper per request than the top frontier models, which matters for long agent sessions.
• Practical reasoning: it is strong enough to plan multi-step changes while staying much faster than extended-thinking models.

In the editor it behaves like any other model: you pick it in the model picker and it powers Chat, Agent mode, inline edits, and background agents. The difference is felt in throughput. Tasks that take a frontier model a minute of thinking often complete in seconds with Composer, with quality that holds up well for the majority of everyday coding work.

Composer is not the 2024 Composer feature

Do not confuse the Composer model with the legacy "Composer" multi-file editing feature Cursor shipped in 2024. That early tool was a UI workflow for applying changes across many files, and it was later folded into what is now Agent mode. The Composer discussed in this guide is the model itself, selected from the same picker as Claude and GPT. If you read older tutorials that treat Composer as a separate panel or keyboard shortcut, they are describing the retired feature, not this model.

How Composer Differs from Third-Party Models

Claude, GPT, and Gemini models are general frontier models that Cursor routes to over the network. Composer is a different kind of thing: a model built by Cursor specifically for the agent loop. That difference shows up in behavior even if the exact internals are not public.

Foundation Model Lineage vs Routed Frontier Models

When you select a third-party model in Cursor, you are calling a large, general-purpose model that was trained on a very broad distribution and then wrapped in Cursor's agent harness. When you select Composer, you are calling a model whose design goals were shaped around codebase navigation, tool use, and fast iteration from the start. In practice this means:

• Third-party models bring enormous breadth and deep reasoning, at the cost of latency and price per request.
• Composer brings speed and low cost, tuned for the specific shape of coding tasks rather than for general reasoning benchmarks.
• The harness matters either way. Cursor's tools (file reads, edits, terminal, search) sit in front of both, so the comparison is really about the model's behavior inside that harness.

Speed vs Depth Trade-Off

Think of it as a dial between depth and throughput rather than a binary of "good" and "bad":

• Depth-biased models spend more time planning and reasoning internally, which pays off on ambiguous, sprawling problems.
• Throughput-biased models like Composer act sooner, guess less often than their speed would suggest, and converge fast on well-scoped tasks.
• Most real work is a mix. Default to the throughput-biased end and escalate when a task proves to need depth.

Illustrative Latency Numbers

To make the trade-off concrete, here are rough, illustrative figures. Treat these as approximate ballparks, not measured benchmarks, since latency depends heavily on task size, context length, and load.

Scenario	Composer (approx.)	Frontier model (approx.)
First meaningful token	Well under a second	A second or more
A short single-file edit	A few seconds	Ten to thirty seconds
A multi-file, tool-heavy task	Tens of seconds	One to several minutes

Numbers are directional, not contractual

The figures above exist only to convey the shape of the difference: Composer is consistently faster, and the gap widens on tool-heavy loops. Do not quote them as hard numbers; measure on your own workload if precision matters.

Selecting Composer in the Model Picker

Composer is available anywhere you can choose a model: Chat, Agent mode, and the Composer-style inline workflows inside Agent. To switch to it:

1. Open Chat or Agent mode with the usual panel shortcut.
2. Click the model picker next to the input box.
3. Find Composer in the model list. Cursor's in-house models are grouped separately from third-party models.
4. Select the Composer entry and send your prompt as normal.

You can also make Composer your default model in Settings > Models, so every new chat starts with it. Many developers keep Composer as the default and manually switch to a heavier model only when a task genuinely needs deeper reasoning.

Composer also appears in the model list for background agents, which makes it a natural choice for remote tasks where you are not watching the latency directly but do care about cost and total wall-clock time.

Where Composer Can Be Used

Surface	How to use Composer	Typical cost model
Chat	Pick it in the model picker	Per request, metered against your plan
Agent mode	Same picker, used for multi-step tasks	Per request
Cmd-K / inline edit	Available for fast single-spot edits	Per request
Background agents	Select Composer when starting the task	Per request, longer sessions cost more
Tab completion	Not a picker choice; Tab uses its own model	Metered differently from model requests

Per-Request vs Per-Token Cost

Cursor's plan usage is generally metered per request rather than purely per token, which is why a cheaper-per-request model like Composer stretches a plan much further than its raw token price alone would suggest. Two practical implications:

• Long sessions that chain many tool calls are where Composer's advantage is largest, because each additional step is comparatively cheap.
• If you are used to reasoning about token cost in raw API terms, remember that Cursor surfaces your usage as plan consumption, so the number you watch is the plan meter, not a dollar figure.

Strengths and Trade-Offs

No single model wins everything. Here is how Composer compares with the frontier models you will typically alternate between.

Capability	Composer	Claude Class Models	GPT Class Models
Response latency	Very fast	Moderate to slow	Moderate
Cost per request	Low	High	High to moderate
Multi-file edits	Strong, purpose-built for it	Excellent	Very good
Terminal command fluency	Strong	Excellent	Very good
Deep architectural reasoning	Good	Excellent	Excellent
Long, ambiguous refactors	Good with clear instructions	Best	Very good
Rapid iteration loops	Best	Moderate	Moderate

The pattern is clear: Composer trades a little peak reasoning depth for a large gain in speed and cost. For a large share of day-to-day tasks, such as implementing a well-specified component, fixing a failing test, writing a migration script, or refactoring a module with a clear interface, Composer finishes the job before a frontier model would have finished planning.

Choosing Between Composer and Larger Models

A practical rule of thumb is to default to Composer and escalate when the task shows signs of needing deeper reasoning. Choose Composer when:

• The task is well specified: you know the files, the pattern to follow, and the definition of done.
• You are iterating quickly and expect several small rounds of edits.
• You are running routine maintenance: dependency bumps, renames, formatting-driven refactors.
• You are batching many independent small tasks, where cost adds up fast.

Reach for a Claude or GPT class model when:

• The problem is ambiguous and the model must infer intent from a sprawling codebase.
• You need sustained reasoning across many interdependent modules, for example a protocol change touching client, server, and schema layers.
• You are debugging a subtle concurrency, memory, or correctness issue where wrong guesses are expensive.
• You are doing architecture-level design where the quality of the first plan matters more than the speed of the first response.

Escalate mid-task instead of restarting

If you start a task with Composer and notice it circling without converging, switch the model for the next turn rather than starting a new chat. The existing context, files opened, and plan so far carry over, and the stronger model can pick up where the fast one stalled.

Prompt Tips for Small, Fast Models

Fast models reward precision. Composer responds noticeably better when your prompts remove guesswork, because every guess it does not have to make is latency and tokens saved.

Follow these habits:

• Name the files and directories up front. Fast models plan less broadly, so pointing them at the right surface area immediately keeps them on track.
• State the definition of done. Say what tests should pass, what command should run, or what behavior should change.
• One objective per prompt. Split multi-goal requests into sequential prompts; the agent loop handles chains of small goals far better than one sprawling goal.
• Anchor to existing patterns. Reference a file that already implements the pattern you want and ask the model to follow it.
• Constrain the blast radius. Say explicitly what not to touch, for example "do not modify the public API of UserService".

A well-shaped prompt for Composer looks like this:

In src/services/, add retry logic to the StripeClient class.
Follow the existing retry pattern in src/services/GithubClient.ts
(exponential backoff, max 3 attempts, logs via the shared logger).

Requirements:
- Only src/services/StripeClient.ts and its test file may change.
- Add unit tests mirroring GithubClient.test.ts.
- `npm test -- stripe` must pass when you are done.

Do not modify the public constructor signature.

Compare that with a vague prompt like "add retries to the Stripe client". Both work eventually, but the first version usually lands in one pass, which is exactly what a speed-optimized model is for.

Optimizing Prompts for a Fast Model

The habits above cover the basics; this section goes deeper into shaping a fast model's work so it succeeds on the first pass.

Do and Do Not

Do	Do Not
Name exact files and directories	Ask the model to "find where X is" across the whole repo
State the definition of done	Leave success criteria implicit
Give one objective per prompt	Bundle several unrelated goals into one prompt
Point to an existing pattern to copy	Describe a brand-new pattern in prose alone
List what must not change	Assume the model will infer the blast radius
Ask for a verification step	Skip tests and trust the diff by eye

A Good Prompt vs a Bad Prompt

A diffuse prompt tends to produce a diffuse edit:

Clean up the auth code and make it better.

A scoped prompt gives the fast model everything it needs to land in one pass:

In src/auth/session.ts, extract the token-refresh logic into a
private method refreshToken() and call it from getSession().

Constraints:
- Only src/auth/session.ts and src/auth/session.test.ts may change.
- Keep the public exports of the module identical.
- Mirror the structure of src/auth/oauth.ts, which already does this.
- `npm test -- auth` must pass.

Report the test output when done.

The difference is not politeness or length; it is the number of decisions the model has to make on its own. Fewer decisions means fewer wrong turns and, for a speed-optimized model, fewer wasted seconds.

Scoping Tasks Into Small Steps

Break larger goals into a short sequence and let the agent loop carry each step:

1. Plan: ask for a written plan and confirm it before any edits.
2. Implement: one file or one module per prompt.
3. Verify: run the relevant tests or command after each step.
4. Continue: move to the next step only once the previous one is green.

Give Explicit File References

Prefer paths and symbols over descriptions. "Update src/billing/Invoice.ts" beats "update the invoice code". When you can, paste the exact function name or a short snippet to follow, because the model then spends less time searching and more time editing.

Ask for Verification

Fast models benefit most when you make verification explicit. End prompts with a line such as "run npm test -- <scope> and paste the output", or "report the exact commands you ran". This turns the agent's speed into trustworthy progress rather than unverified motion.

Encoding Team Conventions in Rules

Because Composer optimizes for speed, it leans on guardrails more than a slower model that reasons everything out. Putting your conventions in .cursor/rules pays off disproportionately with fast models. A compact rule file:

---
description: Service layer conventions for fast model edits
globs:
  - "src/services/**/*.ts"
alwaysApply: false
---

- Follow the client class pattern in src/services/GithubClient.ts.
- All network calls use the shared http client; never import axios directly.
- Every public method needs a unit test in the matching .test.ts file.
- Prefer early returns; keep methods under 40 lines.
- After edits, run `npm test -- <affected-scope>` and report results.

With rules like this in place, you can fire short prompts at Composer and trust that the repetitive standards are enforced without restating them every time.

Using Composer in Background Agents

Background agents run Cursor's agent remotely against your repository while you do something else, reporting back with a diff or a pull request. Composer is often the best default there for two reasons:

1. Cost efficiency. Background tasks tend to be longer and more exploratory, and token costs accumulate across the whole session. A cheaper per-request model keeps a fleet of background agents affordable.
2. Throughput. When you fan out several parallel background agents, each one finishing a few minutes earlier compounds into a much snappier overall workflow.

Good background tasks for Composer include writing missing tests for a module, applying a mechanical refactor across a package, generating documentation stubs, and fixing straightforward issues pulled from a tracker. For tasks that require judgment calls across the whole system, start the background agent with a Claude or GPT class model instead, or begin with a planning phase in your foreground editor and hand Composer a precise plan.

Write background prompts like a ticket

A background agent cannot ask you clarifying questions mid-run the way an interactive session can. Give it the goal, the constraints, the files involved, and how to verify success. Treat the prompt as a small, self-contained ticket and Composer will use its autonomy well.

Composer in Background Agents

Background agents are where Composer's cost and speed advantages compound, because you are not sitting and watching each step. Delegating well takes a little discipline.

Delegating Long-Running Tasks

A good delegation prompt is self-contained and ticket-shaped:

Goal: add unit tests for every public method in src/services/Billing.ts.

Context: follow the testing style in src/services/Billing.test.ts if it
exists; otherwise mirror src/services/GithubClient.test.ts.

Scope: only create or edit test files under src/services/. Do not change
production code. If a method looks untestable as written, note it in the
final summary instead of refactoring.

Verify: `npm test -- services/Billing` must pass. Report the output.

Choosing Scope

• Keep a background task to one package, one module, or one concern. Broad tasks drift.
• Prefer mechanical changes for background runs: renames, test coverage, doc stubs, migration scripts.
• Avoid tasks that hinge on taste or architecture judgment; start those in a foreground session where you can steer.

Reviewing the Diff

Background agents return a diff or a pull request, so review it like a teammate's work:

1. Check the files touched against the scope you set. Anything outside the scope is a signal to look closer.
2. Read the agent's summary of what it claims it did, then verify at least one claim in the code.
3. Run the tests locally or confirm the reported output before merging.
4. If the diff is mostly right but has a few rough edges, fix it in the editor rather than re-running the whole agent; the re-run may change unrelated lines.

Unreviewed background diffs are a liability

Because Composer moves fast, it can produce a large diff quickly. Speed of production is not speed of correctness. Treat every background result as a proposal until you have verified the tests and the scope, and schedule review time, not just run time.

Cost and Usage Characteristics

Composer is one of the most price-efficient ways to consume your Cursor plan. Practical implications:

• Substantially more agent requests fit inside your plan's usage allowance compared with running everything on frontier models.
• Long agentic sessions, which chain many tool calls, stay affordable because each step costs less.
• Fast responses mean less wall-clock time per session, which indirectly saves money when you are iterating interactively.

If you monitor usage in the dashboard, you will see the difference clearly after a week of defaulting to Composer: the same volume of completed tasks lands at a noticeably lower share of your quota. A common strategy is to spend frontier-model quota only where it buys real reasoning quality and let Composer absorb the routine volume.

What Counts Toward Your Limits

Chat and Agent requests, Cmd-K edits, and background agent runs all count toward your plan, metered per request. Tab completions are generally handled separately, and reading files or running commands is not billed on its own; cost is driven by the model turns that call them.

Relative Cost, Speed, and Quality

The table below is a rough, approximate comparison to help you pick, not a benchmark. Rankings can shift between model versions and with your task mix.

Model	Relative speed (approx.)	Relative cost (approx.)	Relative reasoning depth (approx.)
Composer	Fastest	Lowest	Good
Claude Sonnet	Moderate	Higher	Strong
Claude Opus	Slowest	Highest	Strongest
GPT-family models	Moderate	High to moderate	Strong
Gemini models	Moderate to fast	Moderate	Strong

Read the table as "Composer wins on speed and cost; frontier models win on peak reasoning". Most teams settle into defaulting to Composer and escalating deliberately, rather than the reverse.

Combining Composer with Other Models

The strongest workflow is not "pick one model forever"; it is routing each phase of a task to the model that fits it.

1. Plan with a reasoning model. Start with a Claude or GPT class model and ask only for a plan: what files to touch, in what order, and how to verify. Do not edit yet.
2. Execute with Composer. Once the plan is written and you agree with it, switch the model to Composer for the actual edits. A fast model with a clear plan outperforms a fast model discovering the plan as it goes.
3. Review with a second model. After the edits land, switch to a different model and ask it to review the diff for correctness, edge cases, and missed requirements. A fresh model reading the result catches things the executing model rationalized away.

Phase 1 (Claude/GPT, plan only):
"Read src/payments/ and propose a step-by-step plan to add idempotency
keys to the charge endpoint. List files, order, and verification. Do not edit."

Phase 2 (Composer, execute):
"Implement step 1 from the plan. Only src/payments/charge.ts may change.
Run `npm test -- payments` and report output."

Phase 3 (second model, review):
"Review this diff for correctness and edge cases. Flag anything that
breaks idempotency under retries."

This plan-execute-review loop keeps the expensive, deep-reasoning calls small and concentrated, while Composer absorbs the volume of actual editing.

Same context, different model

Switching models mid-task keeps the chat, open files, and plan intact, so the handoff between phases costs nothing. You do not need to re-explain the task; just change the picker and continue.

The Road Ahead: Composer 3

The Composer line is under active development, and the community roadmap is already full of requests for a next iteration, often referred to as Composer 3. Recurring themes in that discussion include stronger long-horizon planning, better performance on very large repositories, and improved reliability on ambiguous multi-step tasks, while keeping the signature low latency and low cost.

You do not need to wait for any of that to benefit today. The current Composer models are production-quality daily drivers, and because model selection is a dropdown rather than a commitment, you can adopt them now and switch the moment a newer generation lands in the picker.

Common Problems and Limitations

Composer is fast, and speed has failure modes you should recognize early.

Making Large Sweeping Edits

Composer can attempt a repo-wide change in one go and leave a sprawling, hard-to-review diff.

• Cause: an unscoped prompt like "refactor the logging everywhere".
• Fix: constrain the change to one package or module, or break the task into a short sequence of scoped prompts. Ask for a plan first if the change truly is wide.

Losing Instructions in Long Tasks

Over a long session, earlier constraints can get diluted as context grows.

• Cause: many turns with shifting goals in a single chat.
• Fix: restate critical constraints when you change direction, or start a fresh chat with a compact summary of the goal and the rules. Rules files in .cursor/rules also help pin conventions across a session.

Hallucinated APIs

Fast models occasionally reference methods or packages that do not exist.

• Cause: the model pattern-matches from training rather than from your codebase.
• Fix: give explicit file references and ask it to verify against the actual source. If it invents an API, point at the real one and ask it to redo the edit using only symbols that exist in the repo.

Needing a Full-Codebase Refactor

Some refactors genuinely span the whole system and exceed what a fast model handles well in one pass.

• Cause: the change has cross-cutting dependencies and ambiguous boundaries.
• Fix: plan it with a reasoning model first, then execute it as a series of scoped Composer steps, verifying after each. Consider one background agent per package rather than a single giant run.

Timeouts or Stalls

Occasionally an agent run stalls or times out, especially on very large tasks.

• Cause: an overly broad objective, a huge context, or a single step that never resolves.
• Fix: narrow the task and retry; if it recurs, split the work into smaller steps, and consider a frontier model for the step that keeps stalling. Scope long background runs so a stall costs you minutes, not an hour.

Symptom to Cause to Fix

Symptom	Likely Cause	Fix
Huge, unreviewable diff	Unscoped prompt	Constrain scope; ask for a plan and split into steps
Model ignores earlier constraints	Context dilution over a long chat	Restate constraints or start a fresh, summarized chat
Model calls methods that do not exist	Training-based pattern matching	Give file references; ask it to verify against real symbols
A whole-codebase refactor feels unsafe	Cross-cutting change	Plan with a reasoning model, then execute as scoped steps
Run stalls or times out	Overly broad task or oversized context	Narrow and retry; split into smaller steps

Frequently Asked Questions

Is Composer the same as the 2024 Composer feature?

No. The 2024 "Composer" was a multi-file editing workflow in the Cursor UI, later folded into Agent mode. The Composer in this guide is a model, selected from the same picker as Claude and GPT.

What model does Composer run on?

Composer is Cursor's own in-house model line, trained by the Cursor team rather than routed to a third party. Its speed and cost profile come from that focus rather than from a general-purpose foundation model.

When should I choose Composer over Claude or GPT?

Default to Composer for well-specified, fast, iterative work. Escalate when a task is ambiguous, spans many interdependent modules, or needs deep architecture-level reasoning.

Is it good enough for real, production work?

Yes, for the large majority of everyday tasks: implementing specified components, fixing tests, mechanical refactors, and routine maintenance. For high-stakes reasoning, pair it with a frontier model using the plan-execute-review workflow.

Does it cost extra?

It is one of the cheapest ways to consume your plan. Because plans are largely metered per request, a low-cost-per-request model lets more work fit inside your allowance.

Can I switch models in the middle of a task?

Yes, and you should. The chat, open files, and plan carry over, so you can plan with a reasoning model and then switch to Composer to execute without losing context.

Why would my edits stall or chase their tail?

Usually because the task was too broad for a single pass. Narrow the scope, give explicit files, and verify after each step rather than expecting one prompt to do everything.

Will there be a Composer 3?

The community discussion points toward a next generation with stronger long-horizon planning and large-repo performance. You do not need to wait; model selection is a dropdown, so you can adopt a newer version the day it appears.

Quick Reference

Question	Answer
What is Composer?	Cursor's in-house, speed-optimized agentic coding model
Where do I select it?	Model picker in Chat and Agent mode, or Settings > Models
When should I not use it?	Deep, ambiguous, architecture-heavy reasoning tasks
Is it the old Composer feature?	No, the 2024 multi-file tool was folded into Agent mode
Does it work in background agents?	Yes, and it is a cost-effective default there
What is next?	Community discussion of a Composer 3 generation

Composer rewards a simple workflow: default to it, write precise prompts, encode your conventions in rules, and escalate to frontier models only when a task genuinely needs deeper reasoning. That habit gets you the speed and cost benefits of Cursor's own model line without giving up quality where it counts.