Cursor subagents: specialists with their own context window

As Agent takes on bigger tasks—wide refactors, multi-file research, long test runs—the main conversation fills up fast. Search results, terminal logs, and browser snapshots are useful, but they are also noisy. Cursor’s answer is subagents: smaller, specialized assistants the parent Agent can spin up, each with its own context window, tools, and (optionally) model. They do the work, return a summary, and leave your primary thread room to think.

You can use subagents in the editor, the CLI, and Cloud Agents. The mental model is delegation, not a second chat you manage by hand. When Agent decides a task is a good fit—or when you ask explicitly—it launches a subagent with a self-contained prompt. That prompt must carry the context the subagent needs, because subagents start fresh: they do not see your earlier messages unless the parent passes them along.

Four ideas explain why subagents exist. Context isolation keeps long exploration or verbose command output out of the main window; the parent only sees the final message. Parallel execution lets several subagents run at once on different parts of a problem. Specialized expertise comes from custom prompts, tool access, and model choice per subagent. Reusability means you can check project-specific agents into .cursor/agents/ and share them with the team.

Subagents run in one of two modes. In foreground mode, the parent waits until the subagent finishes—best when the next step depends on that result. In background mode, the parent continues immediately while the subagent works on its own—better for long jobs or parallel streams. Background subagents write progress under ~/.cursor/subagents/ so the parent can check in later; you can also resume a subagent by agent ID when a task spans multiple turns.

Cursor ships three built-in subagents you do not configure yourself. Explore searches and analyzes the codebase; it is tuned for many parallel searches with a faster model so exploration does not swamp the main context. Bash runs shell commands and keeps voluminous stdout/stderr out of the parent’s way. Browser drives browser automation via MCP and filters noisy DOM and screenshots down to what matters. Agent picks these automatically when the job fits—think “find every usage of X” or “run this test suite and interpret the log,” not “rename this variable.”

When should you reach for a subagent versus a skill? Subagents earn their overhead when you need isolation for long research, multiple parallel workstreams, multi-step specialist work, or an independent sanity check (for example verifying that “done” actually works). Skills fit single-purpose, one-shot actions—generate a changelog, format imports—where you do not need a separate context window. If you are tempted to create a subagent for a trivial repeatable task, a skill or slash command is usually the lighter choice.

Custom subagents live in markdown files with YAML frontmatter. Project agents go in .cursor/agents/ (also .claude/agents/ or .codex/agents/ for compatibility). User agents live under ~/.cursor/agents/ and apply everywhere. Project definitions win on name conflicts, with .cursor/ taking precedence over the other folders. A minimal file sets name, description, and the system-style prompt body; optional fields include model (inherit or a specific model ID), readonly: true for audit-only agents, and is_background: true for non-blocking runs.

The description field is your routing signal. Agent reads it when deciding whether to delegate. Phrases like “use proactively” or “always use for” nudge automatic invocation; vague lines like “helps with coding” do not. You can also call a subagent explicitly with /verifier confirm the auth flow or plain language: “Use the debugger subagent on this stack trace.” For throughput, ask for parallel work in one message—Agent can issue multiple Task tool calls so several subagents run at the same time.

Two patterns show up often in real repos. A verifier subagent is skeptical by design: it checks that claimed work exists, runs tests, and reports what passed versus what was only half-done—useful before you mark a ticket complete. An orchestrator flow chains specialists: planner → implementer → verifier, each handing structured output to the next. Since Cursor 2.5, subagents can launch child subagents too, forming a tree of coordinated work (subject to Task tool access and any hook policies you set).

Subagents inherit the parent’s tools, including MCP servers, unless readonly or team policy restricts them. They are not free: each run has startup overhead and its own token bill; five parallel subagents can use roughly five times the tokens of one agent. For quick edits, the main Agent is often faster. Subagents pay off on complex, long-running, or parallel jobs where context hygiene matters more than saving a few seconds.

Practical adoption: start with two or three focused agents—verifier, debugger, test-runner—not dozens of generic helpers. Commit .cursor/agents/ to version control. Let Agent draft the first verifier.md, then tighten the description until the right agent triggers on real prompts. When you need the full event matrix, configuration fields, and FAQ (model fallbacks, Max Mode, nested subagents), use the official guide at https://cursor.com/docs/subagents as the canonical reference.