Agent Mode

The Autonomous Coding Partner

🔄 In Lessons 3 and 4, you learned tools that assist your coding: Tab predicts your next edit, Cmd+K transforms code you highlight, and Chat answers questions about your codebase. In each case, you’re in the driver’s seat.

Agent mode flips the script. You describe what you want, and Cursor does it — reading files, writing code, running terminal commands, and iterating until the task is done.

It’s the most powerful feature in Cursor. And the most dangerous one if you don’t understand the safety controls.

How Agent Mode Works

Open Composer with Cmd+I, then toggle Agent mode with Cmd+. (it’s the default mode in Cursor 2.0).

Give it a task in plain English:

“Add a password reset feature with email verification”
“Convert the users API from REST to GraphQL”
“Fix the failing tests in the auth module”

What Agent does next:

Reads your codebase — scans relevant files to understand the current structure
Plans the approach — decides which files to create, modify, or delete
Makes edits — writes code across multiple files simultaneously
Runs commands — installs packages, runs tests, starts dev servers
Iterates — if tests fail or builds break, it reads the error and tries to fix it

Each step requires your approval by default. You see what the Agent wants to do before it does it.

Checkpoints: Your Safety Net

Here’s the most important Agent feature: checkpoints.

Every time the Agent modifies your code, Cursor automatically saves a snapshot of the pre-change state. These checkpoints are:

Local only — stored on your machine, not in the cloud
Separate from Git — they don’t affect your commit history
Instant to restore — click a checkpoint to revert all files to that state

When to use checkpoints:

The Agent’s edit broke something you can’t easily fix
You want to try a different approach to the same problem
The Agent went down a wrong path and made too many changes to undo manually

How to restore: In the Composer panel, you’ll see checkpoints listed chronologically. Click the one you want to go back to. All files revert to that point. You can then give the Agent new instructions and try again.

✅ Quick Check: Agent mode made changes to 6 files but the result doesn’t work. You also have uncommitted manual changes in 2 other files you don’t want to lose. Will restoring a checkpoint affect your manual changes? Checkpoints only track files the Agent modified. Your manual changes in other files are safe. But if the Agent happened to edit a file where you also had manual changes, restoring would revert the Agent’s changes AND your manual changes in that specific file. When in doubt, commit your manual work first.

Plan Mode: Think Before Acting

For complex tasks, you don’t want the Agent to start editing immediately. Plan mode makes it stop and think first.

How to use it: In Composer, switch to Plan mode (or ask the Agent: “Plan how you’d implement this before making any changes”).

What you get:

The Agent researches your codebase
It proposes a step-by-step plan: which files to change, what to add, what to modify
You review the plan and either approve, adjust, or redirect
Only after approval does it start editing

When Plan mode saves you:

Adding a feature that touches many files — you want to verify the Agent understands the architecture before it writes code
Refactoring — you want to make sure the Agent’s approach matches your vision
Unfamiliar codebase — the plan reveals whether the Agent actually understands the project

YOLO Mode: Maximum Autonomy

At the opposite end from Plan mode, YOLO mode removes approval gates for terminal commands.

Default behavior: Agent asks permission before running every terminal command (npm install, git status, test runs).

YOLO mode: Auto-approves commands matching patterns you define. Enable it in Settings > Features > Agent.

When to use it: Running tests, linting, building — commands that are safe and reversible. You’re watching the output and can Ctrl+C if something goes wrong.

When NOT to use it: Never auto-approve commands that modify production databases, push to remote repositories, delete files, or interact with external services. YOLO mode should only cover read-only or easily reversible commands.

Writing Good Agent Prompts

Agent responds dramatically to prompt quality. Here’s what works:

Break complex tasks into steps:

Instead of: “Build a complete user dashboard with charts, tables, and filters”

Try: “Add a user dashboard page. Start with just the route and basic layout. I’ll tell you what to add next.”

Reference existing patterns:

“Add a new API endpoint for /users/preferences following the same patterns as @api/users/profile.ts”

Include acceptance criteria:

“The feature is done when: (1) the test suite passes, (2) the TypeScript compiler reports no errors, and (3) the /api/preferences endpoint returns a JSON response.”

Give constraints:

“Don’t install new dependencies. Use the existing date-fns library for date formatting.”

✅ Quick Check: You asked Agent to add a caching layer and it installed Redis, modified 12 files, and changed the database connection logic. That’s way more than you wanted. What’s the better approach? Break it into pieces. Start with: “Add in-memory caching to the getUser function only. Don’t install anything new — use a simple Map.” Get that working. Then expand: “Now add caching to getProducts using the same pattern.” Small, scoped instructions give you more control and produce better results.

Parallel Agents

Cursor 2.0 lets you run up to 8 agents simultaneously. Each gets its own tab in the Composer panel. This is useful when you have independent tasks:

Agent 1: Writing tests for module A
Agent 2: Refactoring module B
Agent 3: Adding documentation to module C

They work independently — each has its own conversation, checkpoints, and file changes. Just make sure they’re not editing the same files, or you’ll get merge conflicts.

Key Takeaways

Agent mode (Cmd+I + Cmd+.) is an autonomous coding partner — it reads, writes, runs commands, and iterates
Checkpoints are automatic snapshots before every Agent edit — your safety net for reverting changes
Plan mode makes Agent propose an approach before editing — use it for complex tasks
YOLO mode auto-approves terminal commands — only enable for safe, reversible operations
Break complex tasks into small, specific instructions with clear acceptance criteria
Run up to 8 parallel agents for independent tasks in Cursor 2.0

Up Next

Agent mode is powerful, but it only knows what you tell it per conversation. What if you could make Cursor automatically follow your coding standards, use your preferred libraries, and avoid patterns you’ve banned? In Lesson 6, you’ll learn rules files, Notepads, custom docs, and MCP — the configuration system that makes Cursor smarter about your project permanently.