Agents
A single Claude Code session reads, thinks, and acts in sequence. One thing at a time.
An agent is a Claude session you delegate to — it runs its own loop, in its own context, and returns a result. Agents let you parallelize work that would otherwise run serially, and isolate complex tasks so they don't consume your main session's context.
Three Modes
Single session — you and Claude in one conversation. Best for most work. Context is shared, decisions are visible, you stay in control.
Subagents — you delegate a task from your session. The subagent runs in its own context, completes the work, and returns a summary. The subagent's details don't bloat your session. Use subagents for research, file scanning, code review — anything with a clear input and output that you don't need to watch step-by-step.
Agent teams — multiple subagents running in parallel, coordinating through shared tasks or a message channel. An orchestrator subagent assigns work, specialist subagents execute, results flow back. Use agent teams for large parallel workloads: scanning a codebase while generating a report while running tests.
When to Delegate
| Situation | Mode |
|---|---|
| Normal work — edit, write, review | Single session |
| One large task you want isolated | Subagent |
| Repetitive work across many files | Subagent (or loop) |
| Multiple independent tasks in parallel | Agent team |
| Codebase exploration + report generation simultaneously | Agent team |
The signal to delegate: if you catch yourself thinking "I wish I could do X while Claude does Y," that's a subagent.
Subagent Mechanics
In Claude Code, you can ask Claude to delegate work in any prompt. The Agent tool creates a new session. You give it a clear task and the files or context it needs. It runs. You get a result.
The Claude Code deep dive covers the full pattern: how to write a good delegation prompt, how to scope context, and how agent teams coordinate through shared task lists.
The Tradeoff
More agents mean more parallelism and less context bloat. They also mean more complexity — coordinating results, handling failures, maintaining coherent state.
Start with a single session. Add a subagent when you hit a clear bottleneck. Add coordination structure only when you need it.
Context
- Claude Code — detailed coverage of subagents, agent teams, and hooks in the Claude Code loop
- Skills — the complement to agents: skills handle repeatable workflows, agents handle parallel delegation
- Config Architecture — how multi-agent setups are configured
- Onboarding — start here before thinking about agents
- MCP Servers — how agents connect to external tools and services
Questions
At what point does the overhead of coordinating agents cost more than the parallelism gains — and how would you know you've crossed that line?
- What's the clearest single task in your current workflow that would benefit from running in isolation while you do something else?
- How do you write a subagent prompt that gives the agent enough context to succeed without copying your entire session history into it?
- If an agent team is a small business with an orchestrator and specialists, what does good organizational design look like at the agent level?