Hand side tasks to Claude Code subagents

Some jobs fill a conversation with material you will never look at again: a 4,000-line log, a full test run, a search through hundreds of files. A subagent does that job in a separate conversation of its own and returns only its report. Your main conversation gets the answer, not the pile it came from.

This guide builds one subagent for reading server logs, shows what it knows when it starts, and ends with what a repository's subagents can do on your machine before you have trusted the folder.

What a subagent is

A subagent is a helper that Claude starts for one task. It has:

• its own context, which starts empty. It doesn't see your conversation, only the task Claude writes for it.
• its own instructions, written in its file.
• its own tools, which can be fewer than the main conversation has.
• its own model, which can be a cheaper one.

When it finishes, its report goes back to the main conversation, and everything it read along the way stays behind.

Claude Code comes with a few built-in subagents and uses them on its own. Explore searches and reads code without changing anything, Plan does the research in plan mode, and general-purpose takes on multi-step tasks. You write your own for jobs you repeat.

Your first subagent

Subagents are Markdown files in a .claude/agents/ folder. This one reads logs, can't change anything, and runs on Haiku, the smallest and cheapest Claude model.

---
name: log-reader
description: Reads server log files and reports what matters. Use when the user asks about errors, warnings or problems in a log.
tools: Read, Grep, Glob
model: haiku
---

You read log files and report back briefly.

Group the entries by kind of problem. For each group, give a count,
the first and last time, and one example line.
Put the problem most likely to hurt real users first.
Do not suggest fixes unless asked.
Never paste more than five log lines in total.

• name and description are required. Claude reads the description to decide when the subagent fits a request.
• tools lists the only tools it may use. Read, Grep and Glob read and find files. Without Edit, Write or Bash, it can't change anything.
• model takes haiku, sonnet, opus, fable or inherit. Leave it out and the subagent runs on the same model as your conversation.
• The body is the subagent's instructions. It replaces Claude Code's usual instructions, so say plainly what you want back.

Save it in .claude/agents/ inside a project to use it there, or in ~/.claude/agents/ to use it in every project. You can also ask Claude to write the file for you. The /agents command no longer does that since Claude Code 2.1.198. It now points you to these folders.

Then ask for it by name:

> Use the log-reader subagent to check logs/error.log and tell me what is wrong

To make sure that exact subagent runs, mention it with @agent-log-reader at the start of your request, or pick it from the list that opens when you type @.

What happened in our test

We gave it a 4,000-line nginx error log (368 KB) with a few problems mixed into the noise. The subagent ran on Haiku, as its file says, and worked with Read and Grep only. The whole file was too large for one read, so it searched it in pieces. Its report named 10 PHP-FPM connection failures as the problem that hurt visitors, and 65 requests for wp-login.php from bots.

The log itself never entered the main conversation. The main conversation read only the report, plus 60 lines of the file when it wanted to check something.

Checking was the right call. The first report accounted for 75 of the 4,000 lines and said nothing about the rest. The main conversation noticed, sent the same subagent back with a follow-up, and got counts that added up: 3,882 info lines, 75 errors and 43 warnings. The main conversation knows only what the report says, so ask for counts that must add up, and read the report as you would a colleague's.

Let Claude pick the subagent

You don't have to name it. In our test, the plain question below was enough: Claude chose log-reader from its description.

> What is going wrong in logs/error.log?

If a subagent is never picked, make its description closer to the words you use when you ask. If it's picked too often, make the description narrower.

What a subagent knows when it starts

A subagent starts with:

• its own instructions, and details such as the working folder
• the task Claude wrote for it
• your CLAUDE.md files, the same ones the main conversation loads (the built-in Explore and Plan skip them)
• the git status of the project

It does not get your conversation, the files Claude has already read, or your auto memory. If something you said earlier matters to the task, such as "ignore the vendor folder", say it again in the request.

Each subagent works in its own context window and makes its own requests, which count toward the same usage limits as your conversation. A subagent on Haiku costs less for a job like reading logs. It is not free.

Turn a subagent off

A deny rule stops Claude from using a subagent, whether it's yours or a built-in one:

{
  "permissions": {
    "deny": ["Agent(log-reader)"]
  }
}

In our test, with that rule in place, Claude never called the subagent and counted the lines itself. A deny rule for Agent alone turns off all subagents.

Subagents from someone else's repository

A project's .claude/agents/ folder comes with the repository, like its .mcp.json. The documentation says that until you trust the folder, Claude Code skips two parts of a project subagent: the hooks in its file and the MCP servers defined in its file. We saw the first one: a hook in a subagent's file did not run in a never-trusted folder.

The subagent's permission mode is a different story. A subagent file can set permissionMode, and when your session is in Manual mode (default), the subagent runs in the mode its file sets. We tested this with claude -p in Manual mode, in two folders that had never been trusted:

• A subagent with Read, Write and Edit and no permissionMode tried to write a file and was blocked: Claude requested permissions to write to ... but you haven't granted it yet.
• The same subagent with permissionMode: acceptEdits in its file wrote the file, with no prompt.
• A subagent with only Bash and permissionMode: auto ran a shell command that wrote a file, with no prompt. In auto mode, a classifier decides which commands run without asking, and it allowed this one.

That is different from "defaultMode": "auto", which Claude Code ignores in a project's settings precisely so that a repository cannot put your session in auto mode. A project subagent can, at least for its own work.

The documentation says Accept edits mode (acceptEdits) covers file edits and common file commands inside the project's folders, not elsewhere on the machine. Auto mode depends on the classifier, which judges each command.

In an interactive session in a new folder, the trust dialog comes first, so you have already said yes to the folder when a subagent's permissionMode applies. It still means a subagent can work with fewer prompts than you'd expect from Manual mode, so read the files first.

When a subagent does not show up

• Check the first line. The file must start with --- on its very first line, or Claude Code reads it as a plain document.
• Check name and description. A file without a name is treated as documentation, and one without a description is skipped. Neither shows an error in the session.
• Check the field names. They must match exactly, such as disallowedTools and permissionMode. An unknown field is ignored without an error.
• Restart after creating the folder. Claude Code watches .claude/agents/ and picks up changes within seconds, but only if the folder existed when the session started.
• To see why a file was skipped, run claude --debug and read the debug log.

Sources

• Create custom subagents, Claude Code documentation
• Configure permissions, Claude Code documentation, including "What runs before you trust a folder"
• Run Claude Code programmatically, Claude Code documentation, on --bare