Agent mode is the core interactive AI experience in Cursor. It autonomously reads your codebase, edits files, runs commands, and iterates on errors. Since its launch in November 2024, it has gone through two major rewrites and become the default way most developers interact with Cursor. This guide covers how it works, how to use it effectively, and where it breaks down.
What Is Cursor Agent Mode?
Agent mode is the most autonomous of Cursor's three interaction modes. You describe a task in natural language. The agent analyzes your request and your codebase, then executes a multi-step plan: reading files, editing code, running terminal commands, searching the web, and fixing errors as they come up. It keeps going until the task is complete or it hits a limit.
Cursor has three modes. Agent is the default and does everything autonomously. Ask answers questions without editing files. Manual requires you to approve every individual edit. Most developers stay in Agent mode for the majority of their work.
| Mode | Edits Files | Runs Commands | Searches Web | Best For |
|---|---|---|---|---|
| Agent | Yes, multi-file | Yes, with approval | Yes | Building features, fixing bugs, refactoring |
| Ask | No | No | Yes | Understanding code, planning approach |
| Manual | Yes, one at a time | Yes, with approval | Yes | Precise edits to sensitive code |
Composer vs Agent Mode: The History
Before Cursor 2.0 (October 2025), the IDE had separate Chat and Composer panels. Chat was read-only. Composer could edit multiple files but could not run commands or search the web. Agent mode merged and extended both. What used to be “Composer” is now closest to Manual mode. If older tutorials reference “Composer mode,” they mean the pre-agent multi-file editor.
How to Activate Agent Mode
Agent mode is on by default. Open any project in Cursor, press Cmd+L (Mac) or Ctrl+L (Windows/Linux), and start typing. The chat panel opens with Agent already selected.
Switching Modes
Use Cmd+. (Mac) or Ctrl+. (Windows/Linux) to cycle between Agent, Ask, and Manual. You can also click the mode dropdown at the top of the chat panel.
YOLO Mode (Auto-Run Commands)
By default, Agent asks for confirmation before running terminal commands. YOLO mode removes all confirmation dialogs. The agent runs commands, deletes files, and installs packages without asking. Enable it in Settings > Features > Chat & Composer. Only use this in sandboxed environments or projects backed by Git where you can easily revert.
Agent from the CLI
Since January 2026, you can run Cursor Agent from the terminal with the cursor-agent command. It supports the same prompts and tools as the IDE agent. It also supports MCP, so external tools configured in your mcp.json work automatically.
What Agent Mode Can Do
Agent mode has all tools enabled by default. It decides which tools to use based on your request.
Multi-File Editing
Edits multiple files in a single pass. It understands relationships between files, so when you add a new API endpoint it also updates the route file, types, and tests.
Terminal Commands
Runs shell commands directly: builds, tests, package installs, database migrations, linting. With YOLO mode enabled, commands execute without confirmation.
Web Search
Generates search queries and browses the web for documentation, Stack Overflow answers, and API references. Useful when the agent needs information not in your codebase.
Auto-Fix
Detects and fixes linter errors and warnings automatically after making edits. If a command fails, the agent reads the error output and attempts a fix without you needing to intervene.
File Creation
Creates new files and directories. When you ask for a new feature, the agent scaffolds the full file structure: components, tests, styles, and configuration.
Checkpoints
Creates automatic checkpoints before making changes. If the agent goes in the wrong direction, you can revert to any checkpoint with one click. This is separate from Git commits.
Tool Call Limits
Standard agent mode allows 25 tool calls per interaction. Each file read, edit, terminal command, or web search counts as one call. When the limit is reached, Cursor creates a checkpoint and asks if you want to continue.
Max mode increases the limit to 200 tool calls and removes context truncation, giving you the full context window of the underlying model. Max mode uses token-based API pricing with a 20% margin. For heavy sessions, expect $8-10/day.
Agent Mode vs Background Agents
These are two different features that solve different problems. Agent mode is interactive and local. Background agents are asynchronous and cloud-based.
| Feature | Agent Mode | Background Agents |
|---|---|---|
| Runs where | Your local machine | Cloud VM |
| Execution style | Interactive, real-time | Async, fire and forget |
| Edits your files | Directly in your workspace | On a separate branch, pushes to GitHub |
| Parallelism | One active agent at a time | Multiple agents on different tasks |
| Confirmation needed | Yes (unless YOLO mode) | No, auto-executes everything |
| Output | Code changes in your editor | Pull request with artifacts |
| Best for | Active development, iteration | Long tasks, CI jobs, running tests |
Use agent mode when you are actively working and want to steer the AI. Use background agents when you have a well-defined task you want to hand off entirely, like “add unit tests for every function in src/utils/” or “refactor all class components to functional components.”
Background agents cost more because they use Max mode-compatible models and run in dedicated cloud VMs. They require a paid Cursor plan. Trigger them with Ctrl+E.
Model Selection in Agent Mode
Cursor lets you switch models mid-session. The model dropdown is at the top of the chat panel. Your choice affects quality, speed, and credit cost.
| Model | Strength | Speed | Credit Cost | Best For |
|---|---|---|---|---|
| Claude Sonnet 4 | Reliable, strong code quality | Fast | ~89 requests/$20 | General coding, most tasks |
| Claude Opus 4 | Best reasoning, complex tasks | Slower | ~45 requests/$20 | Architecture, hard bugs |
| GPT-5 | Strong reasoning | Fast | ~100 requests/$20 | Logic-heavy code, planning |
| Gemini 3 Pro | Largest context window | Very fast | ~100 requests/$20 | Large codebases, bulk analysis |
| Composer (Cursor) | 4x generation speed | Fastest | Included in plan | Short iterative turns |
| Auto | Selects best model per query | Varies | Varies | Default, good for most users |
A practical strategy: use Auto for daily work, switch to Claude Sonnet 4 for multi-file features, and pull in Gemini 3 Pro when you need to analyze a large codebase. Save Opus for genuinely hard problems, like tracing a concurrency bug across multiple services.
The Composer Model
Cursor shipped its own frontier coding model in October 2025, also called Composer. It is trained specifically for agentic interactions inside Cursor: short turns, tool calls, and iterative edits. It is roughly 4x faster than similarly capable models and completes most interactive turns in under 30 seconds. It is included in all paid plans without extra credit cost.
Tips for Effective Agent Mode Prompts
Start with a single-line directive
Begin every prompt with an explicit intent. 'Add a rate limiter to the /api/upload endpoint using a sliding window algorithm' is better than 'improve the upload API.'
Use @-mentions for context
Type @filename to pull specific files into context. Use @docs to reference docs. Use @web for web search. Targeted context beats letting the agent discover everything on its own.
Create .cursor/rules/ files
Modular Markdown (.mdc) files with YAML frontmatter tell the agent when they should activate. Put coding standards, framework preferences, and architectural constraints here instead of repeating them in prompts.
Start fresh sessions per task
Context window fills up as the session grows. After finishing a feature, start a new chat before moving to the next task. Long sessions cause the agent to forget earlier instructions and produce inconsistent code.
Commit before every agent run
Git is your safety net. If the agent makes a mess, git reset takes you back instantly. Without commits, you are stuck manually reverting across multiple files.
Use Plan Mode for complex tasks
Plan Mode makes the agent create a reviewable markdown plan before executing. You can edit the plan to remove unnecessary steps or add context the agent missed. Especially useful when you are unfamiliar with the code.
Prompt Examples
Good: Specific intent with constraints
Add pagination to the /api/products endpoint.
Use cursor-based pagination, not offset.
Return 20 items per page.
Include a "nextCursor" field in the response.
Update the existing tests in tests/api/products.test.ts.Good: Reference files and patterns
@src/components/DataTable.tsx
Add a sortable column header to this table component.
Follow the same pattern as the FilterDropdown in @src/components/FilterDropdown.tsx.
Use the existing SortIcon from @src/components/icons/.Bad: Vague and underspecified
Make the API better.
Fix the table.
Add some tests.The Token Tax
Every word in your .cursor/rules/ files counts as tokens in the context window. A project with 20 global rules might send 2,000 extra tokens with every message. Use the alwaysApply: false frontmatter field to keep rules from loading unless relevant. Prefer auto-attached rules with glob patterns over always-on rules.
Limitations and Context Window
Agent mode is powerful but not unlimited. Understanding where it breaks helps you work around the edges.
Context window degradation
Regular mode truncates context to ~10,000-15,000 tokens even though Claude supports 200K. As sessions grow, the agent loses earlier instructions, repeats itself, and makes inconsistent edits. Max mode removes truncation but costs significantly more.
25 tool call ceiling
Standard agent mode stops after 25 tool calls. For a complex feature touching 8-10 files, this limit can force you to continue the conversation multiple times. Max mode raises this to 200.
Wrong file edits
In large codebases with similar file names or patterns, the agent sometimes edits the wrong file. Always review the file list in diffs before accepting changes.
Long conversations degrade quality
After many turns and summarizations, context accumulates noise. The agent gets distracted by old, no-longer-relevant context. Starting a new session with a clean prompt almost always outperforms continuing a long one.
Needle-in-a-haystack problem
When the context window is packed with rules, chat history, and file contents, the agent can miss critical details buried in the middle. LLMs perform worst on information in the center of long contexts.
Credit-based pricing surprises
Cursor switched from request-based to credit-based billing in mid-2025. Premium model calls drain credits faster. Heavy agent mode usage can push monthly costs well above the base plan price.
Practical Workarounds
- Start new sessions per task. Do not let unrelated context accumulate.
- Compact proactively at 70% context usage, not 90%.
- Use
.cursorignoreto exclude node_modules, build artifacts, and large generated files from indexing. - Use auto-attached rules with glob patterns instead of always-on rules to reduce the token tax.
- Delegate exploration to subagents. They run in separate context windows and return only what matters, keeping your main session clean.
Agent Mode in Cursor vs Claude Code CLI
Cursor and Claude Code take different approaches to AI-driven development. Cursor is IDE-first: you work in VS Code, and the AI assists. Claude Code is agent-first: you work in the terminal, describe what you want, and the AI drives.
| Dimension | Cursor Agent Mode | Claude Code |
|---|---|---|
| Interface | VS Code-based IDE | Terminal / CLI |
| Philosophy | IDE-first, AI assists | Agent-first, AI drives |
| Autocomplete | Yes, integrated Tab completions | No native autocomplete |
| Token efficiency | Standard | 5.5x fewer tokens for equivalent tasks |
| Context management | Rules files, .cursorignore | CLAUDE.md, .claudeignore, subagents |
| Multi-agent | Subagents, background agents | Subagents, parallel sessions, agent teams |
| Pricing model | Credit-based, $20-200/mo | Usage-based with weekly rate limits |
| IDE lock-in | VS Code fork only | Works in any terminal |
Many developers use both. Cursor for day-to-day editing, file browsing, and quick iterations. Claude Code for heavy tasks like documentation generation, test suite fixes, large refactors, and CI/CD automation. The tools complement rather than replace each other.
Cursor's productivity study reports organizations using Agent mode see 39% more pull requests merged. Benchmarks show Cursor completes tasks in 63 seconds vs. GitHub Copilot's 90 seconds. Claude Code's 5.5x token efficiency can make it more cost-effective for batch workloads, where a task consuming 100K tokens in Cursor might use only 18K in Claude Code.
Cursor Agent Mode Pricing (2026)
Agent mode is available on every Cursor plan, including the free tier. The difference is how many agent requests you get and which models you can use.
| Plan | Price | Agent Mode Access | Notable Limits |
|---|---|---|---|
| Hobby | Free | 50 premium requests/mo + 500 free model requests | Limited to testing; runs out quickly |
| Pro | $20/mo | $20 credit pool, unlimited Tab, background agents | ~225 Claude Sonnet requests or ~500 GPT requests |
| Pro+ | $60/mo | 3x usage of all premium models | Best value for full-time agent use |
| Ultra | $200/mo | 20x usage, priority access to new features | Heavy all-day usage with Max mode |
| Teams | $40/user/mo | All Pro features + SSO, admin controls | ~500 agent requests/user included |
Annual billing saves 20% across all paid tiers. Max mode (200 tool calls, full context window) is available on any paid plan but uses per-token API pricing on top of your subscription. Enterprise pricing is custom.
Credit-Based Billing
In June 2025, Cursor moved from request-based billing to a credit system. Your monthly subscription includes a credit allowance that depletes based on which model you use. A $20 Pro credit pool gives roughly 225 Claude Sonnet requests, 500 GPT requests, or 550 Gemini requests. Expensive models like Claude Opus drain credits faster. Check your usage in Settings > Account > Usage.
Frequently Asked Questions
What is Cursor Agent Mode?
Agent mode is the default and most autonomous mode in Cursor. It reads your codebase, edits multiple files, runs terminal commands, browses the web, and iterates until the task is done. Introduced in November 2024, it replaced the older Composer workflow and became the primary way developers interact with Cursor.
How do I activate Cursor Agent Mode?
Press Cmd+L (Mac) or Ctrl+L (Windows/Linux). Agent mode is on by default. To switch between Agent, Ask, and Manual modes, use Cmd+. or click the mode dropdown.
What is the difference between Agent Mode and Background Agents?
Agent mode runs interactively on your local machine. Background agents run asynchronously in a cloud VM, work on a separate branch, and push changes as a pull request. Agent mode handles up to 25 tool calls (200 in Max mode). Background agents auto-execute everything without confirmation.
Which AI model works best in Agent Mode?
Claude Sonnet 4 is the most popular choice for reliability and code quality. Gemini 3 Pro is best for large context work. Cursor's Composer model is the fastest option for short iterative turns. Use Auto mode if you don't want to think about it.
How much does Cursor Agent Mode cost?
The free Hobby tier includes 50 premium agent requests per month. Pro costs $20/mo with a $20 credit pool (roughly 225 Claude Sonnet requests). Pro+ at $60/mo gives 3x the credits. Max mode is available on any paid plan with per-token pricing. Annual billing saves 20%.
What are the limitations of Agent Mode?
The main constraints: context window truncation to ~10K-15K tokens in regular mode, 25 tool calls per interaction, degraded quality in long sessions, occasional wrong-file edits in large codebases, and credit depletion with heavy premium model usage.
What is Max Mode?
Max mode raises the tool call limit from 25 to 200 and removes context truncation, giving you the full context window of the underlying model. It uses per-token API pricing with a 20% margin. Useful for complex tasks that need many autonomous steps or large file contexts.
Better Code Search for Better Agent Results
WarpGrep is a semantic code search MCP server that improves any AI coding agent's performance by ~4% on SWE-bench. It works inside Cursor, Claude Code, Windsurf, and any tool that supports MCP. Better search means your agent finds the right context faster and writes better code.