Cursor Agent: modes, tools and checkpoints explained

What is Cursor Agent?

Cursor Agent is the AI assistant built into the Cursor editor that can finish coding tasks on its own. In Cursor's words, Agent "can complete complex coding tasks independently, run terminal commands, and edit code." You open it in the side pane with Cmd+I (Ctrl+I on Windows and Linux), describe what you want, and it searches your code, makes edits and runs commands until the job is done.

Cursor's Agent overview describes three building blocks:

1. Instructions: the system prompt plus your rules.
2. Tools: file editing, codebase search, terminal commands and more.
3. Model: whichever model you pick for the task.

Cursor tunes the instructions and tools for each model it supports, so you can switch models without rewriting how you work. Use the model picker at the top of the chat input, or press Cmd / to cycle through models. The change applies to the current conversation from that point on.

Which modes does Cursor Agent have?

Modes change what the agent is allowed to do and how it approaches a task. Press Shift+Tab in the chat input to rotate through them, or use the mode picker dropdown.

Ask mode. The Ask mode help page calls it "a read-only mode for understanding your codebase." Good prompts are questions like "How does the authentication flow work?" or "Where is the database connection configured?" When an answer leads to a change, switch back to Agent.

Plan mode. In Plan Mode, the agent asks clarifying questions, researches your codebase and writes an implementation plan. You review and edit the plan in chat or as a Markdown file, then click to build it. Plans save to your home directory by default; click "Save to workspace" to keep one in the repo for your team. Cursor may suggest Plan mode on its own when your prompt looks like a complex task.

A useful habit from the docs: if the agent builds the wrong thing, revert, sharpen the plan and run it again. That is often faster than fixing a half-finished result with follow-up prompts.

Debug mode. Debug Mode does not jump straight to a fix. The agent generates several hypotheses, adds log statements that report to a local debug server, asks you to reproduce the bug with specific steps, reads the logs, then makes a focused fix. Once you confirm the fix, it removes the instrumentation. It suits race conditions, performance problems and regressions.

Custom Modes. Any skill can become a mode. Type /, pick a skill and press Option+Enter (Alt+Enter on Windows), or select Use as Mode. The skill then stays in context on every turn until you exit, which works well for a review checklist or a /tdd playbook. Our Cursor skills guide covers how skills load. Custom Modes are available in the Agents Window and the CLI.

There is also Design Mode in the Agents Window browser: press Cmd+Shift+D, click or draw on elements of your running app, and prompt against what you selected.

What tools can Cursor Agent use?

Tools are how the agent acts. Cursor's docs say "There is no limit on the number of tool calls Agent can make during a task." The built-in tools are:

• Search files and folders: find files by name, read directory structures and search for exact text or patterns.
• Web: generate search queries and search the web.
• Fetch Rules: pull in specific rules based on their type and description.
• Read files: read file contents, including images (.png, .jpg, .gif, .webp, .svg) for vision-capable models.
• Edit files: suggest edits and apply them automatically.
• Run shell commands: run terminal commands and watch the output, using your first terminal profile by default.
• Browser: control a browser to take screenshots, test your app and check visual changes.
• Image generation: create images from text or reference images, saved to your project's assets/ folder by default.
• Ask questions: ask you to clarify while it keeps reading and editing in the meantime.

You can add more tools through MCP servers. All MCP connections need your approval, and each MCP tool call needs approval too unless you allowlist it. See our Cursor MCP guide for setup.

How do checkpoints work?

Checkpoints are snapshots of your files that Agent creates automatically before significant changes. They are your undo button for agent work.

To roll back, click any checkpoint in the chat timeline to preview your files at that point, then restore. You can also use the Restore Checkpoint button on an earlier request, or the + button that appears when you hover over a message. Restoring reverts files only. The conversation stays as it was, so you can explain what went wrong and try again.

Two limits from the docs are worth remembering:

• Checkpoints are local and separate from Git. They are not a replacement for commits.
• Use them only to undo Agent changes. For anything you want to keep long term, commit to Git.

A practical pattern is to commit before you hand the agent a big task. Checkpoints cover quick rollbacks inside the session, and Git covers everything else.

How do approvals and run modes work?

By default, Cursor lets the agent read files and search code without asking, and edit workspace files without asking, except configuration files such as workspace settings, which need approval. Terminal commands need your approval. The Agent security page notes that edits save to disk immediately, so keep your work under version control.

To cut down on prompts, choose a Run Mode in Settings > Agents > Approvals & Execution. The Run Modes docs describe three:

Cursor calls Auto-review "the safest useful setup for most people," and also warns that it "is not a security boundary" because the classifier can make mistakes. You can steer it with plain-English rules in ~/.cursor/permissions.json or <project>/.cursor/permissions.json, for example "Every AWS CLI command should go through approval first."

How do you guide Cursor Agent while it works?

A few features help you steer a running agent instead of starting over:

• @ mentions: type @ to attach files, folders, terminal output, past chats or Git diffs such as @Branch (Diff with Main). Skip it when you are not sure which files matter; the agent searches on its own.
• Queued messages: while Agent works, press Enter to queue your next instruction for after the current task, or Cmd+Enter to send it immediately.
• Images and voice: paste a screenshot or mockup into the chat input, or click the microphone to dictate.
• Side chats: type /side or /btw to ask a side question without derailing the main conversation.
• Context ring: the ring next to the input shows how full the context window is. Click it to see what is using tokens: rules, skills, MCP, conversation and more.

Cursor is also rolling out /goal, which gives the agent a long-lived objective, such as "fix all flaky tests and make CI green," to work toward until it is complete.

Where else does Cursor Agent run?

The same agent runs in more places than the editor side pane:

• Agents Window: an agent-first interface, generally available with Cursor 3 on 2 April 2026, for running many agents across repos, locally or in the cloud. Open it from the Command Palette with Open Agents Window. See the Agents Window docs.
• Cursor CLI: the agent command brings the same modes to your terminal, plus a print mode for scripts and CI. Our Cursor CLI guide covers it.
• Cloud agents: agents that run in isolated cloud VMs. Start one by selecting Cloud in the dropdown under the agent input, or prepend & to a message in the CLI to push the conversation to the cloud, then pick it up on web or mobile at cursor.com/agents. See the Cloud Agents docs.

If you are weighing Cursor against a terminal-first agent, see Claude Code vs Cursor.

How do you keep your best Agent prompts?

Agent output depends heavily on the prompt and the rules behind it, and good ones get lost in old chats. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, with Cmd+K search to find them again. To turn a prompt you reuse into a skill Cursor can run as a Custom Mode, paste it into the free SKILL.md generator.