Composer and Agent Mode: Multi-File AI Editing

What Is Composer?

Composer (Cmd+I) is Cursor's multi-file editing interface. While Chat is for conversation, Composer is for making changes — across multiple files, in a single AI-driven session.

You describe a task, Composer reasons about what needs to change, and presents a diff across however many files are involved. You review, approve, or reject changes file by file or all at once.

Opening and Using Composer

Press Cmd+I to open Composer as a floating window, or Cmd+Shift+I to open it in a dedicated full panel.

A good Composer prompt is task-oriented and specific:

Add a "delete account" feature. It should:
- Add a DELETE /api/users/me endpoint that marks the account as deleted (soft delete)
- Add a confirmation modal to the account settings page
- Clear the session after deletion
- Send a confirmation email using the existing email service

Use the existing auth patterns in @Files src/lib/auth.ts and follow the API route structure in @Files src/app/api

Reviewing Composer Output

After Composer runs, you see a diff view showing every proposed change. You can:

• Accept All — Apply every change at once
• Reject All — Discard everything
• File-by-file review — Accept or reject individual files
• Inline edit — Click into any diff and modify it before accepting

Always review Composer output before accepting. The AI makes mistakes. Treating its output as a first draft that you review — rather than a finished product — is the correct mental model.

Agent Mode

Agent mode is Composer with terminal access. In addition to reading and writing files, it can:

• Run shell commands (npm install, git, make)
• Execute tests and read the output
• Fix errors it encounters, iterating until the tests pass
• Install dependencies it determines are needed

Enable Agent mode from the Composer toolbar. Cursor will ask for approval before running commands (configurable).

Agent Mode Best Practices

Agent mode is powerful but requires careful oversight:

Good uses:

• "Set up a new feature branch and scaffold the file structure"
• "Run tests, identify the failing ones, and fix them"
• "Install dependencies and update the lock file"

Risky uses (require extra review):

• Anything involving database migrations
• Git operations that modify history
• File deletions

Always run agent mode on a clean git branch so you can inspect the full diff and revert if needed.

Checkpoint Strategy

For complex Composer/Agent tasks, use a checkpoint strategy:

1. Commit your current state before starting
2. Run Composer/Agent for one logical unit of work
3. Review the diff carefully
4. Commit what you want to keep
5. Repeat for the next unit

This gives you granular control while still benefiting from AI-driven multi-file editing.

Key Takeaways

• Composer (Cmd+I) makes multi-file changes — always review the diff before accepting
• Agent mode adds terminal access for running commands and iterating on tests
• Use specific, task-oriented prompts with @Files references for best results
• Always work on a git branch when using Composer or Agent mode