Claude Code subagents explained: when to split work on a website project

A subagent is a helper that Claude Code starts to handle one piece of a task in its own separate workspace, then reports back with a summary. Anthropic defines it as "a specialized AI assistant that runs in its own context window with a custom system prompt, specific tool access, and independent permissions." Your main conversation sees the result, not the hundreds of files or log lines the helper read to get there.

On a website project, that is useful in two situations: when a side job would flood your session with output (crawling every page, reading build logs, searching a large theme), and when you want a second, independent look at a change before it ships. This guide covers the built-in subagents as of October 2026, when splitting work helps and when it doesn't, how to write review and audit subagents for a site, and what they cost.

What a subagent is, in plain terms

Think of your main Claude Code session as the person running the project. When a job is self-contained, such as "find every page that still mentions the old phone number," Claude can hand it to a subagent. The subagent gets its own system prompt, its own tool permissions and a short brief that Claude writes. It does the searching, then returns only what matters.

The reason this matters is context. The context window is the session's working memory, and it fills up fast on a big site. Anthropic's docs recommend a subagent "when a side task would flood your main conversation with search results, logs, or file contents you won't reference again." For how context fills and what compaction does, see context, compaction and memory files.

Subagents work inside one session. For running several independent sessions side by side, Claude Code has other features, such as background sessions and worktrees.

The built-in subagents

Claude uses these on its own when a task fits. Each inherits the main conversation's permission rules.

There are also helpers Claude uses automatically for specific jobs, such as answering questions about Claude Code itself. One detail matters for website teams: Explore and Plan start without your CLAUDE.md files and git status, to stay fast. Your project rules don't reach them. Other built-in and custom subagents do load CLAUDE.md. If a rule must reach a subagent, restate it in your request. Plan mode itself is covered in plan mode for website work.

When to split work, and when not to

Anthropic's docs give a clear split, summarized here:

Website jobs that suit a subagent: auditing every template for heading structure, checking all internal links after a URL change, reading a long build log to find the one real error, comparing old and new versions of pages after a migration, and reviewing a finished diff. You can ask in plain language: Use a subagent to check every page in /services/ for a missing meta description and report only the failures.

Claude can also run several subagents in parallel on independent questions, then combine their findings. Anthropic warns that "running many subagents that each return detailed results can consume significant context," so ask for short reports.

Writing a custom subagent for site review

A custom subagent is a Markdown file with YAML settings at the top and its instructions below. Save project subagents in .claude/agents/ and commit them so the team shares them. Here is a short example of a read-only page auditor:

---
name: page-auditor
description: Audits changed pages for SEO and accessibility basics. Use after page content or templates change.
tools: Read, Grep, Glob
model: sonnet
---
You review pages, you never edit them. For each changed page, check: one H1, a unique title, a meta description, image alt text, and a self-referencing canonical. Report a table of failures by file. Say "no issues" if there are none.

The fields worth knowing:

• description tells Claude when to delegate. Adding "use proactively" encourages Claude to delegate without being asked.
• tools is an allowlist; disallowedTools is a denylist. Leave out tools and the subagent inherits everything.
• model picks the model, for example sonnet, opus, haiku or inherit.
• skills preloads skills, such as your SEO checklist, into the subagent at startup. See Claude Code skills explained.
• memory gives the subagent its own notes folder across sessions; project scope keeps it in .claude/agent-memory/ where the team can review it in git.
• isolation: worktree runs the subagent in a temporary git worktree, a separate copy of the repository, so its edits don't touch your working files.

Two cautions. Claude Code ignores misspelled field names without an error, and a disallowedTools entry like Bash(git push *) removes the whole Bash tool, not just pushes. To block specific commands, use a deny rule in your permission settings instead, which applies to the main conversation and subagents alike.

Running subagents: asking, mentioning and background work

There are three ways to get a specific subagent to run, from lightest to strongest:

1. Name it in your request: "Have the page-auditor subagent look at my changes." Claude decides whether to delegate.
2. @-mention it: type @ and pick it from the list. This guarantees that subagent runs for that task.
3. Run the whole session as it: start with claude --agent page-auditor, and the main session takes on its tool limits and model.

In interactive sessions, subagents usually run in the background while you keep working. If one needs permission for a tool call, the prompt appears in your main session and names the subagent asking. Answer carefully: a grant that lasts for the session applies to the whole session, not just that subagent. Run /tasks to see background work, including finished subagents.

You can also fork the conversation with /subtask (Claude Code v2.1.212 or later), and in interactive sessions Claude can start forks itself, because fork mode is on by default. A fork is a subagent that inherits the whole conversation so far, so you don't have to re-explain the situation. Because it shares the main session's prompt cache, Anthropic says it "costs less than a fresh subagent for tasks that need the same context."

The /agents command now prints a reminder to ask Claude or edit the agents folders directly; on versions before v2.1.198 it opened an interactive manager.

Review subagents: a second opinion before anything ships

The most valuable subagent on a website is often a reviewer. Anthropic's best-practices page recommends it: "Before treating a task as done, have a subagent review the diff in a fresh context and report gaps." A reviewer in a fresh context "sees only the diff and the criteria you give it, not the reasoning that produced the change."

Built-in options already use this pattern. /code-review reviews the current diff for bugs in a fresh subagent, and /simplify runs four review agents in parallel to look for cleanup, not bugs. For your own criteria, write the review request yourself, for example: Use a subagent to review this diff against the redirect plan. Check that every old URL has one 301 to a live page, no chains, and nothing outside the plan changed. Report gaps only.

A subagent review is a check, not an approval. It can miss things, and it reads the same files a person would. On eseospace.com, as our rebuild case study describes, one script's "already processed?" check matched a class name that also appeared in a stylesheet it added, so after one run it silently skipped every page. The lessons we wrote down: read the counts, and check the second page a script produces, not just the first. More examples are in common Claude Code mistakes on websites. A person still reads the diff and approves the deploy.

Cost and context trade-offs

Subagents save context in your main conversation, but they do not save usage. Each subagent "sends its own requests, which count toward the same usage limits as your main conversation." A few ways to keep that in check:

• Pick a smaller model for simple jobs. Anthropic's costs page suggests model: haiku for simple subagent tasks. A switch to Opus in your session also applies to subagents that inherit your model.
• Ask for short reports. Results return to your main conversation, so a 2,000-line report defeats the purpose.
• Watch the attribution. On a paid plan, /usage breaks down recent usage by skills, subagents, plugins and MCP servers.
• Know the defaults. Subagents can nest up to three layers deep, and spawning stops when 20 are running at once.

Two heavier features build on subagents. /batch splits a large change into 5 to 30 units and runs one background subagent per unit, each in its own worktree. Agent teams coordinate whole Claude Code sessions; Anthropic says they "use approximately 7x more tokens than standard sessions when teammates run in plan mode," and they are experimental and off by default. For budgeting, see keeping Claude Code usage and costs under control.

Safety: what subagents can and can't reach

A subagent inherits your permission rules, and if your main session runs in auto mode or accept-edits mode, the subagent runs in that same mode regardless of its own permissionMode setting. So the protection comes from your settings and the subagent's tool list, not from the subagent's good intentions. Keep audit subagents read-only, and give edit access only to subagents working on a branch or in a worktree.

Subagents that read web pages or third-party files can pick up prompt injection, meaning hidden instructions in content. Claude Code scans each subagent's final report for text that imitates its own messages or mentions permission settings, and marks it (v2.1.210 or later). Anthropic says the scan "isn't a substitute for restricting what a subagent can reach." Subagents can also ship inside plugins, where they don't support the hooks, mcpServers or permissionMode fields. The full reference is Anthropic's subagents documentation.

Conclusion

Subagents keep big, noisy jobs out of your main session and give you an independent second look at finished work. Use them for crawls, audits, log reading and diff reviews; keep conversational editing in the main session; make reviewers read-only; and remember that each one draws on your usage. If you want help setting up review subagents, permissions and a deploy process for your team, that is part of our Claude Code consulting, and our guide to Claude Code for technical SEO shows the audits worth delegating. More guides are in our Claude Code Guide.

Frequently asked questions