Your team has one repository and a growing list of repeated chores: reviewing pull requests against the same checklist, writing tests for new modules, and scanning diffs for security issues. One developer has a handy subagent on their laptop, another has a slightly different version, and nobody knows which one reflects the team's standards. The result is inconsistent output and prompts that live in private notes.
This guide goes beyond a quick answer by walking through the setup in order, so a team can reproduce it rather than each person improvising. It covers:
- how to decide which tasks deserve their own subagent
- how to write clear role definitions and limit what each one can do
- how to share configurations so everyone works from the same version
- how to review and adjust subagents as the team's needs change
What users report
Users in the r/ClaudeCode community describe two overlapping setups: plain subagents that the main session delegates to, and the experimental agent teams feature. Most agree that subagents are the easier starting point, and that teams add control at the cost of setup friction.
What works
- Delegation can be as simple as asking. One user says you can ask Claude to delegate to parallel subagents, and that this keeps the main agent's context window cleaner because each subagent uses its own context.
- Planning prompts benefit from subagents. Another user suggests telling Claude to use a subagent, and optionally to use Haiku, for a concise planning answer. To the person that recommended using sub shows that thread.
- One user finds agent teams neat for large tasks, and notes that unlike subagents you can message teammates midway or stop them to correct course.
What goes wrong
- Token use rises. A user warns that parallel subagents burn through tokens faster, partly because they sometimes need overlapping context.
- Agent teams need an opt-in. Users enabled them by setting an environment flag in settings.json, and Introducing agent teams (research preview) includes replies from people who could not get it working.
- Nesting is limited. A user reports that team agents currently cannot spawn their own subagents.
Tips shared
- Update Claude Code first, add
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSset to1underenvin~/.claude/settings.json, then restart the terminal, as laid out in How to Set Up Claude Code Agent. - Ask explicitly for a team in your prompt, and launch with
claude --teammate-mode tmuxto see panes per teammate. - Think of the main session as an orchestrator and subagents as individual roles on an engineering team, as forum users put it.
What Are Claude Code Subagents?
Subagents in Claude Code are specialized assistants that the main Claude Code session can hand tasks to. Each one has its own instructions, its own context window, and a defined set of tools, so it can focus on one kind of job without cluttering the main conversation.
They are typically defined as Markdown files with a short configuration header, which means a team can keep them in a repository and version them like any other project file. That is what makes claude code subagents practical for shared workflows rather than just personal experiments.
Why teams use them
A team usually wants consistent behavior, not a different setup on every laptop. Subagents let you write down how a recurring task should be handled once, then reuse it across people and projects.
Common roles include:
- Code reviewer: checks changes against your team's standards.
- Test writer: drafts and runs tests for new code.
- Debugger: investigates failures and proposes fixes.
- Researcher: explores unfamiliar parts of a codebase and reports back a summary.
Benefits for project execution
- Cleaner context: detailed work happens in the subagent's own context, so the main session stays focused on the larger goal.
- Consistency: shared definitions mean reviews, tests, and debugging follow the same approach.
- Tighter permissions: each subagent can be limited to the tools it needs, which reduces the chance of unintended actions.
- Division of labor: separate tasks can be delegated instead of handled in one long, crowded thread.
The sections below cover how to define these subagents and share them across a team.
How to Set Up Subagent Model in Claude Code?
To set up a subagent model in Claude Code, follow these steps to ensure a smooth configuration process. This guide will help you navigate the setup, configuration settings, and common pitfalls to avoid.
Step-by-Step Setup Process
- Access the Claude Code Interface: Begin by logging into your Claude Code account and navigating to the subagent setup section.
- Create a New Subagent: Click on the option to create a new subagent. You will be prompted to enter specific details about the subagent's role and capabilities.
- Define Configuration Settings: Set the parameters for the subagent, including its task assignments, communication preferences, and any limitations on its operations.
- Test the Subagent: Once set up, run a test to ensure the subagent is functioning as intended. This may involve simulating tasks to verify its responses and performance.
- Deploy the Subagent: After successful testing, deploy the subagent within your team’s workflow. Monitor its performance and make adjustments as necessary.
Configuration Settings
When configuring your subagent, consider the following settings:
- Role Assignment: Clearly define the responsibilities of the subagent to avoid overlap with other team members.
- Communication Protocols: Establish how the subagent will communicate with team members and other systems.
- Performance Metrics: Set benchmarks to evaluate the subagent's effectiveness over time.
Common Pitfalls to Avoid
- Overloading the Subagent: Avoid assigning too many tasks to a single subagent, which can lead to performance issues.
- Neglecting Testing: Skipping the testing phase can result in deploying a subagent that does not meet your needs.
- Ignoring Feedback: Regularly collect feedback from team members about the subagent's performance to make necessary adjustments.
For additional resources, you can utilize the Subagent Generator tool to assist in the setup process.
How Do I Set Up Multi-Agent Teams in Claude Code?
Create a set of subagents, each with one narrow job, then let the main Claude Code session delegate work to them. Each subagent is defined as a Markdown file with a name, a description and a system prompt, stored in a project folder so the whole team shares the same definitions.
Create the team
Start with the /agents command inside Claude Code, which lets you create and edit subagents interactively. You can also write the files by hand in a .claude/agents/ directory in your repository. Committing that folder to version control means every developer works with the same team of claude code agents.
Keep the first team small. Two to four agents is easier to reason about than a dozen overlapping ones.
Assign roles and responsibilities
Give each agent a single responsibility and write the description so the main session knows when to call it. Limit the tools each agent can use to what its role needs.
| Role | Responsibility | Suggested tool access |
|---|---|---|
| Code reviewer | Check diffs for bugs and style | Read-only |
| Test writer | Add and run tests | Read, edit, shell |
| Researcher | Explore the codebase and summarize | Read-only |
| Refactorer | Make scoped code changes | Read, edit |
Read-only roles reduce the risk of unwanted edits, and clear boundaries prevent two agents from changing the same files.
Manage team dynamics
A few habits keep a multi-agent setup predictable:
- Let the main session coordinate. It decides which agent handles each task and combines the results.
- Write precise descriptions. Vague ones lead to the wrong agent being chosen or none at all.
- Pass context explicitly. Subagents work in their own context, so include the files, goals and constraints they need in the task.
- Chain agents deliberately. For example, have a researcher summarize first, then hand that summary to a refactorer.
- Review and refine. If an agent drifts from its role, tighten its prompt rather than adding another agent.
Treat the agent files like code: review changes to them and update them as your workflow evolves.
How Does Claude Code Handle Subagents?
Claude Code handles subagents as specialized assistants that take on a specific task, work in their own separate context, and return a result to the main session. The main session delegates the work, so its own conversation stays focused on the larger goal.
This matters for teams because each subagent can be given a narrow role and its own instructions, which keeps behavior predictable and repeatable.
Overview of subagent management
Subagents are typically defined as configuration files that describe the agent's purpose, its instructions, and the tools it may use. Because these definitions are plain files, they can be stored alongside a project and shared through version control like any other team resource.
Management usually comes down to a few decisions:
- Scope: which tasks the subagent should take, and which it should leave alone.
- Instructions: a clear description so the main session knows when to delegate.
- Tool access: limiting each subagent to the tools its role requires.
- Ownership: agreeing who reviews and updates shared definitions.
Integration with Claude Code features
Subagents work inside the same environment as the rest of Claude Code, so they operate on the same codebase and follow the project's conventions. Restricting tool permissions per subagent lets a team separate read-only roles, such as review, from roles that edit files.
Since each subagent uses a separate context, long investigations do not crowd the main conversation. Only the summary comes back.
Examples of effective subagent use
Subagents tend to work best on well-bounded, repeatable jobs:
| Use case | Why it fits |
|---|---|
| Code review | A read-only role with a consistent checklist |
| Test writing | A focused task with clear success criteria |
| Codebase research | Heavy file reading kept out of the main context |
| Debugging | Isolated investigation that reports back findings |
Broad, ambiguous tasks are a weaker fit. Teams generally get more reliable results by starting with one or two narrow subagents and refining their instructions over time.
Best Practices for Using Claude Code Subagents
To optimize the use of Claude Code subagents, it's crucial to implement effective communication strategies within teams. Regular updates and feedback loops can help ensure that all team members are aligned on goals and expectations. Utilizing collaborative tools can facilitate discussions and streamline information sharing, making it easier to coordinate efforts across different subagents.
Monitoring and evaluating subagent performance is another essential practice. Establish clear metrics to assess how well each subagent is meeting its objectives. Regular performance reviews can help identify areas for improvement, and adapting strategies based on these evaluations can enhance overall productivity. Consider using analytics tools to gather data on subagent interactions and outcomes, allowing for informed decision-making.
Iterating on subagent roles is also vital for maintaining efficiency. As projects evolve, the needs of the team may change, necessitating adjustments to subagent responsibilities. Regularly reassess each subagent's role to ensure it aligns with current project goals. This flexibility can lead to the best Claude Code subagents being utilized effectively, maximizing their impact on team performance.
By focusing on these best practices, teams can enhance their collaboration and ensure that Claude Code subagents contribute effectively to achieving their objectives.
How Agentsforce Can Help You Set Up Claude Code Subagents
Agentsforce gives you a ready-made team of specialists for Claude Code, so you don't have to write each subagent's role and instructions from scratch. It is one way to shortcut the setup work described above, especially if your team needs several roles at once.
Agentsforce: Claude Code, fully staffed provides specialists including developers, marketers, and experts in WordPress and Shopify. The aim is to streamline project execution by giving each kind of task a dedicated specialist.
What this means for a team setup
- Less configuration work: specialists already exist for common roles, so you can skip drafting every role definition yourself.
- Clear division of labor: developer, marketing, WordPress, and Shopify tasks each map to a specialist.
- Shared starting point: everyone on the team can work from the same set of specialists instead of building personal variations.
Integration with Claude Code
Agentsforce requires no new app and no new habits. It integrates with Claude Code, so your team keeps working in the environment it already uses.
Cost
Access is a one-time payment of $49 for lifetime access to all specialists and updates. That removes recurring subscription math when you are budgeting for a team.
If you prefer full control, the manual setup steps earlier in this article still apply. A pre-built set of specialists simply gives you a faster starting point, which you can then adapt to your own workflows and conventions.
Related articles
Frequently asked questions
How do I create a subagent in Claude Code?
You create a subagent by describing the role you want it to fill and using the Subagent Generator tool. Start with a narrow, clearly defined job, such as code review or test writing. A focused description makes the subagent easier to reuse across a team.
What is the difference between agent teams and subagents in Claude Code?
Agent teams are made up of multiple agents working together toward a shared goal. Subagents are the specialized roles within those teams, each handling a specific type of task. In practice, you define the subagents first and then combine them into a team.
Can Claude Code automatically create subagents?
No. Claude Code does not automatically create subagents; they must be set up manually. You decide which roles you need, describe them, and add them to your workflow. This keeps the team structure deliberate and predictable.