Claude Subagents and Teams

Subagents

Specialized assistants with their own context window, system prompt, tool access, and permissions. Claude delegates by matching the agent's description.

Built-in	Model	Notes
Explore	main model	Read-only codebase search
Plan	inherits	Read-only research in plan mode
general-purpose	`CLAUDE_CODE_SUBAGENT_MODEL` else main	Multi-step, explore + act
claude	follows subagent model order	Catch-all
statusline-setup	sonnet	`/statusline`
claude-code-guide	haiku	Answers Claude Code questions

Locations, highest priority first: managed settings → --agents flag → .claude/agents/ → ~/.claude/agents/ → plugin agents/.

Custom Subagents

Markdown file with frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (user):

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Give specific, actionable feedback.

Field	Purpose
`name`, `description`	Explicit trigger name; auto-delegation trigger
`tools`, `disallowedTools`	Allow/deny lists (patterns like `Bash(git diff:*)` OK)
`model`	`sonnet`, `opus`, `haiku`, `fable`, full ID, or `inherit`
`permissionMode`	`default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` (ignored for plugin agents)
`maxTurns`	Turn cap
`skills`, `mcpServers`, `hooks`	Extra capabilities scoped to this agent
`memory`	Persist at `user` / `project` / `local` scope
`background`	Always run in background
`isolation`	`worktree` = temporary git worktree
`effort`, `autoCompactWindow`	Per-agent effort / compact window (100K–1M)
`omitClaudeMd`	Skip CLAUDE.md files at startup
`color`, `initialPrompt`	Display color; first turn when run as the main agent

Agent Teams

Multiple Claude instances: team lead + teammates + shared task list + mailbox. Teammates have isolated contexts but talk to each other, and you can message any of them.

	Subagents	Agent teams
Flow	Main → worker → report back	Lead assigns via shared list; teammates coordinate directly
Use for	Quick focused tasks	Parallel exploration, competing theories, separate layers (frontend/backend/tests)

Experimental, disabled by default. Enable: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 (shell or settings.json env).
Create by prompting: "Create an agent team: one on UX, one on architecture, one devil's advocate."
teammateMode (or --teammate-mode): in-process is the default; auto = split panes inside tmux/iTerm2 (it2 CLI) else in-process; tmux; iterm2. Split panes aren't supported in VS Code's terminal, Windows Terminal or Ghostty.
Panel: ↑/↓ select a teammate, Enter opens it, x stops it, Ctrl+T toggles the task list.
Model order: model named in your prompt → definition's model → CLAUDE_CODE_SUBAGENT_MODEL → lead's model.
Limits: no session resumption for in-process teammates, one team per session, no nested teams, task status can lag. Costs far more tokens; start with 3–5 teammates and give each distinct files.
With teams on, a subagent Claude names launches as a teammate; set the env var to 0 to stop that.
Stored in ~/.claude/teams/{team}/config.json and ~/.claude/tasks/{team}/.
Teammates inherit the lead's permission mode (except dontAsk), including --dangerously-skip-permissions. Their permission prompts surface in the lead session.
Hooks: TeammateIdle, TaskCreated, TaskCompleted (exit code 2 sends feedback).