Mastering Cursor Composer & Agent Mode: The Complete Guide

Cursor Composer is the multi-file editing interface inside the Cursor IDE, and Agent mode makes it autonomous. Instead of copying and pasting code snippets back and forth between a chatbot and your editor, this interface operates directly within your workspace to edit files, run terminal commands, and iterate on errors based on your descriptions.

This guide covers how to use Composer and Agent mode effectively, including available modes, shortcuts, model lineups, context management, and practical troubleshooting steps.

What Cursor Composer Actually Is

Composer is the multi-file editing interface inside the Cursor IDE. Opened with Cmd/Ctrl + I, it allows you to toggle between three distinct modes:

Mode	What It Does	Picks Files?	Runs Terminal?	Best For
Normal	Edits files you specify	No, you manually select them	No	Targeted changes to known files
Agent	Autonomous multi-file agent	Yes, automatically finds them	Yes	Full features, refactors, new pages
Ask	Read-only sidebar chat	No	No	Questions about code, explanations

Composer is the user interface, while Agent is a specific autonomous mode inside it. Normal and Ask are the other two modes, which you can cycle through using Shift + Tab.

Agent mode reads your codebase, picks relevant files, creates new ones, runs terminal commands, checks for errors, and iterates on its own edits without requiring you to specify every file beforehand.

Composer Model Lineup

Cursor includes a family of agentic models tailored specifically for Composer. Selecting the right model affects speed, quality, and quota usage.

Model	What It Is	Best For	Trade-off
Composer 1	Original multi-file model	Simple multi-file edits	Slower than newer iterations
Composer 1.5	Faster, more reliable iteration	Day-to-day Agent mode	Strong default for most workflows
Composer 2	Reinforcement learning-trained frontier model	Hard refactors, long-horizon tasks, autonomous loops	Higher quota usage

• Composer 1.5 is the standard default for routine feature work and refactoring.
• Composer 2 is designed for tasks where the agent must plan, edit, run tests, read failures, and re-edit in autonomous loops.
• Composer 1 is largely legacy and superseded by newer models.

You can select the model from the dropdown inside the Composer panel.

Opening & Core UX

Shortcut	Action
Cmd/Ctrl + I	Open Composer (inline)
Cmd/Ctrl + Shift + I	Open Composer (full-screen)
Shift + Tab	Cycle modes: Normal, Agent, Ask
Cmd/Ctrl + Enter	Force send message
@	Mention files, folders, symbols, docs

Full-screen mode (Cmd + Shift + I) provides more screen space to review multi-file diffs. Composer opens in whatever mode you last used, so ensure you check the mode badge in the top-right of the Composer panel before starting a new task.

Your First Prompt: A Todo App in One Turn

To test Agent mode's capabilities, open a new empty folder, hit Cmd/Ctrl + I, switch to Agent mode, and enter the following prompt:

Build a single-page Todo app. Requirements:
- Vanilla HTML/CSS/JS, no build step
- Add, complete, delete tasks
- Persist to localStorage
- Minimal styling, dark background, white text
- Single index.html file plus a styles.css and app.js

The Agent will:

1. Plan the file layout.
2. Create index.html, styles.css, and app.js.
3. Configure the localStorage persistence.
4. Display a diff for each file.

If any adjustment is needed, you can enter feedback directly into the Composer:

Tasks disappear when I refresh the page. Fix it.

The Agent reads the existing files, identifies the bug, and patches the relevant code.

Composer vs Chat vs Agent: When to Use Each

• Use Ask mode when you want to understand code without changing it (e.g., explaining a regular expression or a specific function). This is a read-only mode that does not write to disk.
• Use Normal mode when you know exactly which files need to change and want tight control. You manually reference the files, describe the change, and review the diff.
• Use Agent mode for new features, refactors touching multiple files, or tasks requiring command execution (e.g., compiling code or running a build script to check for errors).

As a rule of thumb, if you need to open and modify more than two files, Agent mode is generally the faster option.

Context Mastery: @Mentions, Rules, Ignore, and Notepads

Agent mode requires clear context to avoid modifying the wrong files or generating incorrect code.

@Mentions (Manual Context)

Mention	What It Does
@filename	Adds a specific file to the context
@folder/	Adds all folder contents
@symbol	References a function, class, or variable
@docs	Searches indexed documentation
@web	Searches the web for current information
@codebase	Performs a semantic search across the whole project
@past chats	References previous conversations

The @codebase mention is highly useful for scanning the repository. For example: "Using @codebase, find all components that use the useAuth hook and add a loading state."

.cursor/rules/ (Automatic Context)

You can configure automatic rules for your project using a .cursor/rules/ directory containing .mdc (Markdown) files. Each rule file uses YAML frontmatter to control when it applies:

---
description: "TypeScript coding standards for this project"
globs: "**/*.ts,**/*.tsx"
alwaysApply: true
---

- Use strict TypeScript. No `any` types.
- Prefer `const` over `let`.
- All components must have explicit return types.
- Import order: React, external libs, internal modules, styles.

Setting alwaysApply: true ensures the rule is loaded into every Agent session automatically. You can also set it to intelligent (decided by relevance) or manual (only when referenced).

.cursorignore

Similar to .gitignore, this file tells the IDE which folders and files to exclude from the context window, such as large build folders, generated files, or sensitive configurations.

Notepads

Notepads are reusable context bundles that you can reference like files. They are ideal for storing API schemas, design specifications, or user stories. Create them in the Notepads panel and reference them using @notepad-name.

Multi-File Editing & Checkpoints

Agent mode modifies multiple files concurrently and displays the diffs for review. It is recommended to review all diffs carefully before accepting them, especially when changes span multiple files.

Checkpoints

The editor automatically creates checkpoints before executing major changes. If a change breaks functionality, you can select "Restore Checkpoint" in the timeline to revert the AI-generated edits while leaving your manual changes intact. It is still recommended to commit your progress via Git before running large Agent tasks.

Pro Prompts That Work

The Full Feature Build

Build a pricing page at /pricing with 3 tiers: Free, Pro ($20/mo), Enterprise (contact us). Use our existing Card component from @src/components/ui/Card.tsx. Add the route to the App Router. Match the style of @src/pages/about.tsx.

The Targeted Refactor

Using @codebase, find every component that uses the deprecated `useUserContext` hook. Replace it with `useAuth` from @src/hooks/useAuth.ts. Update imports and types.

The Migration

Convert @src/styles/Button.module.css to Tailwind classes in @src/components/Button.tsx. Delete the CSS file after migration. Keep the same visual appearance.

The Test Writer

Write unit tests for @src/lib/pricing.ts using vitest. Cover:
- All plan tiers return correct limits
- Edge case: expired trial
- Error case: invalid plan ID
Follow the patterns in @src/lib/__tests__/auth.test.ts.

The Architecture Spec First

I want to add Stripe checkout. Before writing code, outline:
1. Files you'll create/modify
2. Dependencies needed
3. Environment variables required
4. The data flow from button click to payment confirmation
Then implement it.

Asking the agent to lay out a plan before writing code helps prevent structural errors across multiple files.

Background Agents & Parallel Execution

• Background Agents run asynchronously in separate cloud sandboxes. You can start a task (e.g., refactoring API middleware) and switch to another task while it processes on a separate branch.
• Parallel Agents allow you to run multiple agents concurrently in separate git worktrees, isolating changes at the filesystem level.

Pricing & Quota Considerations

• Hobby Plan (Free): Limited Agent requests, standard autocompletions, and basic Agent access.
• Pro Plan ($20/mo): Extended Agent use, access to frontier models, MCP plugins, and cloud agents.
• Pro+ ($60/mo): Three times the credits of the Pro plan, plus all Pro features.
• Ultra ($200/mo): Priority access and maximum credit allocations.
• Teams ($40/user/mo): Shared rules, admin tools, and centralized billing.

Note that Agent usage is split between the Auto/frontier model pool (for Claude or GPT-4-class third-party models) and the Composer pool (when choosing Composer 1.5 or 2). Long sessions that switch models can deplete both pools. Using Composer 1.5 for standard edits and switching to Composer 2 for complex tasks helps manage quota limits.

Failure Modes & Workarounds

• Context Compaction dropping rules: During long sessions, older context is compressed, which can silently drop rules. Keep Agent sessions short (one feature per session), use explicit @ mentions in your prompt, and restart the Composer session for major new tasks.
• Agent modifying ignored files: Agent mode may attempt to edit files listed in .cursorignore if it determines they are relevant. To prevent this, add explicit instructions like "Do NOT modify files in /src/generated/" to your prompt.
• Skipping rules in Agent mode: The Agent may occasionally bypass rules marked as intelligent. Set critical project rules to alwaysApply: true or manually reference them using @.
• High token consumption: Long conversations send a large volume of context tokens with each message. Start a new Composer session once a specific task or feature is complete to reset the context window.
• Hallucinations on novel tech stacks: If you are working with a niche framework, the model may generate invalid API calls. Address this by attaching documentation via @docs and saving correct usage patterns in .cursor/rules/.

Standard Agent Workflow

1. Define the Goal: Open Agent mode and outline the feature, referencing existing styles or components (e.g., "Build a dashboard page. Use the existing layout from @src/layouts/DashboardLayout.tsx.").
2. Review the Plan: Read the Agent's proposed file creations and modifications. Accept or redirect.
3. Monitor the Build: Allow the Agent to create files, import components, and check build outputs.
4. Resolve Errors: If compilation errors or type mismatches occur, paste the logs back into the Composer so the Agent can debug them.
5. Commit Changes: Once the feature is working as expected, commit the changes using Git.

Using Agent mode helps automate the writing of boilerplate and multi-file updates, leaving the developer to focus on code review, security audits, and edge cases.