cursor-cli

Cursor CLI (subagent/task delegation)

Use Cursor CLI to run a separate long-horizon pass over the repo: multi-step implementation, broad refactors, batch file writes, or deep exploration—similar to handing a task to a subagent. You stay orchestrator: smaller prompts, less context burn, often lower spend than doing the same work entirely in-session.

When to use Cursor CLI

• Large or multi-step work: several files, phases, or checkpoints (feature slice, migration, test suite, docs sweep).
• Heavy code generation or editing: Cursor drives --yolo tool use while you summarize outcomes and merge.
• Parallel mental lane: you continue planning or reviewing while Cursor runs a bounded task.
• User explicitly asks for Cursor or “use Cursor for this.”

When not to use

• Small / single-step tasks answerable with one or two edits or a short explanation.
• Tight feedback loops where the user wants rapid back-and-forth refinement in one thread.
• Secrets or policy-sensitive flows—avoid piping credentials; redact before delegating.
• Already-loaded context where duplicating the whole plan adds no value—handle locally.
• Low ROI (Return on Investment): If the task is "needle-in-a-haystack" (requires high precision over a single line) or if the time to compose the Handoff Table exceeds the time to simply edit the file locally. Delegation should only be used when the "mental offloading" outweighs the "handoff overhead."

Delegation and context (critical)

Isolated subagent context saves tokens but splits the story: Cursor does not see the main session's full thread. Poor handoffs cause misread subtasks, conflicting assumptions (stack, style, APIs), and wasted edits.

When composing the single Cursor prompt, treat it as passing enough shared state, not just a title:

Include	Why
Original goal	Same north star as the user—not only the immediate micro-task.
Decisions already made	Framework, patterns, naming, auth approach, “use X not Y”—anything that would otherwise be guessed wrong.
Scope	Paths, modules, and explicit out of scope / do-not-touch areas.
Constraints	Performance, a11y, compatibility, review gates, “no new deps,” etc.
Verification	Explicit command (e.g. npm test, lint) the subagent must run and pass before returning.
Expected output	e.g. “summarize then list files changed,” “report only—no edits,” or “apply edits with minimal diff.”