Using Claude Code's Agent Team Feature

Run multiple specialized Claude agents in parallel to tackle complex tasks faster and keep your main context window lean.

An agent team lets you delegate research, code review, and multi-step tasks to specialized sub-agents while keeping your main conversation context clean. Each agent starts with its own fresh context window, runs its task, and returns a single summary — so your main session does not accumulate the noise of every file search and exploration step.

What the agent team is

Claude Code can spawn sub-agents on demand. Each agent:

Starts cold with a clean, empty context window
Runs a specific task described in a prompt you provide
Returns one summary message back to the parent conversation

Agents can run in the foreground (the parent waits for the result before continuing) or in the background (you keep working while the agent runs, and you are notified when it finishes).

FleetView is the panel in the Claude Code desktop app and IDE extension that shows all agents active in the current session. From there you can monitor status, read intermediate output, and send follow-up messages to a running agent.

Agent types

Claude Code ships with purpose-built agent types tuned for specific tasks:

Agent type	Best for
`claude`	General-purpose tasks with full tool access
`Explore`	Read-only codebase search — finding files, symbols, and usages
`Plan`	Designing implementation strategies and weighing architectural trade-offs
`general-purpose`	Multi-step research and complex searches across the codebase or web
`claude-code-guide`	Questions about Claude Code, the Anthropic API, or the Agent SDK

In FleetView, you can type the agent name after a / to start a typed agent directly from the panel.

Beyond the built-in types, you can define your own custom agents with a dedicated system prompt, restricted tool set, and a fixed model. Custom agents show up in the same agent list and can be invoked exactly like the built-in ones.

Defining your own agents

Where to place agent files

Agent definitions are Markdown files with a .md extension. Claude Code looks for them in two locations:

~/.claude/agents/ — global scope. Available in every project on your machine. Good for general-purpose roles you always want: a code reviewer, a scout, a content writer.
.claude/agents/ — project scope. Only available inside that project's directory. Good for project-specific roles (an agent that knows your API conventions, a release manager that knows your deploy steps).

Project-scoped agents take precedence over global ones if both define an agent with the same name.

~/.claude/agents/
  builder.md         ← always available, every project
  reviewer.md
  scout.md

myproject/.claude/agents/
  deploy-manager.md  ← only available inside myproject/

Agent file format

Each agent file has a YAML frontmatter block followed by the system prompt:

---
name: builder
description: >
  Use for writing, refactoring, or extending code.
  Hand it a well-scoped task — a feature, a fix, a refactor.
  It reads existing conventions before making changes and stays surgical.
model: claude-sonnet-4-6
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

You are a focused, surgical code writer for this project.
Always read existing code and conventions before making changes.
Make minimal, targeted edits — no scope creep, no unrequested refactors.
Never hardcode secrets or API keys. Flag any you find.

Frontmatter fields:

Field	Required	Notes
`name`	Yes	Invocation name — what you type to spawn it
`description`	Yes	Tells Claude Code when to use this agent. Write it as a trigger condition, not just a label.
`model`	No	Overrides the session model for this agent. Use `claude-haiku-4-5-20251001`, `claude-sonnet-4-6`, or `claude-opus-4-8`.
`tools`	No	Restricts which tools the agent can call. Omit to grant all tools.

The description field is the most important one to write carefully. Claude Code reads it to decide which agent to invoke for a given task. A vague description like "helps with code" will be ignored; a specific trigger condition like "Use when asked to write, refactor, or extend code — hand it a specific file or feature, not an open-ended question" will be matched reliably.

Sample recommended agents

builder — a focused code writer. Reads before writing, stays surgical:

---
name: builder
description: >
  Use for writing, refactoring, or extending code in any project.
  Delegate well-scoped implementation tasks — a feature, a fix, a refactor.
  Not for vague exploration or architecture decisions.
model: claude-sonnet-4-6
tools: [Read, Write, Edit, Bash, Glob, Grep]
---

You are a surgical code writer. Read existing code and conventions before making
any change. Make the smallest change that solves the problem. No scope creep.
No unrequested refactors. Never hardcode secrets — flag any you find.

reviewer — read-only auditor, ideal on Haiku to save credits:

---
name: reviewer
description: >
  Use to audit code changes, diffs, or commits for correctness, security, and
  consistency. Read-only — does not write code. Run after builder finishes,
  or on demand for any diff.
model: claude-haiku-4-5-20251001
tools: [Read, Grep, Glob]
---

You are a read-only code auditor. Review for correctness bugs, security issues
(injection, hardcoded secrets, unsafe deserialization), and consistency with
surrounding code. Report findings as a concise bulleted list. Flag anything
security-critical as REQUIRES SENIOR REVIEW. Do not suggest style changes
or unrequested refactors.

scout — cheap data retrieval on Haiku, no reasoning:

---
name: scout
description: >
  Use for cheap, high-volume data retrieval — reading files, listing paths,
  extracting function signatures, checking if a symbol exists. No analysis,
  just clean structured data. Feed its output to smarter agents.
model: claude-haiku-4-5-20251001
tools: [Read, Grep, Glob, WebSearch, WebFetch]
---

Your only job is to retrieve and return data exactly as requested. No analysis,
no opinions, no suggestions. Return results in the format the caller specifies.
If no format is specified, use a compact list. Never add explanations.

planner — architecture and strategy, worth the Opus cost:

---
name: planner
description: >
  Use for designing implementation strategies, evaluating architectural
  trade-offs, and producing step-by-step plans before coding starts.
  Invoke before builder on any non-trivial feature.
model: claude-opus-4-8
tools: [Read, Grep, Glob]
---

You are a software architect. When given a task, read the relevant code first,
then produce: (1) a concise summary of the current state, (2) a step-by-step
implementation plan, (3) any risks or trade-offs the implementer should know.
Do not write code — produce plans only.

writer — technical documentation and content:

---
name: writer
description: >
  Use for writing tutorials, documentation, README files, and technical
  blog posts. Turns feature descriptions or outlines into finished,
  publish-ready prose. Does not write code.
model: claude-sonnet-4-6
tools: [Read, Grep, Glob, WebSearch, WebFetch]
---

You write clear, practical technical content for developers. No filler,
no preamble, no marketing language. Use short sentences and real examples.
Match the tone and style of existing documentation in the project.

Documenting your team in CLAUDE.md

The CLAUDE.md file at the root of your project (or in ~/.claude/CLAUDE.md for global rules) is read at the start of every session. It is the right place to document which agents are in scope, when to invoke them, and any escalation rules.

A minimal agent table:

## The crew

| Agent | Model | Use for |
|---|---|---|
| `builder` | sonnet | Writing / refactoring / extending code |
| `reviewer` | haiku | Auditing diffs — read-only, run after builder |
| `scout` | haiku | Cheap file retrieval and data extraction |
| `planner` | opus | Architecture decisions before any large feature |
| `writer` | sonnet | Documentation, tutorials, README files |

## Delegation rules

- Delegate chunky, well-scoped jobs. Keep coordination in the main thread.
- `builder` implements → `reviewer` audits. Skip review for trivial edits.
- Security-critical code (auth, payments): reviewer flags `REQUIRES SENIOR REVIEW`,
  then the main thread (Sonnet/Opus) does the final sign-off.
- Never invoke `planner` for tasks that are already well-defined — go straight to builder.

You can also scope agents to specific sub-projects. If your repo has multiple packages, the CLAUDE.md inside each package can restrict which agents apply there:

## In scope here
`builder`, `reviewer`. Do NOT invoke `planner` or `scribe` in this package.

Claude Code loads CLAUDE.md files from the root, any parent directories up to the home directory, and the current working directory — all of them are merged. Project-level files take precedence over global ones.

Related commands

List available agents

/agents

Shows every agent Claude Code can see: built-in types plus any custom agents found in ~/.claude/agents/ and .claude/agents/. The output includes each agent's name, description, model, and scope (global vs. project).

Check session cost

/cost

Shows the cumulative token usage and estimated cost for the current session — broken down by input tokens, output tokens, and cache reads. Run this any time you want a mid-session cost snapshot.

Switch or inspect the active model

/model

Shows the current session model. Pass a model alias to switch:

/model haiku
/model sonnet
/model opus

Switching the session model does not affect agents that have a model: override in their frontmatter — those always use their declared model regardless of the session default.

Reload CLAUDE.md without restarting

After editing a CLAUDE.md or agent file, restart the session or open a new terminal — Claude Code reads these files at session start, not continuously. There is no live-reload command.

Checking token and cost usage

In-session: `/cost`

The /cost command gives a real-time breakdown for the current session:

Session usage
  Input tokens:   42,310
  Output tokens:  8,940
  Cache reads:    61,200
  Estimated cost: $0.18

Cache reads (prompt cache hits) are billed at a much lower rate than fresh input tokens — this is where long-running sessions with heavy CLAUDE.md and memory files get cheaper over time rather than more expensive.

Account-level: claude.ai/settings/usage

The web dashboard at claude.ai/settings/usage shows cumulative usage across all sessions and projects, broken down by day. This is the authoritative source for billing — the in-session /cost estimate may differ slightly due to rounding.

Keeping costs low with agents

The biggest cost lever is keeping expensive-model time focused on reasoning, not retrieval:

Scout pattern — run Haiku agents for all file reads, path listings, and data extraction. A Haiku agent reading 30 files costs roughly 10× less than a Sonnet agent doing the same.
Short reports — end every agent prompt with an output cap: "Report in under 100 words" or "Return only file paths." Large agent responses are returned to the parent context, inflating its token count.
Background for slow tasks — a two-minute test run in the background does not hold a context window open. The agent sleeps until the command finishes; you pay for active reasoning time, not wall-clock time.

When to use agents vs. inline work

Use agents for work that would otherwise inflate your main context:

Wide codebase exploration — searching many files to answer "where is X defined?"
Independent parallel questions — two or more lookups that do not depend on each other
Isolated code review — reviewing a diff without the full working session as background noise
Long-running or slow tasks — builds, test runs, waiting on CI, polling a deploy

Do not use agents for:

Short, targeted lookups where a single Grep or Read call is enough — agents carry startup overhead that makes them more expensive for small work
Steps that depend on context only the parent holds — agents start cold and do not see your conversation history unless you paste the relevant parts into the prompt
Sequential steps where each one depends on the previous result — run those inline

How to spawn an agent

Claude Code spawns agents automatically for tasks that fit the pattern. You can also request one explicitly:

Research how authentication middleware works across this project.
Use an Explore agent to keep the main context clean.

For parallel work, describe both tasks in a single message:

At the same time:
1. Find all places where the User model is mutated — use an Explore agent, quick search.
2. Check GitHub for any open issues mentioning "login failures" — use a general-purpose agent in the background.

When asking for exploration, include a breadth hint — "quick", "medium", or "very thorough" — so the agent calibrates how many files and search rounds to use.

Background agents

Background agents run while you continue the conversation. You are notified automatically when they finish.

Run the full test suite in the background and let me know when it is done.

Rules for background agents:

Do not ask for their output immediately after spawning — you will be re-invoked when they finish
Do not poll ("is it done yet?") — the runtime handles the notification, not a sleep loop
Use them for tasks with a defined end state: a build, a test run, a status check

Continuing an agent instead of spawning a new one

Agents are not single-shot. If a finished agent built up useful intermediate knowledge and you have a follow-up, continue it by referencing its ID or name — do not spawn a fresh one. A new agent re-derives everything from scratch.

Continue the previous Explore agent and check for usages in test files as well.

Worktree isolation

When an agent needs to modify files, use worktree isolation. The agent receives its own Git branch and working copy, so its changes cannot conflict with your current work:

Start an agent with worktree isolation to refactor the auth module.
Return the branch name when done so I can review the diff.

If the agent makes no changes, the worktree is cleaned up automatically. If it does make changes, the branch name and path are returned so you can inspect and merge.

Setting a model per agent

Every agent can run on a different Claude model. By default an agent inherits the model of the parent session, but you can override it per spawn. This is the fastest way to cut costs without changing how your team is structured.

Available models, from lightest to most capable:

Model	Alias	Best for
Claude Haiku 4.5	`haiku`	Mechanical tasks — file retrieval, grep-and-return, data extraction, formatting
Claude Sonnet 4.6	`sonnet`	Balanced default — writing code, moderate reasoning, multi-step searches
Claude Opus 4.8	`opus`	Deep reasoning — architecture decisions, complex debugging, nuanced judgment
Claude Fable 5	`fable`	Long narrative or creative generation tasks

To set the model, specify it in your request:

Spawn a Haiku Explore agent to find all files that import the AuthService class.
Return only the file paths.

The Scout pattern

A Scout agent is a Haiku-powered Explore or general-purpose agent whose only job is to retrieve data and return it verbatim — no analysis, no reasoning, just fetching. Use it when the task is purely mechanical:

Listing files matching a pattern
Reading a config file and returning its contents
Collecting function signatures from a module
Checking whether a file or symbol exists

Because Haiku is significantly cheaper per token than Sonnet or Opus, running five Scout agents in parallel to gather data costs a fraction of what a single Sonnet agent doing the same work would. Once the data is back in the parent session, the smarter model can reason about it.

Example — Scout agents feeding a planning step:

Run three Haiku Explore agents in parallel:

1. List every file under src/auth/ — return paths only.
2. Find all usages of verifyToken() — return file and line number only.
3. Read the contents of src/lib/session.js and return them verbatim.

When all three are done, I will plan the changes needed.

The planning and reasoning happen once, in the parent session, using whatever model the parent runs. The cheap part — the data retrieval — is offloaded to Haiku.

When to reach for Opus

Opus costs more per token but produces meaningfully better output for tasks that need deep reasoning or careful judgment. Use it for agents that:

Design or critique architecture
Debug a subtle, non-obvious failure
Review a complex diff for security issues
Produce prose (a spec, a post-mortem) that will be read by others

Running one Opus agent for a focused high-stakes task and several Haiku agents for surrounding data collection is the highest-leverage mix.

Model selection at a glance

Data retrieval, file listing, pattern matching  →  Haiku
Code writing, standard research, multi-step work  →  Sonnet (default)
Architecture, complex debugging, critical review  →  Opus

Reducing token consumption

The agent team is the most powerful lever for keeping token costs low in long sessions.

Why it works: When you send an Explore agent to scan 40 files, that scan — all the tool calls, partial reads, and dead ends — stays in the agent's context window, not yours. You receive only the summary.

Practical tips

Delegate exploration early. If a task requires reading many files before you know which ones matter, spawn an Explore agent upfront. Ask it to report only the most relevant findings, not raw file contents.

Ask for short reports. End agent prompts with an output constraint: "Report in under 150 words" or "Return only file paths and line numbers." Tight summaries cost less when returned to the parent.

Run independent questions in parallel. Two unrelated lookups that run as parallel background agents finish faster and neither one touches the main context. Running them sequentially in the parent window costs time and context.

Avoid agents for small lookups. A single Grep or Read inline is cheaper than spawning an agent. Reserve agents for genuinely multi-step work or when context isolation matters.

Instruct agents to summarize, not quote. Say "Return a concise summary — do not include raw file contents." Agents that paste large excerpts back inflate the parent's context just as much as inline search would.

Match the model to the task. Use Haiku for Scout agents that only retrieve files, list paths, or extract data. Reserve Sonnet or Opus for agents that need to reason, write, or judge. Running five Haiku Scout agents in parallel costs less than one Sonnet agent doing the same mechanical work sequentially.

Use background for slow tasks. A test run that takes two minutes does not need to block the conversation. Run it in the background, keep working, and let the notification re-invoke you when the result is ready.

Example: parallel research before a change

Before I change how sessions are stored, run two background agents:

1. (Explore agent, medium) Find every file that imports or references the Session class.
   Report only the file paths and line numbers — no context.

2. (general-purpose agent) Search GitHub issues for anything mentioning "session expiry"
   or "auth token". Return a one-paragraph summary.

Notify me when both are done.

Both agents run simultaneously. You receive two short summaries. The main session grew by two short messages instead of by a full codebase scan and a web-search loop.

Common mistakes

Spawning a fresh agent instead of continuing. If the previous agent explored the codebase and accumulated context you need, starting a new one discards that work. Use SendMessage with the existing agent's ID for follow-ups.

Forgetting agents start cold. Agents do not inherit the parent conversation. Always include the relevant background in the prompt — the problem statement, relevant file names, the decision already made — anything the agent needs to do the job.

Writing an overly broad prompt. "Understand the whole codebase and tell me what is important" produces a large, unfocused result. Narrow the scope: one question, one area, one concrete output.

Spawning agents for one-call tasks. If the answer requires a single Grep, run it inline. The agent overhead is only worth it when the task spans multiple files, multiple rounds, or when context isolation is the point.

Writing a vague agent description. The description field in your agent file is what Claude Code uses to decide when to invoke that agent. "Helps with code" will never be matched. Write trigger conditions: "Use when asked to write or refactor code — hand it a specific file or feature, never open-ended questions."