Subagents and Custom Agents Compared: Claude Code vs Codex vs Cursor vs Gemini CLI vs GitHub Copilot (2026)

Custom subagents are Markdown files with YAML frontmatter. The body becomes the subagent's system prompt. Only name and description are required.

• Locations, by priority: managed settings, the --agents CLI flag (JSON, current session only), .claude/agents/ (project), ~/.claude/agents/ (user), then a plugin's agents/ directory.
• Optional fields include tools (allowlist), disallowedTools (denylist, applied first), model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation (worktree) and color.
• Built-in subagents: Explore (read-only search), Plan (read-only research in plan mode), general-purpose, claude, statusline-setup and claude-code-guide.
• Invocation: automatic delegation by description, natural language, an @-mention such as @agent-<name>, or claude --agent <name> to run the whole session as that agent.
• Background: background subagents run concurrently, and Ctrl+B moves a running task to the background. The default limit is 20 concurrent subagents (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS).
• Model: sonnet, opus, haiku, fable, a full model ID, or inherit. CLAUDE_CODE_SUBAGENT_MODEL sets a default.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Codex custom agents are standalone TOML files, one agent per file. Codex identifies the agent by its name field, not the filename.

• Locations: ~/.codex/agents/ (personal) and .codex/agents/ (project).
• Required fields: name, description, developer_instructions. Optional: model, model_reasoning_effort, model_reasoning_summary, model_verbosity, features.* keys and skills settings.
• A custom agent cannot override sandbox_mode, approval_policy, model_provider or mcp_servers. It inherits these from the parent.
• Built-in agents: default, worker and explorer. A custom agent with the same name as a built-in takes precedence.
• Invocation: ask directly, for example "spawn two agents", or name a custom agent in your prompt. Project or skill instructions can also request delegation.
• Parallel: Codex spawns agents, waits for all results and returns one consolidated response. You can open a subagent thread, and ask Codex to steer, stop or close subagent threads.
• Global [agents] settings include agents.enabled, agents.max_concurrent_threads_per_session, agents.default_subagent_model, agents.default_subagent_reasoning_effort and agents.interrupt_message.
• Tool limits: subagents inherit the parent permissions. To reduce capabilities, set feature keys such as features.shell_tool to false.

Cursor subagents are Markdown files with YAML frontmatter followed by the prompt. Cursor also reads Claude Code and Codex agent folders.

• Project locations: .cursor/agents/, .claude/agents/, .codex/agents/. User locations: ~/.cursor/agents/, ~/.claude/agents/, ~/.codex/agents/.
• Project agents override user agents. When names clash, .cursor/ wins over .claude/ or .codex/.
• Fields: name (defaults to the filename), description, model (default inherit), readonly (default false), is_background (default false).
• Built-in subagents: explore (uses a faster model by default) and browser (controls the browser via MCP tools).
• Invocation: the agent delegates based on the description, or you call one with /name in a prompt, such as /verifier, or by naming the subagent.
• Parallel and background: multiple Task tool calls in one message run at the same time. is_background: true returns immediately. Subagents can run in their own Git worktree or cloud VM. /in-cloud runs the next task as a cloud subagent, and /autopilot hands a pull request to a cloud subagent.
• Model: inherit or a model ID, with bracket options such as claude-opus-5[effort=high].
• Tool limits: subagents inherit all parent tools. readonly: true is the only documented restriction field.

Gemini CLI agents are Markdown files with YAML frontmatter. The body becomes the agent's system prompt. Subagents are enabled by default.

• Locations: .gemini/agents/*.md (project) and ~/.gemini/agents/*.md (user).
• Fields: name and description (required), kind (local or remote, default local), tools, mcpServers, model (default inherit), temperature (default 1), max_turns (default 30), timeout_mins (default 10).
• Built-in subagents: codebase_investigator, cli_help and generalist are on by default. browser_agent is off by default and needs Chrome 144 or later.
• Invocation: automatic delegation, or start the prompt with @ and the name, such as @codebase_investigator. Each subagent is exposed to the main agent as a tool with the same name.
• Model: set per agent with model, or override in settings.json with agents.overrides.
• Tool limits: the tools list supports wildcards *, mcp_* and mcp_server_*. Subagents cannot call other subagents. policy.toml rules can target a subagent with the subagent property.
• Turn subagents off with "experimental": { "enableAgents": false } in settings.json. Manage them with /agents.

---
name: my-agent
description: When the main agent should call this subagent
tools:
  - mcp_*
model: inherit
max_turns: 30
---

System prompt for the subagent goes here.

Copilot custom agents are agent profiles: Markdown files with YAML frontmatter. The body holds the prompt, up to 30,000 characters. The filename, minus .md or .agent.md, is the agent's identifier.

• Copilot CLI locations: .github/agents/ (project) and ~/.copilot/agents/ (user), using the .agent.md extension. The home directory version wins on a name clash.
• Cloud agent locations: .github/agents/ in a repository, or /agents/ in an organization's .github or .github-private repository. Enterprise agents live in a .github-private repository. A repository agent overrides an organization agent, which overrides an enterprise agent.
• Fields: description (required), name (optional display name), target (vscode or github-copilot), tools, model, disable-model-invocation, user-invocable, mcp-servers, metadata. infer is retired.
• Built-in CLI agents: explore, task, general-purpose, code-review, research (only via /research) and rubber-duck (runs on a different model).
• CLI invocation: /agent in interactive mode, naming the agent in a prompt, inference from the description, or copilot --agent <name> --prompt "...".
• Parallel: agents run as subagents with separate context windows, in parallel where appropriate.
• Tool limits: omit tools or use ["*"] for all tools, list aliases such as read, edit, search, execute, agent, web and todo, or use [] to disable all. MCP tools use server/tool or server/*.

---
name: reviewer
description: Reviews pull requests for security issues
tools: ["read", "search"]
---

Review the changes and report security problems.

• Need the finest tool control: Claude Code has both an allowlist and a denylist, plus per-agent permission mode, hooks and worktree isolation. Copilot also has a tools list with aliases and MCP namespacing.
• Want one agent folder that works in more than one tool: Cursor reads .claude/agents/ and .codex/agents/ as well as .cursor/agents/.
• Want parallel workers with one merged answer: Codex documents spawning many agents and returning one consolidated response.
• Want background or cloud runs: Claude Code (background subagents, Ctrl+B) and Cursor (is_background, cloud subagents) document this. The Gemini CLI page does not.
• Need org-wide shared agents on GitHub: Copilot supports organization and enterprise agent profiles in a .github or .github-private repository.
• Want to tune sampling per agent: Gemini CLI documents temperature, max_turns and timeout_mins fields.