Cursor subagents
Write a Cursor subagent in .cursor/agents with name, description, model, readonly and is_background. Includes model bracket options.
Locations and precedence
Project .cursor/agents/, also .claude/agents/ and .codex/agents/. Project wins over user; .cursor/ wins over Claude or Codex paths.
Documented fields
| Field | Notes |
|---|---|
name | Optional; lowercase letters and hyphens; defaults from filename |
description | Drives delegation hints |
model | inherit or ID with optional [effort=high,context=300k] brackets |
readonly | No file edits or state-changing shell |
is_background | Non-blocking run |
How Claude-only fields are treated when reading .claude/agents/ is not documented (unverified).
FAQ
- Does Cursor read Claude Code agents?
- Yes, .claude/agents/ is listed as a project and user location. Extra Claude-only fields are not documented for Cursor (unverified).
- Can I restrict tools?
- Cursor docs do not list a per-subagent tool allowlist. readonly: true blocks file edits and state-changing shell commands; MCP tools still inherit from the parent.
- Why is my subagent on a different model?
- Model may be inherit, a specific ID, or include bracket params. Admin blocks, plan limits or legacy Max Mode rules can override the model at runtime per Cursor docs.
- Does Cursor parse Codex TOML in .codex/agents/?
- The subagents page lists .codex/agents/ as a location but describes each subagent as Markdown. Whether TOML is parsed is not documented (unverified).
- How do I run a subagent in the background?
- Set is_background: true in frontmatter. Background subagents run without blocking the parent.