Agent Teams: Multi-Agent Collaboration

Coordinate multiple CodeBuddy Code instances into a team, completing complex tasks through shared task lists, inter-member messaging, and centralized management.

Experimental Feature: Agent Teams is disabled by default. You can enable it via the [Experimental] Agent Teams toggle in /config, or set the environment variable CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS=1. This feature currently has known limitations.

Agent Teams lets you coordinate multiple CodeBuddy Code instances working together. One session serves as the team lead, responsible for coordinating work, assigning tasks, and aggregating results; the remaining members (teammates) work independently, each with their own context window, and communicate directly with each other through a messaging system.

Unlike Sub-agents, where sub-agents run within a single session and can only report results back to the main agent, Agent Teams members can communicate directly with each other, and you can bypass the lead to talk to any member directly.

When to Use Agent Teams

Agent Teams is most effective for tasks where parallel exploration creates real value. Typical scenarios include:

• Research and Review: Multiple members investigate different aspects of a problem simultaneously, then share and challenge each other's findings
• New Module Development: Each member is responsible for an independent module without interfering with each other
• Competitive Hypothesis Debugging: Members test different hypotheses in parallel, converging on the correct answer faster
• Cross-layer Coordination: Frontend, backend, and testing are each handled by different members, progressing in sync

Agent Teams introduces additional coordination overhead, and token consumption is significantly higher than single-session. It works best when members can work independently. For sequential tasks, same-file edits, or work with complex dependencies, single-session or sub-agents are more appropriate.

Comparison with Sub-agents

	Sub-agents	Agent Teams
Context	Independent context window, results returned to caller	Independent context window, fully independent
Communication	Can only report results to the main agent	Members can send messages directly to each other
Coordination	Main agent manages all work	Shared task list, members claim tasks autonomously
Use Cases	Focused tasks where only the final result matters	Complex work requiring discussion and collaboration
Token Consumption	Lower: results summarized back to main context	Higher: each member is an independent instance

In short: use sub-agents for independent subtasks that need quick execution, use Agent Teams for complex tasks that require communication and coordination between members.

Enabling Agent Teams

Agent Teams is disabled by default. There are two ways to enable it:

Method 1: Via /config Toggle (Recommended)

In an interactive session, type /config, find the [Experimental] Agent Teams option, and press Enter to toggle it to true.

Method 2: Via Environment Variable

export CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS=1

You can also set it in settings.json:

{
  "env": {
    "CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Or use the configuration option directly:

{
  "agentTeam": {
    "enabled": true
  }
}

Creating Your First Team

Once enabled, tell CodeBuddy in natural language what kind of team you want. CodeBuddy will automatically create the team, generate members, and assign tasks based on your description.

I'm designing a CLI tool to help developers track TODO comments in code.
Create a team to explore this problem from different angles: one for UX design,
one for technical architecture, and one as a "devil's advocate" to raise challenges.

CodeBuddy will:

1. Create the team and shared task list
2. Generate independent members for each role
3. Coordinate each member's work
4. Aggregate the final results

After the team is created, the terminal will display all members and their current status. You can talk directly to any member using @member-name.

Interface After Team Creation

After successful creation, you'll see something like:

Team design-review created

The lead then generates members via the Task tool, each displayed as @member-name · description with a distinct color identifier.

Controlling Your Team

Tell the lead your intentions in natural language, and it will handle team coordination, task assignment, and work delegation.

Interacting with Members

You can talk directly to any member without going through the lead.

@mention completion: Type @ in the input box to trigger Tab auto-completion for member names. Fuzzy search is supported—typing a partial name will match. The dropdown menu displays names in each member's assigned color, with status annotations (e.g., ✓ completed). Select a member and type your message to send directly.

@all broadcast: Type @all to send a message to all members simultaneously, equivalent to a broadcast. When there are more than 1 member, the @all option appears at the top of the completion list.

Tip: Members who have completed their tasks also appear in the @ completion list. Selecting a completed member and sending a message will reawaken it to continue working.

Real-time Status Bar

A team status bar is displayed below the input box, showing each member's work status:

Team (2 active) · @ux-designer ● @tech-architect ● @devils-advocate ✓

• ● indicates working
• ✓ indicates completed
• ✗ indicates failed

Each member name is rendered in their assigned color, with real-time display of token consumption and tool call counts. When the completion dropdown is open, the status bar automatically hides to avoid obstruction.

Specifying Members and Models

CodeBuddy automatically decides how many members to generate based on the task, but you can also specify explicitly:

Create a 4-person team to refactor these modules in parallel, each member using the lite model.

Requiring Plans Before Implementation

For complex or high-risk tasks, you can require members to submit plans before implementation:

Generate an architect member to refactor the authentication module, requiring a plan submission for approval before modifying code.

After completing the plan, the member sends a plan approval request to the lead. The lead reviews and approves or rejects (with feedback). Rejected members stay in plan mode, revise, and resubmit.

Delegate Mode

By default, the lead may implement tasks itself rather than waiting for members to finish. Press Shift+Tab to switch to Delegate Mode, restricting the lead to coordination tools only (generating members, sending messages, managing tasks), without directly modifying code.

This is suitable for scenarios where you want the lead to focus on task decomposition, assignment, and aggregation.

Task Assignment and Claiming

The shared task list is the core of team coordination. Tasks have three states: pending, in progress, and completed. Tasks also support dependencies: when a dependency is completed, downstream tasks are automatically unblocked.

• Lead assignment: Tell the lead which task to assign to which member
• Autonomous claiming: After completing their current task, members automatically claim the next unassigned and unblocked task from the list

Press Ctrl+T to toggle the task list display in the terminal.

Closing Members

To gracefully end a member's session:

Have the researcher member shut down

The lead sends a shutdown request, and the member can accept (graceful exit) or reject (with explanation).

Cleaning Up the Team

After work is complete, have the lead clean up team resources:

Clean up the team

This removes the shared team resource directory. All active members must be closed before cleanup, or it will fail.

Important: Always clean up the team through the lead. Members should not perform cleanup operations, as their team context may not resolve correctly.

How It Works

Team Architecture

An Agent Team consists of the following components:

Component	Purpose
Team Lead	The main session that creates the team, generates members, and coordinates work
Teammates	Independent CodeBuddy Code instances, each executing assigned tasks
Task List	A shared work list for all members, supporting claiming and status tracking
Messaging System (Mailbox)	Communication mechanism between members, supporting direct messages and broadcasts

Execution Mode

Members run in-process within the main terminal. All members share the same terminal window, and you interact with specific members via @member-name.

Context and Communication

Each member has an independent context window. When spawned, members load the same project context as a normal session (CODEBUDDY.md, MCP servers, skills, etc.) and receive the lead's initial prompt. The lead's conversation history is not passed to members.

Message Types:

Type	Purpose
message	Send a message to a specific member
broadcast	Broadcast to all members (use cautiously—token consumption scales linearly with member count)
shutdown_request	Request a member to shut down
shutdown_response	Member's response to shutdown request
plan_approval_response	Plan approval response

Auto-restart Mechanism: Members who have completed their tasks automatically restart when they receive new messages, without manual intervention. This means you can send messages to any member at any time, even if they've already finished their work.

Data Storage

Team and task data is stored locally:

• Team configuration: ~/.codebuddy/teams/{team-name}/config.json
• Member mailboxes: ~/.codebuddy/teams/{team-name}/inboxes/{member}.json
• Task lists: ~/.codebuddy/tasks/{team-name}/

Permissions

Members inherit the lead's permission settings. If the lead starts with --dangerously-skip-permissions, all members will too.

Usage Examples

Parallel Code Review

Split review criteria into independent dimensions, with each member focusing on one direction:

Create a team to review PR #142, generate three reviewers:
- One focusing on security implications
- One checking performance bottlenecks
- One verifying test coverage
Have them each review and report their findings.

Each reviewer examines the same PR from a different perspective. The lead aggregates findings after everyone completes.

Competitive Hypothesis Debugging

When the root cause is unclear, have multiple members verify different hypotheses in parallel:

Users report the app disconnects after sending a single message.
Generate 5 members to investigate different hypotheses. Have them discuss
with each other, trying to disprove each other's theories, like a scientific debate.
Update the final consensus into the troubleshooting document.

The key to this "debate" structure is overcoming anchoring bias: sequential investigation tends to be dominated by the first explanation found, while multiple independent investigators challenging each other means the surviving theory is more likely to be the true root cause.

Cross-layer Feature Development

Frontend, backend, and testing are each handled by different members:

I need to add a bulk import feature to the user management module. Create a team:
- One for backend API and database migration
- One for frontend interface and interaction
- One for writing integration tests
Have the architect member design the interface specification first, then others develop in parallel based on the spec.

Best Practices

Provide Members with Sufficient Context

Members automatically load project context but don't inherit the lead's conversation history. Include task-specific information in the initial prompt:

Generate a security reviewer with this prompt:
"Review the authentication module in the src/auth/ directory, focusing on token handling,
session management, and input validation. The app uses JWT tokens stored in httpOnly cookies.
Report findings sorted by severity level."

Set Appropriate Task Granularity

• Too small: Coordination overhead exceeds parallel benefits
• Too large: Members go too long without reporting, increasing rework risk
• Just right: Self-contained work units with clear deliverables (a function, a test file, a review report)

Tip: The lead automatically splits work into tasks and assigns them. If tasks aren't granular enough, ask the lead to split further. Keeping 5-6 tasks per member keeps everyone productive and makes it easier for the lead to reassign work when someone gets stuck.

Wait for Members to Complete

Sometimes the lead implements tasks itself rather than waiting for members. If you notice this:

Wait for your members to finish their respective tasks before continuing

Or switch directly to Delegate Mode.

Avoid File Conflicts

Two members editing the same file simultaneously will overwrite each other. When splitting work, ensure each member is responsible for a different set of files.

Check Progress Regularly

Monitor members' work progress, correct course deviations promptly, and aggregate interim results at any time. Unsupervised teams over long periods are more likely to produce waste.

Troubleshooting

Members Don't Appear

• Check the team status bar to confirm if members have been spawned and are running
• Confirm the task complexity warrants a team. CodeBuddy determines whether to generate members based on the task

Too Many Permission Requests

Members' permission requests are collected at the lead, which can be disruptive. Before spawning members, pre-approve common operations in permission settings.

Member Stops After Error

A member may stop working after encountering an error. Send additional instructions directly via @member-name, or have the lead spawn a replacement member to continue.

Lead Ends Prematurely

The lead may conclude work is done before all tasks are complete. If this happens, tell it to continue waiting, or use Delegate Mode to restrict its behavior.

Known Limitations

Agent Teams is still in the experimental stage and currently has the following limitations:

• No session recovery: /resume and /rewind do not restore members. After resuming a session, the lead may try to message members that no longer exist—simply have the lead respawn members
• Task status may lag: Members sometimes fail to mark tasks as completed in time, blocking dependent tasks. If you find tasks stuck, manually check if work is done and update the status
• Shutdown may be slow: Members finish their current request or tool call before shutting down
• One team per session: Clean up the current team before creating a new one
• No nested teams: Members cannot create their own sub-teams; only the lead can manage teams
• Lead role is fixed: The session that creates the team remains the lead for its entire lifecycle and cannot be transferred
• Permissions set at spawn time: All members inherit the lead's permission mode

Tip: CODEBUDDY.md works normally—members read CODEBUDDY.md files from their working directory. Use this to provide project-level guidance for all members.

Related Features

• Lightweight Delegation: Sub-agents spawn helper agents within a session, suitable for focused tasks that don't require inter-member coordination
• Manual Parallelism: Git worktrees allow manually running multiple CodeBuddy Code sessions without automated team coordination