pages/agent/overview.txt

route: /docs/agent/overview
title: Cursor Agent
description: Assistant for autonomous coding tasks, terminal commands, and code editing

Cursor Agent
Agent is Cursor's assistant that can complete complex coding tasks independently, run terminal commands, and edit code. Access in sidepane with Cmd+ICtrl+I.
Learn more about how agents work and help you build faster.
How Agent works
An agent is built on three components:
Instructions: The system prompt and rules that guide agent behavior
Tools: File editing, codebase search, terminal execution, and more
Model: The agent model you pick for the task
Cursor's agent orchestrates these components for each model we support, tuning instructions and tools specifically for every frontier model. As new models are released, you can focus on building software while Cursor handles the model-specific optimizations.
Tools
Tools are the building blocks of Agent. They are used to search your codebase and the web to find relevant information, make edits to your files, run terminal commands, and more.
To understand how tool calling works under the hood, see our tool calling fundamentals.
There is no limit on the number of tool calls Agent can make during a task.
Semantic search
Perform semantic searches within your indexed codebase. Finds code by meaning, not just exact matches.
Search files and folders
Search for files by name, read directory structures, and find exact keywords or patterns within files.
Web
Generate search queries and perform web searches.
Fetch Rules
Retrieve specific rules based on type and description.
Read files
Intelligently read the content of a file. Also supports image files (.png, .jpg, .gif, .webp, .svg) and includes them in the conversation context for analysis by vision-capable models.
Edit files
Suggest edits to files and apply them automatically.
Run shell commands
Execute terminal commands and monitor output. By default, Cursor uses the first terminal profile available.
To set your preferred terminal profile:
Open Command Palette (Cmd/Ctrl+Shift+P)
Search for "Terminal: Select Default Profile"
Choose your desired profile
Browser
Control a browser to take screenshots, test applications, and verify visual changes. Agent can navigate pages, interact with elements, and capture the current state for analysis. See the Browser documentation for details.
Image generation
Generate images from text descriptions or reference images. Useful for creating UI mockups, product assets, and visualizing architecture diagrams. Images are saved to your project's assets/ folder by default and shown inline in chat.
message-circle-questionAsk questions
Ask clarifying questions during a task. While waiting for your response, the agent continues reading files, making edits, or running commands. Your answer is incorporated as soon as it arrives.
Checkpoints
Checkpoints save snapshots of your codebase during an Agent session. Agent automatically creates them before making significant changes, capturing the state of all modified files.
If Agent takes a wrong turn, click any checkpoint in the chat timeline to preview your files at that point, then restore to revert all files to that state. You can also restore from the Restore Checkpoint button on previous requests or the + button when hovering over a message.
Checkpoints are useful for exploratory work, complex refactoring, and iterative development where you want safe rollback points.
Checkpoints are stored locally and separate from Git. Only use them for undoing Agent changes; use Git for permanent version control.
Queued messages
Queue follow-up messages while Agent is working on the current task. Your instructions wait in line and execute automatically when ready.
Using the queue
While Agent is working, type your next instruction
Press Enter to add it to the queue
Messages appear in order below the active task
Drag to reorder queued messages as needed
Agent processes them sequentially after finishing
Keyboard shortcuts
While Agent is working:
Press Enter to queue your message (it waits until Agent finishes the current task)
Press Cmd+EnterCtrl+Enter to send immediately, bypassing the queue
Immediate messaging
When you use Cmd+EnterCtrl+Enter to send immediately, your message is appended to the most recent user message in the chat and processed right away without waiting in the queue.
Your message attaches to tool results and sends immediately
This creates a more responsive experience for urgent follow-ups
Use this when you need to interrupt or redirect Agent's current work