Agent Mode: Let Cursor Drive

The previous lessons in this module covered tools where you stay in control of every individual change: Ask mode answers questions, Cmd+K edits a selection you chose, and Tab completes what you are already typing. Agent mode is different. You hand Cursor a goal and let it figure out the steps.

Agent is the default mode in Cursor's side panel, and it is the most powerful (and most potentially disruptive) way to work. Understanding what Agent can do, when to plan first, and how to use it safely is essential before you start relying on it.

What You'll Learn

• What Agent mode is and how it differs from Ask mode
• How to start an Agent session from the side panel
• What Agent can do: create files, edit across your project, search your codebase, and run terminal commands
• How to use Plan mode to agree on an approach before Agent builds
• How checkpoints, queued messages, and command approval keep you in control
• When to use Agent vs Ask vs Cmd+K
• How to review the changes Agent makes, and why version control still matters
• Tips for writing Agent prompts that produce reliable results

---

What Agent Mode Is

Agent mode is Cursor's autonomous, multi-step execution mode. When you give Agent a task, it does not produce a single response and wait. Instead, it:

1. Searches your codebase to find the relevant files
2. Reads those files to understand the current state
3. Writes code changes across one or more files
4. Creates new files if needed
5. Runs terminal commands to install dependencies, run tests, or check the build
6. Iterates based on what it finds: if a test fails after a change, it reads the error and tries to fix it

Cursor is driving, not you. Your role is to set a clear goal, watch what it is doing, steer it if it goes off track, and review the work when it finishes.

Why "Agent" Mode?

In AI, an "agent" is a system that takes actions in an environment to reach a goal, rather than just answering questions. Given a goal like "add user authentication to this Express app", Cursor's Agent acts in your codebase (the environment) through a sequence of searches, reads, edits, and commands until the goal is done, or until it needs more information from you.

---

Starting an Agent Session

Open the side panel with Cmd+L or Cmd+I (Ctrl on Windows/Linux). Agent is the default mode. If you were in Ask or Plan mode, press Shift+Tab in the chat input to cycle back to Agent, or use the mode picker.

In Agent mode, the chat input works a little differently:

• You describe a goal, not just a question
• Cursor carries out a series of actions instead of only replying
• It may ask clarifying questions first, or start right away

You do not need to tag every file. Agent searches your codebase on its own. If you already know which files matter, @ mention them to save it time.

Cursor also has an Agents Window for running several agents in parallel, including in separate git worktrees or in the cloud. The habits in this lesson apply there too.

---

Plan Before You Build

For small, clear tasks, Agent can go straight to work. For bigger ones, start in Plan mode first.

In Plan mode, the agent researches your codebase, asks clarifying questions, and writes an editable plan: which files it will change, what it will add, and in what order. You read the plan, fix anything that is wrong ("use the existing logger, not console.log", "skip the admin page for now"), and then tell it to build. The build follows the plan you approved.

Use Plan mode when:

• The task touches many files or several parts of the system
• The requirements are unclear and you want the agent to ask questions first
• It is an architectural change, like a new data model or a refactor across modules
• You want a record of the intended approach before any code changes

Planning first costs a minute or two and often saves a long cleanup. It is much easier to fix a wrong step in a plan than in fifteen edited files.

---

What Agent Mode Can Do

Knowing Agent's capabilities helps you set expectations and write useful prompts.

Create New Files

Agent can create files anywhere in your project. If you ask it to "add a settings page", it might create:

• A new page component file
• A styles file
• A new route configuration entry
• Test files for the new component

It handles the full scaffolding of a feature, not just the code inside one file.

Edit Many Files Together

When a change spans several files (adding a new API endpoint, for example), Agent coordinates all the edits. It might update your router, create a handler, add a type definition, and update your docs, keeping them consistent.

This is where Agent goes well beyond Cmd+K, which works on one selection at a time.

Run Terminal Commands

Agent can run terminal commands in your project, such as:

• Running your test suite (npm test) to verify changes
• Installing packages (npm install some-package)
• Running build scripts to check for compile errors
• Running linters or formatters
• Running database migrations

When tests fail, it reads the error output and tries to fix the code.

Search and Read Your Codebase

Before making changes, Agent searches your project to find relevant code, learn your patterns, and avoid conflicts with what already exists. This is why you can describe a goal in plain words without listing every file.

Extend Itself with Skills and Subagents

Agent can also use skills (packaged instructions for specific jobs) and hand parts of a task to subagents that work on a piece in parallel. You do not need these to get started. Just know they exist, and that you can manage them, along with rules and MCP servers, from Cursor's customization settings.

---

A Concrete Agent Mode Example

Suppose you open the side panel in Agent mode and type:

Add a /api/comments endpoint to this Express app that supports GET (list all comments for a post) and POST (create a new comment). Use the same patterns as the existing /api/posts endpoint. Add tests.

Agent might take these steps:

1. Search the codebase and read src/routes/posts.ts to learn the existing pattern
2. Read the database schema or model files to understand the data
3. Create src/routes/comments.ts with GET and POST handlers in the same style
4. Update src/app.ts (or wherever routes are registered) to add the new route
5. Create a types/comment.ts type definition
6. Create tests/comments.test.ts with tests for both endpoints
7. Run npm test to check the tests pass (asking your approval first if you require it)
8. Fix any failures it finds
9. Summarize what it did and where the new files are

You did not edit a single file by hand. For a bigger version of this task, you would start in Plan mode and approve the plan before step 3.

---

Staying in Control While Agent Works

Autonomy does not mean you are locked out. Cursor gives you several ways to steer and undo.

Queued Messages

You can keep typing while Agent works. Press Enter and your message is queued: Agent picks it up when it finishes its current step. Use this to add a detail you forgot ("also add pagination to the GET route") without stopping the run. If Agent is clearly heading the wrong way, stop it and redirect instead.

Terminal Command Approval

Running commands is powerful, so Cursor lets you decide how much freedom Agent has. You can require approval before each command, or allow trusted commands (like your test or lint script) to run automatically. Start strict, then loosen it for commands you run all the time. Be careful with anything that deletes data, touches production, or pushes code.

Checkpoints

Cursor creates checkpoints as Agent works. In the chat timeline, click a checkpoint to preview your files at that point, then restore it to revert all files back to that state. If Agent took a wrong turn three steps ago, you can roll back to just before it and try a different instruction.

Checkpoints are a handy undo button inside Cursor, but they are not a replacement for git. Keep committing your work.

---

When to Use Agent vs Ask vs Cmd+K

Picking the right tool makes a big difference in speed and safety.

Use Ask Mode When

• You want to understand code before changing it
• You have a question about an approach or API
• You want a snippet you will review and apply yourself
• You are exploring options and not ready to change anything

Use Cmd+K When

• You know exactly which block of code needs to change
• The change fits inside one selection
• You want a focused diff for one transformation
• The task is a clear, single edit (add error handling, refactor this function, convert this to TypeScript)

Use Agent Mode When

• The task needs several new files
• Changes span existing files that must be updated together
• You want the AI to verify its work by running tests
• The task has multiple steps that depend on each other
• You can describe the end goal clearly (and for big tasks, you have approved a plan)

A helpful mental model: Ask is for thinking, Plan is for agreeing on the approach, Cmd+K is for single edits, Agent is for features.

---

Reviewing Agent's Changes

Because Agent may touch many files, reviewing its work matters more here than with any other feature.

During Execution

Agent shows each step in the side panel: which files it searches and reads, which edits it makes, which commands it wants to run. If it heads in the wrong direction, stop it, queue a correction, or roll back to a checkpoint.

After Execution

When Agent finishes, review the changes before anything else. Cursor shows the edited files with diffs you can accept or reject. Cmd+Return (Ctrl+Enter on Windows and Linux) accepts all suggested changes and Cmd+Shift+Backspace (Ctrl+Shift+Backspace) rejects all, but it is better to look through each file first.

Git gives you the full picture across the project:

git diff

Read the diff as carefully as you would a colleague's code review. Check:

• Do the changes do what you asked?
• Are there unintended side effects?
• Does the code follow your project's conventions?
• Are the tests meaningful, or superficial?
• Were any files changed that should not have been?

---

Why Version Control Is Still Essential

Checkpoints help inside a session, but before any significant Agent session you should be on a clean git branch with no uncommitted changes. Treat this as a safety requirement, not a suggestion.

Agent can change many files quickly. If it makes a mistake (and sometimes it will, because no AI is perfect), git gives you a reliable rollback path: git restore . undoes Agent's edits to tracked files, and git clean -fd removes any new files it created (run git clean -nd first to preview what will be deleted). Git also keeps history across sessions, branches, and machines, which checkpoints do not.

Recommended Workflow

# Before starting an Agent session:
git checkout -b feature/add-comments-endpoint
git status  # Make sure the working tree is clean

# In Cursor: Plan mode for big tasks, then Agent to build
# Review Agent's output

# If satisfied:
git add -p    # Review changes interactively before staging
git commit -m "Add /api/comments endpoint with tests"

# If not satisfied:
git restore .   # Undo Agent's edits to existing files
git clean -nd   # Preview the new files Agent created
git clean -fd   # Delete those new files

This way you always have a safe restore point and can keep or discard Agent's work cleanly.

---

Tips for Effective Agent Prompts

Agent is powerful but needs clear direction. Vague prompts lead to surprises. These patterns help:

Describe the Goal, Not the Steps

Agent is good at working out the steps, so describe the outcome:

• "Add a user authentication system using JWT tokens"
• "Migrate the user settings page from class components to functional components with hooks"
• "Add rate limiting to all API endpoints"

If you want to shape the steps, use Plan mode and edit the plan rather than writing a long step-by-step prompt.

Reference Existing Patterns

Pointing Agent at existing patterns greatly improves consistency:

• "Use the same error handling pattern as the existing auth middleware"
• "Follow the same file structure as the posts module"
• "Write tests in the same style as the existing test files"

Specify What Should Not Change

If there are areas you want to protect, say so:

• "Do not modify the database schema"
• "Keep the existing API response format identical"
• "Do not add any new npm dependencies"

If you repeat the same instructions in every session, move them into project rules or an AGENTS.md file (covered later in the course).

Set Scope Limits

In large codebases, Agent may be more thorough than you intended. Limit the scope:

• "Only work within the src/api/ directory"
• "Only change the frontend components, not the API layer"
• "Focus only on the authentication module"

Ask for Verification

If your project has tests, tell Agent to use them:

• "After making changes, run npm test and fix any failures"
• "Make sure it compiles by running npm run build"

This uses Agent's ability to check its own work, which catches many simple mistakes.

---

Summary

Agent mode is Cursor's most autonomous feature and the default in the side panel. It takes a goal and works through searches, reads, edits, new files, and terminal commands to reach it, without you directing each step. For big or unclear tasks, start in Plan mode, agree on the plan, then let Agent build.

You stay in control with queued messages, command approval, and checkpoints. But autonomy comes with responsibility: work on a clean git branch, review the diff when Agent finishes, and check that the changes do what you expected.

---

Key Takeaways

• Agent is the default mode in the side panel (Cmd+L or Cmd+I); switch modes with Shift+Tab
• Agent can search your codebase, create files, edit across your project, run terminal commands, and verify its work with tests
• Use Plan mode before building complex, multi-file, or unclear tasks, then build from the plan you approved
• Queued messages let you add instructions while Agent works; command approval controls which terminal commands run automatically
• Checkpoints let you preview and restore files to an earlier point in the session, but keep using git as your main safety net
• Use Ask for understanding, Cmd+K for targeted single edits, and Agent for multi-file features
• Write goal-oriented prompts that reference existing patterns, state what must not change, limit scope, and ask Agent to run tests
• Agent is powerful but not infallible: review its output as carefully as any code you did not write yourself