Subagents, explained by monkey

Give Claude one huge job and its context window, everything it can hold in mind at once, fills up with file dumps and search results. The fuller it gets, the worse Claude works. Subagents fix that. Each one runs in its own separate context window, does one job, and sends back a summary, so your main chat stays clean.

The code reviewer, ready to paste

Make a folder called .claude/agents in your project and save this as .claude/agents/code-reviewer.md. Commit it and your whole team gets it too.

---
name: code-reviewer
description: Reviews code for bugs, security problems and readability. Use proactively after writing or changing code.
tools: Read, Glob, Grep
model: sonnet
---

You are a careful senior code reviewer. You only read code. You never edit files.

When invoked:
1. Start with the files or changes you were asked to review.
2. Read them, plus anything they call that you need in order to understand them.
3. Check for:
   - Bugs and edge cases: empty input, missing data, errors nobody handles
   - Security: secrets in code, user input that isn't checked, unsafe queries
   - Readability: unclear names, copy-pasted code, functions doing too much
   - Anything that doesn't match how the rest of the project does it

Reply with:
- Must fix: real problems, each with the file, the line and a suggested fix
- Should fix: things that will cause trouble later
- Nice to have: small polish
- Looks good: one line on what's solid

Be specific and brief. If there's nothing to fix, say so.

What each part does:

• name: what you call it. Only name and description are required.
• description: how Claude decides when to use it. The words "Use proactively" get Claude to hand it work without being asked.
• tools: Read, Glob and Grep let it read and search your code but not change anything. Leave the tools line out and it gets every tool subagents can use.
• model: sonnet runs it on Sonnet. For cheap jobs, model: haiku saves money.
• Everything under the second --- is its instructions, what it's told every time it starts.

Rather not write the file yourself? Ask Claude:

How to use it

• Ask in plain words: "Use the code-reviewer subagent to review the changes I just made."
• Type @ and pick it, or write @agent-code-reviewer, to make sure that exact one runs.
• Run a whole session as it: claude --agent code-reviewer
• Or let Claude decide. With "use proactively" in the description, Claude is nudged to call it on its own when the job fits. It's a nudge, not a guarantee, so @ it when you need it to run.

Where subagents live

• .claude/agents/ in your project: just this project. Commit it and your team gets it.
• ~/.claude/agents/: all your projects.
• Already built in: Explore (fast and read-only, for searching code), Plan (does the research during plan mode) and general-purpose (can look around and make changes).

Running lots at once

• Subagents run in the background by default, so Claude keeps working and picks up their results later. Ctrl+B sends a running task to the background.
• Ask for several at once: "Research the auth, database, and API modules in parallel using separate subagents."
• /subtask <task> starts a fork: a background helper that already knows the whole conversation, so you don't have to explain anything again. It shows up in a panel under the prompt. Press Enter to open it, or x to stop it.

Limits

• Up to 20 can run at once by default. Past that, starting another fails with "Concurrent subagent limit reached".
• A subagent can start its own subagents, up to 3 levels deep.
• Each one uses its own tokens, and they count toward your usage limits. Lots of long reports can still fill your main chat, so ask for short summaries.
• Rewind (Esc Esc) doesn't undo edits a subagent made. Use git for those.
• The built-in Explore and Plan helpers start without your CLAUDE.md.

Monkey believe in you. Now go build.

follow @nocodemonkey