Intermediate25 min1 prerequisite

Learn to use Cursor's Composer for multi-file code generation, complex refactoring, and agentic coding workflows.

Mastering Composer

Composer is Cursor's most powerful feature. While Chat and inline editing work on single files, Composer can create, modify, and refactor code across your entire project—acting like an AI pair programmer that understands your whole codebase.

What Makes Composer Different

Feature	Inline (Cmd+K)	Chat (Cmd+L)	Composer
Single file edits	✅	✅	✅
Multi-file edits	❌	❌	✅
Create new files	❌	❌	✅
Run terminal commands	❌	❌	✅
Agentic mode	❌	❌	✅
Context awareness	Current file	Attached files	Full codebase

Opening Composer

Keyboard: Cmd+I (Mac) or Ctrl+I (Windows/Linux)
Menu: View → Composer

Composer opens as a full-width panel, giving you space to describe complex tasks.

Composer Interface

Terminal

┌──────────────────────────────────────────────────────────────────┐
│ Composer                                              [Settings] │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  [Agent Mode ◉]  [Normal Mode ○]                                 │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │ Describe what you want to build or change...              │  │
│  │                                                            │  │
│  │                                                            │  │
│  └────────────────────────────────────────────────────────────┘  │
│                                                                  │
│  Context: @file1.ts @file2.ts                       [+Add File]  │
│                                                                  │
│  [Generate]                                                      │
└──────────────────────────────────────────────────────────────────┘

Basic Composer Usage

Creating New Features

Describe what you want to build:

Terminal

Create a user authentication system with:
- Login and registration pages using React and Tailwind
- Form validation with Zod
- API routes for auth endpoints
- JWT token handling
- Protected route wrapper component

Composer will:

Create multiple files
Set up proper imports
Establish the authentication flow
Connect components together

Multi-File Refactoring

Terminal

Refactor the user management code:
1. Extract the API logic from pages/users.tsx into lib/api/users.ts
2. Create a custom hook useUsers in hooks/useUsers.ts
3. Add proper TypeScript types in types/user.ts
4. Update all imports across the project

Adding to Existing Code

Terminal

Add dark mode support to this application:
- Create a ThemeContext
- Add a toggle button in the header
- Update all component styles to support dark mode
- Persist preference to localStorage

Agent Mode

Agent mode lets Composer work autonomously—it can run commands, check results, and iterate until the task is complete.

Enabling Agent Mode

Toggle "Agent Mode" in the Composer interface, or use keyboard shortcut variations.

What Agent Mode Can Do

Run terminal commands
Terminal
```
Set up this project with ESLint, Prettier, and Husky
```
Composer runs npm install, creates config files, and sets up hooks.
Check its own work
Terminal
```
Create a new API endpoint and write tests for it
```
Composer creates the endpoint, writes tests, runs them, and fixes any failures.
Iterate on errors
Terminal
```
Fix all TypeScript errors in this project
```
Composer finds errors, fixes them, checks again, and continues until clean.

Agent Mode Example

Prompt:

Terminal

Create a new Next.js API route at /api/products that:
- Connects to our Supabase database
- Returns paginated products
- Supports filtering by category
- Include tests

Agent Mode steps:

Creates /api/products/route.ts
Adds Supabase query logic
Creates test file
Runs tests
Fixes any failing tests
Confirms all tests pass

Adding Context

Manual Context

Click "+Add File" or use @ mentions:

Terminal

@components/Button.tsx @components/Card.tsx @lib/styles.ts
Create a new Modal component that matches our existing design system

Automatic Context

Composer automatically includes:

Currently open files
Recently edited files
Files related to your request
Type definitions and imports

Codebase Context

Reference your entire project:

Terminal

@Codebase
How do we handle errors across this application?
Show me all the patterns, then create a unified error handling approach.

Reviewing Changes

The Diff View

After generation, Composer shows all changes:

Terminal

┌─ Changes ─────────────────────────────────────────────────────────┐
│                                                                   │
│ 📁 components/                                                    │
│   ├─ Modal.tsx (new file)                                        │
│   ├─ Button.tsx (modified)                                       │
│   └─ index.ts (modified)                                         │
│                                                                   │
│ 📁 lib/                                                          │
│   └─ hooks/useModal.ts (new file)                                │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

Click any file to see the specific changes.

Accepting Changes

Accept All: Apply all changes at once
Accept File: Apply changes file by file
Reject: Discard and start over
Edit: Modify the prompt and regenerate

Partial Acceptance

You can accept some files and reject others:

Review each file's changes
Accept files you want
Reject files that need more work
Prompt again for remaining changes

Effective Composer Prompts

Structure Your Request

Break complex tasks into clear steps:

Terminal

Build a blog system:

1. Database:
   - Posts table with title, content, slug, publishedAt
   - Authors table with name, bio, avatar
   - Relationship: posts belong to authors

2. API Routes:
   - GET /api/posts - list with pagination
   - GET /api/posts/[slug] - single post
   - POST /api/posts - create (auth required)

3. Components:
   - PostCard - preview card for listing
   - PostContent - full post view
   - PostForm - create/edit form

4. Pages:
   - /blog - post listing
   - /blog/[slug] - individual post
   - /admin/posts - post management

Reference Existing Patterns

Terminal

@components/UserCard.tsx @components/ProductCard.tsx

Create an OrderCard component following the same patterns:
- Same styling conventions
- Same prop structure
- Same responsive behavior

Specify Technical Requirements

Terminal

Create a file upload component:
- Use React Hook Form
- Accept images only (jpg, png, webp)
- Max 5MB file size
- Show preview before upload
- Progress indicator during upload
- Use our existing @Button and @Input components
- Upload to our Supabase storage bucket

Common Composer Workflows

Scaffold a New Feature

Terminal

Create a complete user settings feature:
- Settings page with sections for Profile, Security, Notifications
- API endpoints for each settings type
- Form validation with error handling
- Success/error toast notifications
- Match the existing app style

Migrate Code

Terminal

Migrate our authentication from NextAuth to Clerk:
1. Remove NextAuth packages and config
2. Install Clerk
3. Update all auth references
4. Update protected routes
5. Update user session handling

Add Testing

Terminal

Add comprehensive tests to the checkout flow:
- Unit tests for price calculations
- Integration tests for cart operations
- E2E tests for the complete checkout process
- Use Jest and React Testing Library
- Follow our existing test patterns in @tests/

Documentation

Terminal

Generate documentation for our API:
- README.md with setup instructions
- API.md with all endpoints documented
- JSDoc comments for all public functions
- TypeScript types exported and documented

Tips for Better Results

Start Small, Then Expand

Terminal

// First prompt
Create a basic Card component with title and content

// After accepting
Add image support and action buttons

// After accepting
Add variants: default, outlined, elevated

Provide Examples

Terminal

I want a toast notification system.
Here's an example of how I want to use it:

toast.success('User created!')
toast.error('Something went wrong')
toast.promise(saveUser(), {
  loading: 'Saving...',
  success: 'Saved!',
  error: 'Failed to save'
})

Be Explicit About What Not To Do

Terminal

Create form validation:
- DO use Zod for schema
- DO NOT use Yup
- DO NOT modify existing API routes
- Keep validation logic in a separate file

Troubleshooting

Composer Doesn't See All Files

Make sure files are part of your workspace
Check .cursorignore isn't excluding them
Explicitly @ mention the files
Open the files in tabs

Changes Are Incomplete

Break the task into smaller pieces
Add more specific context
Reference similar existing code
Use Agent mode for complex tasks

Generated Code Doesn't Match Style

Reference existing files that show your style
Include your .cursorrules file
Be explicit about patterns to follow

Summary

Cmd+I opens Composer for multi-file operations
Agent mode lets Composer run commands and iterate
Add context with @ mentions for better results
Review diffs carefully before accepting
Structure prompts clearly for complex tasks
Iterate incrementally for best results

Next Steps

Composer follows your conventions better when you set up Rules for AI—the next lesson covers how to configure these project-specific instructions.

Mark this lesson as complete to track your progress