Agent Mode: Let Cursor Drive

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

This is one of the most powerful and most potentially disruptive features in Cursor. Understanding what Agent can do, when to use it, 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 activate Agent mode in the Chat panel
• What Agent mode can do: file creation, multi-file editing, terminal commands, and package installation
• When to use Agent vs Ask vs Cmd+K
• How to review the changes Agent makes
• Why version control is essential when working with Agent mode
• 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 for you. Instead, it:

1. Plans a sequence of actions to accomplish the goal
2. Reads relevant 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 verify behavior
6. Iterates based on what it finds -- if a test fails after a change, it reads the error and tries to fix it

This is autonomous operation. Cursor is driving, not you. Your role during an Agent session is to monitor what it is doing, guide it if it goes off track, and review its work when it finishes.

Why "Agent" Mode?

The term "agent" in AI refers to a system that takes actions in an environment to achieve goals -- rather than just answering questions. Cursor's Agent mode embodies this: given a goal like "add user authentication to this Express app", it acts in your codebase (the environment) through a sequence of file edits, command executions, and reads until the goal is achieved (or it determines it needs more information from you).

---

Activating Agent Mode

Agent mode is accessed from the Chat panel (Cmd+L to open). At the top of the chat input, there is a mode selector dropdown. Click it and choose Agent instead of Ask.

Once Agent mode is selected, the Chat input works slightly differently:

• You describe a goal, not a question
• Cursor will execute a series of actions, not just generate a response
• You may be asked clarifying questions before it starts, or it may proceed immediately

To switch back to Ask mode, return to the mode selector and choose Ask.

Keyboard Access

Some Cursor versions allow you to type a special prefix or use a command to switch to Agent mode. Check Cursor's keyboard shortcuts panel (Cmd+Shift+P, search "Agent") for the current shortcut if clicking the dropdown feels slow.

---

What Agent Mode Can Do

Understanding Agent's capabilities helps you set appropriate 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 new features, not just the code inside a single file.

Edit Multiple Files Simultaneously

When a change spans multiple files -- adding a new API endpoint, for example -- Agent coordinates all the edits. It might update your router file, create a new handler file, add a type definition, and update your API documentation at the same time, maintaining consistency across all changes.

This is where Agent's capability goes beyond what you can easily do with Cmd+K, which operates on one selection at a time.

Run Terminal Commands

Agent can execute terminal commands in your project. This includes:

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

When Agent installs a package, it adds it to your package.json and runs the install command. When it runs tests and they fail, it reads the error output and attempts to fix the code.

Read and Search Files

Agent reads files to understand your project's current state. Before making changes, it typically reads the files it is going to edit. It also searches your codebase to find relevant existing code, understand patterns, and avoid conflicts with what already exists.

---

A Concrete Agent Mode Example

Here is what Agent mode looks like in practice. Suppose you open Chat, switch to 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. Read src/routes/posts.ts to understand the existing pattern
2. Read the database schema or model files to understand the data structure
3. Create src/routes/comments.ts with GET and POST handlers following the same pattern
4. Update src/app.ts (or wherever routes are registered) to include the new route
5. Create a types/comment.ts type definition file
6. Create tests/comments.test.ts with tests for both endpoints
7. Run npm test to verify the tests pass
8. Fix any test failures it encounters
9. Report what it did and where to find the new files

All of this happens without you manually editing a single file.

---

When to Use Agent vs Ask vs Cmd+K

Choosing the right tool for a task makes a significant difference in efficiency 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 to generate a snippet you will review and apply manually
• You are exploring options and not ready to commit to a change
• The task is small enough to handle with a single targeted edit

Use Cmd+K When

• You know exactly which block of code needs to change
• The change is self-contained within one selection
• You want to review a diff for a specific targeted transformation
• The task is a clear, single-operation edit (add error handling, refactor this function, convert this to TypeScript)

Use Agent Mode When

• The task requires creating multiple new files
• Changes span several existing files that need to be updated in a coordinated way
• You want the AI to verify its work by running tests
• The task has multiple steps that logically depend on each other
• You can clearly describe the end goal and trust Agent to figure out the path

A helpful mental model: Ask is for thinking, Cmd+K is for single edits, Agent is for features.

---

Reviewing Agent's Changes

Because Agent operates autonomously and may touch many files, the review step is more important here than with any other Cursor feature.

During Execution

As Agent works, it shows you what it is doing in the Chat panel. You can watch the sequence of actions: which files it is reading, which edits it is making, which commands it is running. If you see it going in a direction that seems wrong, you can interrupt it.

After Execution

When Agent finishes, review the changes before doing anything else. Use git to see exactly what happened:

git diff

This shows every line that was added or removed across all files. Read through the diff with the same care you would apply to a colleague's code review. Check:

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

Using Cursor's Built-In Diff View

Cursor also shows file diffs in the editor. Any file that Agent modified will appear with change indicators in the gutter. You can open each file and see the before/after state directly.

---

Why Version Control Is Essential with Agent Mode

Before every Agent session involving significant changes, you should be on a clean git branch with no uncommitted changes. This is not optional advice -- it is a safety requirement.

Here is why:

Agent mode can make changes to many files in a short time. If Agent makes a mistake (and it will sometimes -- no AI is perfect), you want a clean rollback path. With version control, rolling back is trivial: git checkout . or git reset --hard HEAD restores your working tree to its last committed state.

Without version control as a safety net, undoing a bad Agent session means manually figuring out what changed across every file Agent touched. This can be hours of work.

Recommended Workflow

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

# Open Cursor, switch to Agent mode, give your prompt
# 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 checkout .  # Undo all of Agent's changes instantly

This workflow means you always have a safe restore point and can make use of Agent's output or discard it cleanly.

---

Tips for Effective Agent Prompts

Agent mode is powerful but requires clear direction. Vague prompts lead to unexpected results. These patterns consistently produce better Agent sessions:

Describe the Goal, Not the Steps

Agent is good at planning the steps. You do not need to tell it "first create a file, then update the router, then...". Instead, describe the outcome:

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

If you find yourself describing implementation steps in detail, consider whether Cmd+K with a few targeted edits might be more predictable.

Reference Existing Patterns

Telling Agent to follow existing patterns dramatically 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"

This gives Agent a concrete template to match rather than making style choices on its own.

Specify What Should Not Change

Agent sometimes modifies things you did not intend. If you have areas of the codebase you want to protect:

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

Set Scope Limits

For large codebases, Agent might try to be thorough in ways that exceed your intent. Scope limits help:

• "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 a test suite, tell Agent to run it:

• "After making changes, run npm test and fix any failures"
• "Verify your changes compile without errors by running npm run build"

This uses Agent's ability to self-verify, which catches many simple mistakes automatically.

---

Summary

Agent mode is Cursor's most autonomous feature. It takes a high-level goal and executes a sequence of file reads, edits, file creations, and terminal commands to accomplish it -- without you manually directing each step. This makes it dramatically faster than Cmd+K for tasks that span multiple files or require coordinated changes across a feature.

But autonomy comes with responsibility. Always run Agent on a clean git branch, always review the diff when it finishes, and always verify that the changes do what you expected. Agent is a powerful tool for moving fast, and version control is what makes moving fast safe.

---

Key Takeaways

• Agent mode is activated from the Chat panel's mode selector dropdown and enables Cursor to autonomously take multi-step actions
• Agent can create files, edit multiple files, run terminal commands, install packages, and verify its own work by running tests
• Use Ask for exploration and understanding, Cmd+K for targeted single edits, and Agent for multi-file features and tasks with multiple dependent steps
• Always work on a clean git branch before starting an Agent session -- version control is your safety net for undoing unwanted changes
• Review Agent's work with git diff after each session; check all modified files before committing
• Write goal-oriented prompts that describe the outcome, reference existing patterns, specify constraints, and ask Agent to verify with tests
• Agent is powerful but not infallible -- treat its output with the same scrutiny you would apply to any code you did not write yourself