Cursor Composer Guide

Composer is the agentic editor built into Cursor. Where Cmd+K edits one selection and Chat answers questions, Composer can read many files, make edits across them, run shell commands, and iterate for multiple steps on a single task. This page covers the normal mode vs agent mode distinction, how to write good prompts, and when Composer is the wrong tool.

Opening Composer

Press Cmd+I on macOS or Ctrl+I on Windows. The Composer panel opens on the right side of the editor. A fresh panel shows an input box, a model picker, and a context bar above the input.

The model picker in April 2026 defaults to Claude Sonnet 4.5. You can switch to Opus 4, GPT-4o, Gemini 2.5 Pro, or your own custom model. Model choice affects cost more than capability for most Composer tasks; Sonnet is the right default.

Normal mode vs agent mode

The toggle above the input switches between two modes.

Normal mode behaves like an enhanced Chat. It reads the files you explicitly add to context, proposes edits as a diff, and does not touch anything else. Good for: single feature changes, small refactors, bug fixes with a known location.

Agent mode gives Composer tool access. It can open files by searching the codebase, write new files, edit existing ones, run terminal commands, and decide its own next step. Good for: tasks you cannot fully scope in advance, debugging across unknown files, running tests and reacting to output.

Agent mode costs 3-5x more premium requests than normal mode because every tool call round-trips to the model. Use it when the savings in human time outweigh the extra cost.

How agent mode reads and edits files

When you send a prompt in agent mode, Composer picks a tool on each step:

• read_file - open a specific path
• codebase_search - semantic search across the indexed project
• grep_search - literal string match
• list_dir - see contents of a folder
• edit_file - apply a diff to a file
• run_terminal_cmd - execute a shell command
• web_search - pull external docs

The agent chains these together. A typical feature task looks like: codebase_search for the feature area, read_file on the 3-4 most relevant files, edit_file for each change, run_terminal_cmd to run the test suite, read_file again if a test failed, edit_file to fix. Ten to fifteen steps is normal for a non-trivial task.

Terminal access

In agent mode Composer can run shell commands. It prompts for approval on each command by default. You see the exact command string and can accept, reject, or edit before it runs.

Common commands the agent requests:

• pnpm test or npm test after making changes
• pnpm lint to verify formatting
• git status and git diff to see its own work
• Migration commands like pnpm prisma migrate dev

Turn on auto-run for read-only commands under Settings > Features > Composer Agent if you want less interruption. Write-y commands still require approval.

The context bar

Above the input box is the context bar. This is where you add information Composer should see:

• @File - attach a specific file
• @Folder - attach a directory
• @Code - attach a function or class by name
• @Docs - pull docs from a URL or indexed site
• @Web - real-time web search
• @Codebase - semantic search across the whole project
• @Terminal - last terminal output
• @Notepad - a saved prompt scratchpad

You do not need to attach the target files in agent mode because the agent finds them itself. In normal mode, attach everything the edit will touch.

Writing good Composer prompts

The prompts that produce clean output share three properties:

1. Be specific about files or areas. "Update the navbar" is vague. "Update src/components/Navbar.tsx to add a dark mode toggle that reads from the ThemeContext in src/contexts/theme.tsx" is actionable.
2. State the expected output. "Add tests for the PaymentService" is ambiguous. "Add a Vitest file at src/services/__tests__/payment.test.ts covering the happy path, a declined card, and a network timeout" produces testable output.
3. List constraints. "Do not touch the existing Stripe integration" or "Use the same error handling pattern as UserService" prevents drift.

A working prompt template:

Task: <what to build>
Files: <known files, or "search the codebase">
Constraints: <what not to change, conventions to follow>
Done when: <acceptance criteria>

The diff review flow

After Composer proposes edits, each changed file shows a diff with three buttons: Accept, Reject, Reject with feedback.

Accept applies the diff. Reject throws it away. Reject with feedback lets you type a correction, and Composer tries again on that file only.

Review diffs file by file. Do not click Accept All unless the change is small. A common failure mode is accepting a 10-file change without reading, then finding a test broken three commits later with no idea which edit caused it.

Iterating in the same session

Follow-up messages in the same Composer session keep the full context. This is how you guide a task to completion without restarting:

First message: Add the dark mode toggle.
Second message: The toggle shows but does not persist across reloads. Use localStorage.
Third message: The localStorage key should be "theme" to match the existing useTheme hook.

Each follow-up adds new context. Sessions longer than 20 messages start to drift as the model context grows. Start a fresh session when the topic shifts.

Checkpoints

Composer saves a checkpoint at every tool call in agent mode. The checkpoint panel on the left of Composer shows each step. Click a checkpoint to revert the working directory to that state.

This is the safety net for agent mode. If the agent went off track on step 7 of a 12-step task, revert to step 6 and send a follow-up message that steers differently. You do not have to start over.

Checkpoints are local only and not tied to git. Commit your work before a long Composer session if you want a real backup.

Long tasks

Agent mode can run 10-20 steps on a complex feature without intervention. Sample tasks that sit in that range:

• Add a new REST endpoint end-to-end: route, handler, service, tests, OpenAPI spec update
• Migrate a component library from MUI to shadcn/ui in one directory
• Add i18n support: detect all user-facing strings, extract to a locale file, replace inline usage

Expect 10-20 premium requests and 5-10 minutes of wall time. Walk away, check back, review diffs.

When Composer struggles

Composer is weaker at:

• Very large codebases (10k+ files) where codebase_search returns too many candidates
• Dynamic JavaScript where types are implicit and the model cannot trace data flow
• Tasks with ambiguous requirements, where the agent tries to guess intent and usually gets it wrong
• Cross-repo changes; Composer works within a single workspace

For large codebases, help the agent by pinning specific files or directories with @Folder before starting. For ambiguous tasks, spend two minutes writing a tighter prompt instead of re-running the agent three times.

Composer vs Chat

Chat (Cmd+L) and Composer look similar but differ in one key way: Chat cannot edit files. It explains, answers, and shows code suggestions you copy yourself.

Use Chat when you want to learn the codebase, debug an error message, or get a second opinion on a design. Use Composer when you want the change actually applied.

Composer vs terminal agents

Cursor Composer competes with terminal-based agents like Claude Code and Aider. The tradeoffs:

• Composer stays in the editor, so the diff review UI is better integrated
• Terminal agents have no editor context, so they rely more on the file system and git
• Composer costs premium requests from your Cursor subscription; terminal agents bill your own API key
• Terminal agents tend to be better at multi-step shell work; Composer is better at code edits

If you already pay for Cursor Pro and spend most of your time in the editor, Composer is the right default. If you want to run agents in headless mode or in CI, terminal agents win.