Agent Mode and Plan Mode

What Agent Mode Is

Press Cmd+I to open Composer and activate Agent Mode. Agent is Cursor's most powerful AI surface. Unlike Chat, which proposes changes for you to apply, Agent autonomously reads and modifies code across multiple files, creates new files, and runs terminal commands — all to complete the high-level task you describe.

The Agent workflow:

1. You describe the task in plain language.
2. Agent searches your codebase to understand the relevant context.
3. Agent proposes a sequence of file changes.
4. You review each change as a diff and approve or reject it.
5. If you enabled auto-run, Agent can also execute terminal commands (npm install, test runs, build steps) and react to their output.

Plan Mode: The Feature Most Developers Skip

Plan Mode is activated by pressing Shift+Tab in the Agent prompt box instead of Enter. It is, arguably, the most important feature in Cursor — and most users never use it.

Here is what happens when you use Plan Mode instead of sending your request directly:

1. Agent does not write any code immediately.
2. Instead, it researches your codebase: reads relevant files, identifies existing patterns, maps dependencies.
3. It may ask you clarifying questions about intent or constraints.
4. It then writes a detailed, step-by-step plan showing exactly what it intends to do and why.
5. You read the plan, request changes if needed, and then approve it.
6. Only after your approval does Agent begin writing code.

This costs about 30 extra seconds. The benefit is that Agent starts with a correct understanding of your project and a plan you've validated. The alternative — letting Agent run without a plan — risks it going in the wrong architectural direction and producing dozens of file changes you then have to unpick.

When to Always Use Plan Mode

• Any task that will touch more than three or four files.
• New features that involve architectural decisions (database schema changes, new API routes, new components that others will depend on).
• Large refactors: moving from one library to another, restructuring a module, changing a shared type.
• Framework migrations.
• Any time you are not entirely sure of the right approach yourself — if you don't have a plan, let Agent draft one for you to review.

Writing Good Agent Prompts

Agent quality scales directly with prompt quality. The most common failure mode is a vague prompt: "make this better" or "refactor the auth system" give Agent too little to work with. Better prompts specify:

• The specific task and its goal.
• Which files or areas are in scope.
• Any patterns to follow (e.g., "follow the same pattern as the existing GET /users route").
• Explicit constraints (e.g., "do not change the database schema", "keep backward compatibility").

Reviewing Agent Changes

Agent shows every file it modifies as a diff before finalising. Read every one. Agent can:

• Import a library that isn't in your package.json.
• Introduce a subtle logic error in a rarely-hit code path.
• Solve the stated problem correctly but in a way that conflicts with a constraint you forgot to mention.

The review step is not a formality — it is where your expertise as a developer adds value on top of the AI output. Accept the changes that are right, reject or edit the ones that are wrong, and keep moving.