Cursor Agent Overview: Tools, Models & How It Works

Every Agent run rests on three pieces: the instructions it follows, the tools it can call and the model that does the reasoning. Change any one of them and the run behaves differently.

Knowing which piece changed tells you where to look, because each one fails differently. A bad result right after a model switch points at the model. A bad result on the same model, in a repo where someone added a rule last week, points at the instructions, and that problem follows you onto every model you try next. When a familiar task starts going wrong, read the rules that apply to those files before you open the model picker.

Agent works through a set of tools. It can search your repo, read and edit files, run shell commands, drive a browser, search the web, generate images and ask you a question mid-task.

Codebase search is built on Instant Grep, which matches exact names, strings and regex patterns using an index it builds on your machine. For broad questions, Agent can send an Explore subagent to run many searches in its own context and report back. Cursor no longer documents the semantic search tool that found code by meaning.

Two rows are easy to overlook. Fetch rules means some of the guidance that steers the agent arrives mid-task instead of sitting in the opening context. Image generation saves to your project's assets/ folder by default and shows the result inline in chat, which is a different job from the browser's screenshots.

The shell row has one setup detail to check. By default, Cursor uses the first terminal profile available. If that isn't the shell your project's scripts expect, commands fail in ways that look like the agent's mistake. Set your profile from the Command Palette with Terminal: Select Default Profile.

There is no limit on how many tool calls Agent can make during a task. That lets it finish long jobs, and it also lets a vague prompt spend a lot of usage before anything stops it, because nothing in the loop watches the clock for you. Write the stopping condition into the prompt instead of watching for it yourself.

Agent is the mode that edits files and runs commands. Ask is read-only and explains code. Plan Mode, Debug Mode and Design ModeA way to point at an element in Cursor's built-in browser and change it directly, instead of describing it in words. Press Enter for the full definition. are specialized agent workflows for planning, debugging with runtime evidence and changing a UI visually. Agent Review checks diffs after edits. Pick the mode that matches the job: exploring, executing, debugging or reviewing.

⇧+⇥ cycles through Agent, Ask, Plan and Debug from the chat input, and it is the quickest fix when you have been in the wrong one. A read-only Ask reply when you wanted the change looks a lot like the model ignoring you, and so does an edit when you only wanted an answer. Check the mode before you rewrite the prompt.

If your plan includes Auto, start with it as your daily driver, so Cursor picks the model for you. Plus and the legacy Start plan don't include Auto. Turn Auto off only when you need a specific model's characteristics.

Since July 22, 2026, Auto on Teams and Enterprise plans can run on Cursor Router. The router is on by default for Teams, and Enterprise admins turn it on from the dashboard. With it, you choose an optimization mode instead of a model: Cost, Balance or Intelligence. Individual plans have Cost mode only.

Cost uses the previous Auto routing logic. Under Balance and Intelligence, a classifier reads each agent request and routes it by task type and complexity, and the request bills at the list price of the model it reaches. Cursor's pages disagree on how Cost bills. The router and pricing docs say it bills as a Cursor-model request from the weekly pool, while the router help page says all Auto modes bill at the routed model's list price.

When you do choose a model, decide in two steps. First, pick thinking or non-thinking. A thinking modelA reasoning model (shown with a brain icon in Cursor's picker) that spends extra compute before answering; reach for it on complex, nuanced work and a standard model for fast, simple tasks. Press Enter for the full definition. suits plans, complex environments and security or codebase scans; it is slower and smarter, and overkill for simple tasks. Then weigh each model's traits. In one Cursor webinar, the presenter described GPT-5.x as verbose and prone to overthinking a simple task, but excellent at writing documentation and clear natural-language explanations.

Restore a checkpoint. Before significant changes, Agent automatically snapshots the files it has modified. Each checkpoint sits in the chat timeline: click one to preview your files at that point, then restore to revert them. Previous requests also show a Restore Checkpoint button.

Checkpoints are stored locally, separate from Git, and Cursor says to use them only for undoing Agent changes and to use Git for permanent version control. That makes them good for exploration: after three attempts at a refactor, none of them right, you can go back to the state before the first. They don't help once the work needs to leave your machine.

Branch before a long agent session anyway. Checkpoints can undo a bad hour on your own machine, but other people can review the work only once it is on a branch.

Yes. Type your next instruction while Agent runs and press Enter to queue it. Queued messages appear in order below the active task, you can drag them to reorder, and Agent works through them after it finishes. ⌘+↵ sends a message immediately and skips the queue; Cursor's Agent docs give only that Mac shortcut.

Use each path for its own job. An immediate message is appended to your most recent message and processed right away, so it is the tool for redirecting a run that is heading the wrong way. Queueing is for a follow-up you already know you want. Send ordinary follow-ups the immediate way and a focused run turns into a thread that has changed subject three times.

The August 19, 2026 changelog added a gentler option. You can send a message that steers the agent without interrupting it: the message waits for the next tool call instead of cutting the agent off mid-action. Type the follow-up and click Send now, or press Enter twice. Cursor's docs say this is live at cursor.com/agents and still rolling out in the Agents WindowCursor's surface listing your agent runs; open a run to read its diff and search transcripts from the command palette. Press Enter for the full definition.. Where you have it, a mid-run correction no longer costs you work, because the half-finished action completes before your redirect lands.

Four habits separate a clean Agent run from one that wanders.

• @-mention the files and folders that matter instead of making Agent search blind.
• State success criteria: a test command, URL or expected behavior.
• Approve terminal commands that touch production, secrets or billing.
• Start a fresh chat when context fills with failed attempts.

We would build the last habit first, because it is the least intuitive of the four. Starting a fresh chat feels like throwing work away, especially when the agent nearly had it. What you throw away is a transcript of failed attempts that the model reads as context, and that transcript is what keeps it circling the same wrong answer.