Claude Code subagents. A helper reads the logs, and only the summary comes back

The nightly order import has failed again, and a developer asks Claude Code to find out why. Claude reads long logs, test output and three modules. It finds the cause, but by then the context window is full of logs nobody will look at again. This is the kind of work Claude Code subagents are for.

Without them, the next question, about something else entirely, carries all that baggage along. A subagent reads the logs in its own context, and only what it found comes back to the main conversation. We explained why a cluttered context makes answers worse in the article on long AI conversations.

What a Claude Code subagent is

Anthropic's documentation describes a subagent as a specialised assistant for one type of task. It runs in its own context window, with its own instructions, its own set of tools and its own permissions. It starts from a clean slate and doesn't see your conversation or the files Claude has already read.

It does load your CLAUDE.md files. The exceptions are the built-in Explore and Plan, which start without them to stay fast. When the subagent is done, it sends a summary back to the main conversation.

Claude Code comes with a few built-in subagents. Explore searches code quickly and can't change anything. Plan gathers information in plan mode. The general-purpose agent takes tasks that need both searching and acting.

One thing is easy to miss. A subagent sends its own requests, and they count toward the same usage limit as the main conversation. A separate context doesn't mean the work uses nothing.

How to create your own subagent

A subagent is a Markdown file with YAML frontmatter. Project subagents live in .claude/agents/, and the ones you want in all your projects go in ~/.claude/agents/. Only two fields are required, name and description. You can also limit the tools and pick a lighter model.

---
name: log-reader
description: Reads logs and test output. Returns only errors with file name and line number. Use when long logs need to be reviewed.
tools: Read, Grep, Glob
model: haiku
---

Read the logs you are given. List the errors with file and line number
and add one sentence about the likely cause.
Do not change any files.

The tools field lets this helper only read and search, and model: haiku hands the log reading to a lighter, faster model. The text below the frontmatter is its set of instructions.

The easiest way is to ask Claude to write the file. In newer versions the /agents command reminds you of exactly that, or of editing the folder by hand. Claude Code picks up a new or changed file in an existing agents folder by itself. If the folder was only created during the session, restart the session.

When Claude delegates on its own

Claude decides by itself whether to hand a task to a subagent, based on your request, the description field and the current context. That makes the description the most important line in the file. It should say in which situation to use the helper. "A helper for code" tells Claude nothing, while "use when long logs need to be reviewed" tells it exactly when.

Anthropic suggests that a phrase like "use proactively" encourages Claude to delegate more often.

You can also ask directly in plain words, for example "use the log-reader subagent on last night's logs". An @-mention with the agent's name guarantees that this exact subagent runs.

When splitting helps and when it only eats the limit

A subagent makes sense when a task produces a lot of text you don't need in the main conversation. Long logs, test output, a review of a folder full of documents.

It also helps when parts of the work don't depend on each other. Several subagents can then run in parallel, each on its own module or its own batch of documents, and Claude collects their findings.

It's useful as well when the helper should have fewer tools than the main conversation. A code reviewer that can only read won't change anything by accident.

The documentation is just as clear about when to stay in the main conversation:

• the task needs frequent back-and-forth and corrections,
• planning, implementation and testing share a lot of context,
• it's a quick, targeted change,
• speed matters, because a subagent starts from zero and first has to gather context on its own.

Many subagents at once also means a lot of limit. Each one spends its own tokens, and their long reports can clog the main context. Editing has one more catch. Changes a subagent makes to files usually don't come back with /rewind, so commit before that kind of work.

If a document review like this has to run every week with nobody at the computer, that's a job for automation, not for an AI session. Start with one subagent for reading logs or test output, with read-only tools. Once the main conversation stops drowning in output, move on to splitting bigger tasks.