Debug: reproduce, instrument, then fix

When something is already broken and a normal Agent pass can’t find the cause, Debug is Cursor’s built-in mode for that bug (Debug mode docs; the mode surface shifts between releases, so statements here are dated September 2026). You pick it from the mode picker dropdown next to the Agent chat input, the same one you switch Agent and Plan from; Cmd/Ctrl+. opens that menu, and Shift+Tab cycles through the modes (Debug mode docs; shortcut reference). Where Agent’s instinct is to implement a feature and Plan’s is to design one, Debug’s job is to find a root cause and fix it, working from runtime evidence rather than guessing at a fix. It suits exactly the failures that resist a straight-ahead attempt: race conditions, timing problems, leaks, bugs that reproduce only sometimes.

Note what Debug actually does, because it isn’t a read-only “tell me why” mode. Its loop is hands-on:

1. It generates several hypotheses about what’s going wrong.
2. It instruments your code with logging statements to test them - meaning it edits files before the root cause is known, planting probes rather than waiting until it’s certain. The probes send their output to a local debug server hosted in a Cursor extension.
3. You reproduce the bug (the loop needs a failure you can trigger locally at least sometimes) so the probes emit their runtime logs; Debug gives you the steps and keeps you in the loop while it captures real behavior.
4. It analyzes the logs and isolates the cause.
5. It ships a targeted fix - typically a few lines - has you re-run the reproduction to confirm it, then removes the instrumentation it added.

So Debug both edits to diagnose and delivers the fix. The contrast with Agent isn’t “Debug won’t touch your code” - it will, twice. It’s that Debug is built around the reproduce-instrument-fix cycle for something already broken, and its fix answers to evidence gathered from a real run instead of a first guess.

The same postures from the CLI

Everything in this chapter starts in the editor, but the postures travel. Cursor’s CLI - its terminal agent, run as the agent command (cursor-agent remains a backward-compatible legacy alias, CLI changelog) - takes /plan, /ask, and /debug to switch modes in its interactive view (slash-command reference). We cover the CLI properly in its own chapter; the thing to carry forward now is that modes aren’t a GUI gimmick. They’re a posture that follows you into the terminal.

All four postures - Ask (read-only Q&A), Agent, Plan, and Debug - share one assumption: that the agent is looking at the right code. It often isn’t - and a wrong-file answer arrives with exactly the same confidence as a right one, in any mode you pick. The next chapter is about what’s in front of the agent when it starts. Next: context, @-tagging and self-gathering.