Agent Mode

Agent mode is Cursor's autonomous execution mode. Instead of answering questions or making single edits, the agent plans a series of steps and executes them independently — creating files, editing code, running terminal commands, and reading project context.

The difference between modes:

What the agent can do:

• Read files across your project to understand context
• Create new files and directories
• Edit existing files (multiple files in sequence)
• Run terminal commands (build, test, install packages)
• Search your codebase for relevant code
• Iterate on its own work (run tests, see failures, fix them)

What the agent cannot do:

• Access external services (APIs, databases) unless via terminal commands
• Make decisions that require business context it doesn't have
• Guarantee correctness — it can introduce bugs like any developer
• Push to git or deploy (these require your explicit action)

Mental model:

Think of Agent mode as a junior developer who:

• Is very fast at typing and searching
• Follows instructions literally
• Needs clear goals but can figure out implementation steps
• Should have their work reviewed before merging

Agent mode is accessed through the AI side pane with a specific mode selection.

Enabling Agent mode:

Configuration options:

In Cursor Settings (Cmd+, / Ctrl+,), search for "Agent" to find relevant settings:

• Auto-run terminal commands — Whether the agent can execute terminal commands without asking first (recommended: keep this OFF initially, so you approve each command)
• Auto-apply edits — Whether file edits are applied immediately or shown for approval
• Model selection — Which AI model powers the agent (newer models tend to be better at multi-step planning)

Recommended initial configuration:

For beginners:

Auto-run commands: OFF (review each terminal command before it runs)
Auto-apply edits: OFF (review each file edit before it's applied)

As you gain confidence:

Auto-run commands: ON for safe commands (tests, builds), OFF for installs/destructive commands
Auto-apply edits: ON (trust the agent more, revert via git if needed)

The quality of your task description directly impacts the quality of the agent's output. Here's how to write effective agent prompts.

The anatomy of a good agent task:

[GOAL]: What you want to achieve (the "what")
[CONTEXT]: Relevant details about your project (the "where/why")
[CONSTRAINTS]: Rules or limitations (the "how" boundaries)
[SUCCESS CRITERIA]: How you'll know it worked (the "done" definition)

Example — good task description:

Create a user registration form component.

Context:
- This is a Next.js 14 project with TypeScript
- We use React Hook Form for forms and Zod for validation
- Existing form components are in src/components/forms/

Requirements:
- Fields: name, email, password, confirm password
- Validate: email format, password min 8 chars, passwords match
- On submit, call the API at /api/auth/register
- Show inline validation errors under each field
- Show a success message or error toast after submission

Follow the patterns in src/components/forms/LoginForm.tsx for styling and structure.

Example — poor task description:

Make a signup form

(This lacks context about tech stack, validation needs, file location, and design expectations.)

Watching the agent work:

Once you submit a task, the agent will:

1. Plan — It may outline steps it intends to take
2. Read — It reads relevant files in your project for context
3. Execute — It creates/edits files, one at a time
4. Verify — It may run tests or check for errors
5. Report — It tells you what it did and what's next

You'll see each step in the AI side pane. Depending on your settings, you may need to approve each action.

What a typical agent execution looks like:

Agent: I'll create the registration form. Here's my plan:
1. Read LoginForm.tsx to understand the existing pattern
2. Create RegistrationForm.tsx with form fields
3. Create a Zod validation schema
4. Add the API call handler
5. Add the component to the page

Step 1: Reading src/components/forms/LoginForm.tsx...
[Shows file content]

Step 2: Creating src/components/forms/RegistrationForm.tsx...
[Shows proposed file content — awaiting your approval]

Reviewing agent output is a critical skill. The agent works fast, but you're responsible for the code that enters your project.

The review interface:

When the agent proposes a file edit or new file:

• You see a diff view (green = additions, red = deletions)
• You can Accept to apply the change
• You can Reject to skip it and tell the agent why
• You can Modify by accepting then editing manually

When the agent proposes a terminal command:

• You see the command it wants to run
• You can Allow to let it execute
• You can Deny to block it

What to look for when reviewing:

Redirecting the agent:

If the agent goes in the wrong direction, interrupt it:

You: Stop. That approach won't work because we need to support
pagination. Instead of fetching all users at once, use the
usePaginatedQuery hook from src/hooks/usePaginatedQuery.ts.
Continue with that approach.

The agent will adjust its plan and continue.

Partial acceptance:

Sometimes the agent gets 80% right:

1. Accept the proposed changes
2. Make manual adjustments to the parts you want different
3. Tell the agent: "I've accepted and modified the RegistrationForm. The validation schema needs an update — add a check that the email domain is not from disposable email providers. See our existing validation helpers in src/lib/validation.ts."

When to reject and start over:

• The agent's approach is fundamentally wrong (wrong architecture pattern)
• It's modifying files you didn't want touched
• The output is so far from what you need that fixing it is harder than starting fresh

To start over: reject the pending changes, start a new agent conversation, and provide a clearer task description with more constraints.

Choosing the right mode for the task saves time and produces better results.

Use Inline (Cmd+K / Ctrl+K) when:

• You know exactly where the change goes (one location, one file)
• The change is small: rename a variable, add a parameter, refactor a function
• You can describe the change in one sentence
• Examples: "Add error handling to this function", "Convert this to TypeScript", "Add a loading state"

Use Chat (Cmd+L / Ctrl+L) when:

• You need to discuss or explore before implementing
• You want explanations alongside code suggestions
• You want to compare approaches before committing
• The task is conversational: "How should I structure this?", "What's the best way to handle X?"
• Examples: "Explain this code", "What are my options for state management here?", "Help me debug this"

Use Agent when:

• The task spans multiple files
• You need files created, imports added, tests written — as a coordinated set
• The task has multiple steps that build on each other
• You can clearly describe the end goal but not every implementation step
• Examples: "Build the entire CRUD for this resource", "Refactor this module into smaller files", "Add authentication to all API routes"

Decision matrix:

Combining modes in a workflow:

A real workflow might use all three:

1. Chat: "How should I structure a notification system for this app?" (AI suggests an approach with stores, components, and API hooks)

2. Agent: "Implement the notification system as discussed. Create the store, the NotificationToast component, and the useNotifications hook." (Agent creates 4-5 files)

3. Inline (Cmd+K): Select a line in the generated code and say "Also handle the case where notifications are disabled in user settings" (Quick targeted edit to one function)

Agent mode truly shines on complex, coordinated tasks that would take many manual steps. Here are patterns for common multi-file tasks.

Pattern 1: Feature scaffolding

Create a complete "Blog Posts" feature with:
1. Prisma schema for a Post model (title, content, slug, published, authorId, createdAt, updatedAt)
2. API routes: GET /api/posts (list), GET /api/posts/[slug] (detail), POST /api/posts (create), PUT /api/posts/[id] (update), DELETE /api/posts/[id] (delete)
3. Zod validation schemas for create and update
4. React Query hooks for each endpoint
5. A basic PostList page component and PostDetail page component

Follow existing patterns in the "Users" feature (src/features/users/).

Pattern 2: Refactoring

Refactor src/components/Dashboard.tsx (currently 450 lines) into smaller components:
1. Extract the stats cards section into DashboardStats.tsx
2. Extract the activity feed into DashboardActivity.tsx
3. Extract the charts section into DashboardCharts.tsx
4. Keep Dashboard.tsx as the layout container that composes these pieces
5. Move shared types into a types.ts file in the same directory
6. Ensure all existing functionality is preserved

Do not change any styling or behaviour — this is a pure structural refactor.

Pattern 3: Adding cross-cutting concerns

Add error boundary and loading states to all page components in src/app/:
1. Create a reusable ErrorBoundary component in src/components/common/
2. Create a PageSkeleton loading component
3. Wrap each page in src/app/(main)/ with the ErrorBoundary
4. Add Suspense boundaries with PageSkeleton as fallback
5. Test by adding a temporary throw in one page to verify the boundary catches it

Reference the Next.js 14 error.tsx and loading.tsx conventions.

Pattern 4: Test generation

Generate comprehensive tests for src/lib/pricing.ts:
1. Read the file and understand all exported functions
2. Create src/lib/pricing.test.ts
3. Test each function with:
   - Happy path cases
   - Edge cases (zero, negative, very large numbers)
   - Error cases (invalid input types)
4. Use Jest with the existing test configuration
5. Run the tests and fix any failures

Target: 90%+ line coverage for this file.

Tips for complex tasks:

• Number your requirements — the agent follows numbered lists more reliably than prose
• Reference existing code — "Follow the pattern in X" is your most powerful tool
• Define boundaries — "Only modify files in src/features/posts/" prevents scope creep
• Include success criteria — "Run the test suite and ensure all tests pass" gives the agent a verification step
• Break mega-tasks into phases — If you need 20 files changed, do it in 2-3 agent sessions of 5-8 files each

After the agent completes:

1. Run git diff to see all changes in one view
2. Run your test suite to verify nothing broke
3. Run your linter to catch style violations
4. Do a manual review of the key logic files
5. Commit if satisfied, or ask the agent to fix specific issues