Claude Code Subagents and Agent Teams: A Practical Guide

You've seen the words "subagents," "Agent Teams," "orchestration," and you wonder if you're missing something. Short answer: for most of your tasks, no. But on big work, yes, and it's worth understanding.

Let's untangle it without the jargon.

What a subagent actually is

A subagent is a specialized assistant with its own context, its own prompt, and its own tool permissions.

When the main agent hits a well-defined subtask, it delegates it to a subagent. That subagent works in its own context window, does its job, and returns just the result. The main agent doesn't get its full history polluting its context, it gets the conclusion.

That's the point: keep the main agent's context clean. Instead of one agent drowning in 50,000 tokens of file search, you have a subagent that does the search and reports back three useful lines.

You declare your subagents in your project's .claude/agents/ folder. Each has a name, a description that says when to use it, and a system prompt.

---
name: test-writer
description: Use when tests need to be written or fixed
---
You write tests. You aim for edge-case coverage,
not the happy path. You never touch production code.

Agent Teams, the next step up

Agent Teams is the multi-agent orchestrator built into Claude Code. Still experimental, disabled by default, but a solid entry point.

The idea: a lead agent splits a big task, delegates each piece to a specialist agent (with its own model, prompts, tools), the specialists work in parallel on a shared file system, and the results flow back to the lead.

If "delegate to a specialist" sounds like subagents, that's normal. Agent Teams is that idea pushed all the way to running several agents truly in parallel, not just one after another.

Beyond the built-in one, there are third-party orchestrators like Multiclaude and Gas Town. They're opinionated, which is what makes them good starting points when you begin: they decide for you until you've built your own habits.

When you need it (and when you don't)

Let's be clear: multi-agent orchestration is pointless for 95% of agent-assisted tasks. For most of your daily work, a single agent is faster and simpler.

Right now, multi-agent is still an expensive and experimental way to attack large projects.

You need it when:

• The project splits into genuinely independent pieces that touch different files.
• A single context window can't hold the whole thing.
• You want to parallelize a broad refactor or a repo-wide migration.

You don't need it for a bug fix, a focused feature, or anything that fits in one head.

The trap is spinning up a ten-agent "team" for something one agent would do in five minutes. You pay in tokens and complexity for a parallelism the task never asked for.

The real problem: visibility

Here's what doesn't get talked about enough. The moment you run several subagents or an Agent Team, you lose the thread.

A lead delegates to five specialists. Which one is working? Which finished? Which is waiting on a decision? In a terminal you see a wall of scrolling text, and you can't tell who's doing what.

This is where a visual dashboard changes everything. AgentsRoom shows each agent and each subagent as its own tile, with its status spelled out. You watch the delegation happen, you see who's waiting on your reply, you see who crashed. The wall of text becomes a readable map.

Without that view, multi-agent orchestration stays an impressive demo that's unmanageable day to day. With it, it becomes a tool you actually use.

Where to start

Don't jump straight to an eight-agent team.

Start with one or two subagents for precise, repetitive tasks: one that writes tests, one that searches the codebase. You'll quickly feel the gain on your main agent's context.

Once that mechanic feels natural, turn on Agent Teams for work that splits cleanly. Keep an eye on who's doing what, approve plans before execution, and stop the moment review becomes your bottleneck.

Multi-agent rewards the people who structure before they launch. Not the ones who launch the most agents.