skip to content

In Cursor's Agent panel, how do Plan mode and Debug mode change what the agent does before it edits code?

level: juniorimportance: should knowfreq 16%

answer

  1. Shift+Tab or the mode picker
  2. Plan: questions, research, an editable plan
  3. nothing built until you click Build
  4. Debug: hypotheses, then log statements
  5. local debug server; you reproduce

basics

~20 s

Plan mode asks clarifying questions, researches the codebase and writes an editable plan, coding only after you click Build. Debug mode forms hypotheses, adds logging that reports to a local debug server, has you reproduce the bug, fixes it, then removes the logging.

solid answer

~50 s

Both are modes of Cursor's Agent, reached with Shift+Tab from the chat input or from the mode picker. **Plan mode** holds back the edits: Agent asks clarifying questions, researches the codebase and produces a plan that opens as a file you can read and edit, and nothing is built until you click **Build**. Plans are saved in your home directory unless you choose **Save to workspace**. **Debug mode** is for a bug you can reproduce but not explain: Agent generates several hypotheses, adds log statements that send data to a local debug server running in a Cursor extension, gives you steps to reproduce the bug, reads the logs, makes a targeted fix and removes the instrumentation once you confirm. Plain Agent mode edits files and runs commands as it works, with no separate plan or evidence step. Each mode has its own context, so switching modes starts a fresh context window.

go deeper

for a junior

Know that Shift+Tab or the mode picker switches between Agent, Plan and Debug, and that Plan writes nothing until you click Build.

for a middle

Explain Debug mode's loop: hypotheses, log statements to a local debug server, your reproduction, a small fix and removal of the logging after you confirm it.

for a senior

Show when you reach for each mode on a real team, and why reverting and refining the plan beats patching a build that went the wrong way.

for a principal

Weigh the cost of a plan-first habit against speed, and decide where saved plans should live so the team can review and reuse them.

## Three modes of one agent Cursor's **Agent** is the assistant in the side panel (Cmd+I on Mac, Ctrl+I on Windows and Linux) that searches the codebase, edits several files and runs terminal commands. What it does first depends on the **mode** you pick. You switch modes by pressing **Shift+Tab** in the chat input, which cycles through them, or with the **mode picker** dropdown in the Agent panel. | Mode | Best for | Edits files? | |---|---|---| | **Agent** | Building features, refactoring, fixing bugs you understand | Yes, as it works | | **Plan** | Complex work where you want to review the approach first | Yes, after you approve the plan | | **Debug** | Bugs that need runtime evidence | Yes, a targeted fix after the evidence | Cursor also has a read-only **Ask** mode on the same picker; it answers questions and never edits, and it is a separate subject. Project, user and team rules apply in every mode. ## How Plan mode works **Plan mode** puts a reviewable document between your request and the code. In order: 1. Agent asks **clarifying questions** about your requirements. 2. It **researches the codebase** to gather context. 3. It writes an **implementation plan**, which opens as a virtual file you can read and edit. 4. You refine the plan, in chat or by editing the Markdown directly. 5. You click **Build**, and only then does Agent start writing code. Plans are saved in your **home directory** by default. **Save to workspace** moves a plan into the project, where it can be shared with the team and kept as documentation. Cursor also *suggests* Plan mode on its own when you type wording that suggests a complex task. Cursor's docs recommend Plan mode for features with several valid approaches, tasks that touch many files or systems, unclear requirements, and architectural decisions. For quick or familiar changes, plain Agent mode is fine. ## How Debug mode works **Debug mode** replaces guessing with runtime evidence. Instead of writing a fix immediately, the agent works through six steps: 1. **Explore and hypothesize**: read the relevant files and generate several hypotheses about the root cause. 2. **Add instrumentation**: insert log statements that send data to a **local debug server** running in a Cursor extension. 3. **Reproduce**: ask *you* to reproduce the bug, with specific steps, so the logs capture real behaviour. 4. **Analyze logs**: identify the actual cause from what was recorded. 5. **Targeted fix**: make a focused change, often only a few lines. 6. **Verify and clean up**: you rerun the steps; once the fix is confirmed, the agent removes all the instrumentation. It suits bugs you can reproduce but cannot explain from the code: race conditions and timing issues, performance problems and memory leaks, and regressions where something used to work. Reproducing several times helps with intermittent bugs. ## Choosing between them - You know what to build and it is small: **Agent** mode. - The task is large or ambiguous and a wrong approach would be expensive: **Plan** mode, then **Build**. - Something is broken and reading the code has not explained why: **Debug** mode. - You only want an explanation, with no edits: **Ask** mode, which is outside this question. When a Plan-mode build goes the wrong way, Cursor's guidance is to go back to the plan rather than patch the result with follow-up prompts: revert the files (the **Revert** button on an earlier message, then **Confirm**), make the plan more specific and build again. ## Details that catch people out - **Switching modes starts a fresh context window.** Each mode has its own context, so a long Agent conversation does not follow you into Debug mode. Restate the symptom. - **Plan mode is not read-only.** It edits files, but only after you click Build. - **A plan lives in your home directory** until you save it to the workspace; teammates cannot see it before then. - **Debug mode's logging is temporary.** The agent removes it after you confirm the fix, so do not expect it in the final diff. - **Debug mode depends on you.** If you skip the reproduction steps, the logs record nothing useful and the fix is a guess again.

  • A Plan-mode build in Cursor drifted from what you wanted halfway through. What does Cursor's guidance suggest instead of fixing it with more prompts?
    Go back to the plan. Revert the files to the stage before the build (the **Revert** button on an earlier message, then **Confirm**), make the plan more specific about what you need, and click **Build** again. Cursor's docs say this is often faster than steering an agent mid-build and gives cleaner results.
  • Why does Cursor's Debug mode ask you to reproduce the bug instead of finding the cause by reading code?
    Its evidence is runtime data. The agent adds log statements that report to a local debug server, then gives you specific steps to trigger the bug. The cause comes from what the logs recorded, so timing bugs and leaks that look fine on the page become visible. Reproducing several times helps with intermittent failures.

  • Plan mode is read-only and never edits files
  • Debug mode attaches the editor's debugger and sets breakpoints
  • Debug mode leaves its log statements for you to delete
  • Plans are committed into the repository automatically
  • Switching from Agent to Debug mode keeps the same conversation context