Claude MarketplacesSubmit

Claude Code Agent Teams and Subagents: Setup and Real Numbers

Mert DüzgünPublished 7 minute read

Claude Code has two ways to split work across more than one agent: subagents, which run inside your session and report back, and agent teams, where a lead session coordinates separate Claude Code instances that message each other. On November 14, 2026 we read 2,195 of the top repos behind CCM listings and found 8,490 agent files in 523 of them.

What a Claude Code subagent is

The subagents docs describe a subagent as a specialized assistant that runs in its own context window, with its own system prompt, tool access and permissions. Use one when a side task would fill your main conversation with output you will not need again. The subagent does the work and returns a summary.

Claude picks a subagent from its description field, your request and the current context. Adding "use proactively" to the description makes Claude delegate more often. You can also force it: name the subagent in your prompt, @-mention it (for example @"code-reviewer (agent)"), or run the whole session as that agent.

  1. In your terminal, start Claude Code as the agent (replace code-reviewer with your agent's name):

    claude --agent code-reviewer

Where subagent files live

A subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt. When two definitions share a name, the higher-priority location wins:

Location Scope Priority
Managed settings Organization 1 (highest)
--agents CLI flag (JSON) Current session 2
.claude/agents/ Current project 3
~/.claude/agents/ All your projects 4
A plugin's agents/ directory Where the plugin is enabled 5

Check project agents into version control so your team shares them. Claude Code picks up edits within a few seconds. A new agents folder created during a session needs a restart.

On current versions, /agents only prints a reminder to ask Claude or edit these folders. Its interactive wizard ended with v2.1.197.

Frontmatter fields

Only name and description are required. The others you will use most:

  • tools and disallowedTools limit what the agent can call. Leave tools out and the agent inherits every tool available to subagents.
  • model takes sonnet, opus, haiku, fable, a full model ID, or inherit.
  • color sets the display color (red, blue, green, yellow, purple, orange, pink or cyan).
  • permissionMode, maxTurns, skills, mcpServers, hooks, memory, effort, background and isolation (worktree gives an isolated copy of the repo) are the other common ones. The docs table lists a few more.

Plugin agents ignore hooks, mcpServers and permissionMode for security reasons. A misspelled field is ignored without an error.

An example we wrote from the documented fields, saved as .claude/agents/test-runner.md:

---
name: test-runner
description: Runs the test suite and reports failures with file and line. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
color: yellow
maxTurns: 20
---

You run tests. Find the project's test command, run it, and report each
failing test with its file, line and error message. Do not edit files.
Return a short list of failures and the command you ran.

The docs' model order: a model Claude passes on the call, then the file's model field, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model.

What 8,490 agent files show

We scanned the top 2,200 repos by GitHub stars among those behind CCM skill and marketplace listings (2,195 read, as of November 14, 2026). These are the counts for every agents/<name>.md path:

Frontmatter model value Agent files
No model field 4,196
sonnet 2,189
inherit 782
opus 695
haiku 382
Other values (gpt-4.1, fable, full IDs and more) 246

About half of all agent files set no model (1,330 of them have no frontmatter at all), so they follow the model order above. Another 782 say inherit, which picks the main conversation's model and takes priority over CLAUDE_CODE_SUBAGENT_MODEL. Of the 3,512 files that name a model other than inherit, about 62% pick sonnet, about 20% opus and about 11% haiku.

About half the files (4,308) set a tools list, and 1,831 set a color. The median repo with agents has 5 of them, and 165 repos have 10 or more.

The count includes mirrors and duplicates. affaan-m/ecc and everything-claude-code are the same 310 files, and Axiom shows up twice under two casings of its name.

The repos with the most agent files:

Repo Agent files GitHub stars (November 14, 2026)
jeremylongshore/claude-code-plugins-plus-skills 381 2,608
davepoon/buildwithclaude 343 3,738
affaan-m/everything-claude-code 310 300,916
josstei/maestro-orchestrate 273 488
gtmagents/gtm-agents 204 438
wshobson/agents 202 42,406

We left out affaan-m/ecc (a mirror) and github/awesome-copilot (234 files, mostly GitHub Copilot .agent.md agents).

Claude Code Game Studios is a smaller example from our scan: 49 agents and 75 skills in its .claude/ folder, sorted into three tiers with directors such as creative-director at the top (37,658 GitHub stars, November 14, 2026).

What agent teams are

Agent teams are a separate, experimental feature. One session is the team lead. It spawns teammates, and each teammate is a full Claude Code instance with its own context window. Teammates share a task list, claim work from it, and message each other through a mailbox.

Per the docs, subagents return a result to the caller and the main agent manages the work, while teammates coordinate among themselves. Subagents cost fewer tokens because results get summarized back. Each teammate is a separate Claude instance, so teams cost more.

Teams are off by default. To turn them on and start one:

  1. In settings.json, set the environment variable:

    {
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

    Or set it in your terminal before you start Claude Code:

    export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

  2. Optional: to give each teammate its own pane in tmux or iTerm2, add this to ~/.claude/settings.json (iTerm2 also needs the it2 CLI):

    {
  "teammateMode": "auto"
}

  3. Inside Claude Code, ask for a team in plain words, for example:

    Spawn three teammates to review pull request #142: one on security, one on performance, one on test coverage.

You can reuse a subagent definition as a teammate role ("Spawn a teammate using the security-reviewer agent type").

With teams on, a subagent that Claude names launches as a teammate, so a team can form when you did not ask for one. And teams do not spawn in non-interactive mode (-p) or the Agent SDK.

The documented limits: one team per session, no nested teams, the lead is fixed, /resume and /rewind do not bring back in-process teammates, and task status can lag. The docs suggest 3 to 5 teammates and about 5 or 6 tasks per teammate, and warn that two teammates editing the same file overwrite each other.

Hooks support both features. SubagentStart and SubagentStop fire for subagents. TeammateIdle, TaskCreated and TaskCompleted fire for teams, and exit code 2 sends feedback that keeps a teammate working or stops a task from being created or closed. Our Claude Code hooks post covers the format.

How to install a plugin that ships agents

The wshobson/agents marketplace has an agent-teams plugin with four agents (team-lead, team-reviewer, team-debugger, team-implementer) and commands such as /team-review and /team-debug. Its team-reviewer pins model: opus and lists SendMessage and the Task tools in tools. To install it:

  1. Turn on agent teams, as in the steps above. The plugin needs CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

  2. Inside Claude Code, add the marketplace:

    /plugin marketplace add wshobson/agents

  3. Inside Claude Code, install the plugin:

    /plugin install agent-teams@claude-code-workflows

For a workflow on plain subagents, Superpowers has subagent-driven-development and dispatching-parallel-agents. More in our Superpowers post.

Teams or subagents: when to use each

Start with subagents. Teams are still experimental. Of the 477 repos in our scan with a hook config (November 14, 2026), 59 hook SubagentStop and 45 hook SubagentStart, against 17 each for TeammateIdle and TaskCompleted.

Use a team when the workers need to talk to each other. The docs list four good fits: research and review, new modules where each teammate owns a piece, debugging with competing hypotheses, and changes across frontend, backend and tests. For a sequential task, or for edits to the same file, one session or a subagent does better.

Use inherit for agents that need your main model's judgment. Cheap, high-volume work like running tests or searching can pin haiku, which the docs also suggest for cost. If you want the same model whatever the main session runs, sonnet is the most common pin in published agents.

Where to start

Write one project agent in .claude/agents/ for a task you repeat, give it a short description and a tools list, and check it in. Browse plugins on CCM to see how others write theirs: wshobson/agents has 94 plugins in one marketplace and 202 agent files, and gsd-core ships 67 agent files (November 14, 2026). Turn on agent teams only for a review or debugging task that gains from separate reviewers who check each other's findings.

More from the blog