Cursor rule

1---
2description: "Cursor 3.7 runtime guide: choose the right tool, canvases, Design Mode, /worktree, /best-of-n, Await, and parallel execution where safe."
3alwaysApply: false
4---
5 
6# Cursor 3.7 Tools Mastery
7 
8Keep durable behavior in the core rule. Use this file for current Cursor **3.7** tool-selection patterns and the Agents Window surface.
9 
10## Cursor 3.7 workspace
11 
12In Cursor 3.7, agent work is centered in the **Agents Window**. Open it from the command palette: `Cmd+Shift+P -> Agents Window` on macOS (per the [Cursor 3 announcement](https://cursor.com/blog/cursor-3); 3.7 changelog at [cursor.com/changelog](https://cursor.com/changelog)). The classic three-pane editor is still available; switch between them at any time.
13 
14- **Multi-workspace / multi-repo:** the Agents Window can surface several workspaces at once. Name the repo or root path when handing off work, opening files, or running commands so edits land in the intended tree.
15- **Per-session execution environment:** each agent tab picks its own environment — local working tree, isolated worktree (`/worktree`), cloud sandbox, or remote SSH. State the environment in the handoff contract; it is the unit of isolation.
16- **Per-session model picker:** the model picker lives in the agent tab header (e.g. `composer-2.5`, `MiniMax-M3`, `auto`). Name the model in the handoff contract.
17- **Integrated browser:** prefer the IDE's built-in browser for local UI verification when it is exposed in your session; it matches the "snapshot-first" flow in Browser Guidance below. Cursor 3.7 adds **Design Mode** (multi-select elements, voice input) — user selections there are ground truth for UI edits.
18- **Canvases:** live React artifacts beside the chat for dashboards, reports, and structured analyses; load the `canvas` skill before `.canvas.tsx` work.
19 
20## Golden Rule
21 
22For significant actions:
23 
24```text
25Check what exists
26Choose the smallest correct tool
27Act
28Validate with the lightest useful verification
29```
30 
31## Default Tool Map
32 
33**Cursor 3.7 / Composer-style agents (typical names in current desktop agents)** — the session usually exposes something close to:
34 
35| Step | Tool / command | Notes |
36|------|----------------|-------|
37| Read a path | `Read` | Prefer over shell `cat`/`sed` |
38| Search by pattern | `Grep` | Ripgrep-backed; use for exact symbols and strings |
39| Search by meaning | `SemanticSearch` | "Where does X happen?" not exact text |
40| List paths | `Glob` | File discovery by pattern |
41| Edit in place | `StrReplace` | Surgical edits; read the file first |
42| Create or replace whole file | `Write` | Use when there is no stable old_string to patch |
43| Remove file | `Delete` | |
44| Terminal | `Shell` | Builds, tests, git, installs |
45| Web | `WebSearch`, `WebFetch` | |
46| Ask user | `AskQuestion` | |
47| Track steps | `TodoWrite` | |
48| Delegate branch work | `Task` | Subagent-style runs (types such as explore, debugger, verifier — see schema) |
49| Wait for background work | `Await` | Wait for a background shell, subagent, or a specific output token (e.g. `Ready`, `Error`) |
50| Isolated worktree | `/worktree` | Run a session in its own git worktree so concurrent edits do not collide |
51| Parallel model compare | `/best-of-n` | Run the same task across N models in parallel worktrees, then compare |
52| MCP servers | `call_mcp_tool` (+ resource helpers if present) | Read MCP tool descriptors before calling |
53| Plan mode | `SwitchMode` | When the product exposes a planning mode |
54| Images | `GenerateImage` | Only when the user asks for generated images |
55| Notebooks | `EditNotebook` | `.ipynb` cell edits |
56| Lint diagnostics | `ReadLints` | After substantive edits when available |
57| Multimodal inputs | `Read` against attached image/video paths | M3 native multimodal — treat as first-class inputs |
58| Interactive artifact | Canvas (`.canvas.tsx`) | Dashboards, reports, MCP tabular output — load `canvas` skill first |
59| Context diagnostics | Context usage report canvas | 3.7 — token breakdown across prompt, tools, rules, skills |
60 
61**Browser:** often MCP tools (for example `cursor-ide-browser`) with names like `browser_snapshot`, `browser_navigate` — follow the server's schema. **Design Mode** (3.7) is user-driven; honor multi-select and voice instructions as visual ground truth.
62 
63**Parallel batching:** issue **multiple independent tool calls in one assistant turn** when the runtime allows it.
64 
65**Other Cursor surfaces** (CLI, older builds, API): names may differ (`ReadFile`, `ApplyPatch`, `Subagent`, etc.). The **exact tool list in the current session always wins** — same principle as `model-compatibility.mdc`.
66 
67## Pick The Right Surface (Cursor 3.7)
68 
69| Need | Best fit |
70|------|----------|
71| Trivial localized edit | IDE inline edit |
72| Multi-file feature in one repo | Single agent session in the Agents Window |
73| Risky exploration, parallel branches, anything that must not collide with the main tree | `/worktree` (isolated git worktree) |
74| High-stakes decision (design, architecture, refactor) where you want a second opinion | `/best-of-n` (run across 2–4 models, then pick or merge) |
75| Long-running shell, subagent, or CLI that takes seconds-to-minutes | `Await` on the background job, or a specific output token |
76| Work that should keep running while you walk away | Cloud session, then hand back to local when environment-specific proof is needed |
77| Standalone analytical deliverable (audit, metrics table, MCP data dump) | Canvas — not a markdown table in chat |
78| Context pressure on a long M3 run | Context usage report canvas (3.7), then compress per `minimax-m3-long-context` |
79 
80## Read and Search Guidance
81 
82- Prefer direct read/search tools over shell equivalents.
83- Batch independent reads and searches in one turn when the session allows parallel calls.
84- Use `SemanticSearch` for "how/where/what handles this?" questions, not exact symbol lookups.
85- For long files or large repos, prefer targeted `Grep` or slice-sized `Read` over full re-ingest; see `minimax-m3-long-context` for the M3 1M-context version of this.
86 
87## Editing Guidance
88 
89- Read the file first (`Read`).
90- Use `StrReplace` for focused in-file edits; use `Write` for new files or full rewrites when patch context is awkward.
91- Keep edits coherent; avoid thrashing the same file with many tiny changes.
92- Re-read or verify after editing.
93- For UI changes, re-read the post-change screenshot/frame when one is available and cite the path in the report.
94 
95## Shell Guidance
96 
97Use `Shell` for:
98- builds, tests, typechecks, and linting
99- package-manager or framework CLI commands
100- git inspection
101- long-running verification commands when no dedicated tool exists
102 
103Before starting dev servers or watchers:
104- check the terminals folder for an existing one
105- when one is started, `Await` its output token (`Ready`, `Compiled`, etc.) instead of polling
106 
107## Browser Guidance
108 
109When browser tools exist (including Cursor's integrated browser in supported builds):
110 
111```text
1121. Check tabs
1132. Navigate
1143. Snapshot before interaction
1154. Interact using snapshot refs
1165. Re-snapshot and inspect console/network when behavior is unclear
117```
118 
119Use browser checks for layout-sensitive UI work, interaction bugs, and issues shell commands cannot prove.
120When the user selects elements in **Design Mode**, treat those selections like attached screenshots — cite what was selected and what you changed.
121Do not promise a browser-only or canvas deliverable until you have confirmed that path in the current runtime.
122 
123## MCP and Plugin Guidance
124 
125- Prefer direct tools exposed in the prompt over wrapper APIs.
126- If an MCP server exposes resources instead of action tools, use the resource functions the environment provides.
127- **MCP Apps structured content**: when a tool returns structured content, prefer the structured form over prose dumping; render rich tabular output in a **canvas** when the data is the deliverable.
128- Keep repo guidance generic enough to survive tool and server renames.
129 
130## Task and subagent guidance
131 
132In Composer-style agents the delegation tool is usually **`Task`**, with a `subagent_type` and prompt (see the live schema). Use it for isolated research, broad exploration, debugger or verifier passes, or branches that would otherwise pollute the main context.
133 
134When multiple delegations are truly independent:
135- launch them concurrently in the same assistant turn when the schema allows
136- give each run a distinct scope, expected output, and stopping point
137- keep one synthesis step in the main thread after they return
138- avoid overlap that makes two agents inspect the same surface without a reason
139 
140For long-running delegations, `Await` the subagent result instead of polling. In **Multitask Mode**, run `Task` in the background (`run_in_background: true`) and `Await` completion. Subagents can nest further `Task` calls (3.7) — keep depth shallow; the main thread still owns synthesis and edits.
141 
142Good parallel split examples:
143- frontend investigation vs backend investigation
144- version research vs codebase pattern search
145- debugger pass vs verifier pass
146- `/best-of-n` style: same prompt to 2–3 models in isolated worktrees
147 
148Bad parallel split examples:
149- two agents editing the same file
150- agent B depends on findings from agent A
151- multiple agents exploring the whole repo with no separation
152 
153If the task is narrow, prefer direct tools over spawning subagents.
154 
155## Parallelism
156 
157Parallelize only when calls are independent:
158- multiple reads
159- unrelated searches
160- independent research tracks
161- separate `Task` / subagent investigations with different scopes
162 
163For `Task` specifically:
164 
165```text
1661. Split the work into independent slices
1672. Launch multiple Task calls in one message when they do not depend on each other
1683. Wait for all results (use Await for long-running ones)
1694. Synthesize centrally before acting
170```
171 
172Do not parallelize dependent edits or steps that require previous outputs, and do not default to serial Task launches when a parallel batch is possible.
173