TopolearnSubagents keep noisy research and verification out of your main context and let you enforce narrower permissions.
A subagent is a helper Claude starts for a sub-task. It runs in its own context window with its own system prompt, tool list and permissions. When it finishes, only its summary returns to your conversation. That makes subagents the main tool for keeping the main context clean: a search across 200 files happens inside the subagent, and you get back five lines.
Claude Code has built-in subagents, including Explore (fast, read-only codebase search), Plan (used in plan mode to research) and a general-purpose one. Claude delegates to them on its own, and you can ask directly: "use subagents to investigate how token refresh works and whether we already have OAuth helpers".
You can define your own as markdown files with frontmatter:
.claude/agents/<name>.mdfor the project,~/.claude/agents/<name>.mdfor you everywhere,- required fields:
nameanddescription(when Claude should delegate to it; "use proactively" encourages automatic use), - optional:
tools(restrict to, say, read-only tools),model(haikufor cheap tasks,opusfor deep review, orinherit),permissionMode,maxTurnsand more.
The body is the subagent's system prompt. Invoke one by description match, by name ("use the security-reviewer subagent"), or by @-mentioning it. claude --agent <name> runs a whole session as that agent.
Good uses: codebase research, running and summarizing test suites, reviewing a diff with fresh eyes (a reviewer that did not write the code is less biased), and domain checks like security review. Remember each subagent's own work still uses tokens, and subagents cannot see your conversation unless you pass the details in the request.
Example
---
name: security-reviewer
description: Reviews diffs for security problems. Use proactively after changes to auth, payments or input handling.
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review the changes for:
- injection (SQL, command, XSS) and unsafe deserialization
- authentication and authorization flaws
- secrets or credentials in code or logs
Report each finding with file:line, severity and a concrete fix.
Report only real risks, not style.
# saved as .claude/agents/security-reviewer.md
# use: "use the security-reviewer subagent on the current diff"Remember
- Subagents run in their own context and return only a summary
- Define them in .claude/agents/*.md with name, description, tools and model
- Use them for research, test runs and unbiased review
Watch out for
- Assuming a subagent knows what you discussed earlier; it starts fresh, so include the needed details in the delegation.