Overview
Agent Teams allows you to coordinate multiple CodeBuddy Code instances into a collaborative team, completing complex tasks through shared task lists, inter-member messaging, and centralized management.
Note:
This feature currently has known limitations.
Agent Teams allows you to coordinate multiple CodeBuddy Code instances to work together. One session acts as the team lead, responsible for coordinating work, assigning tasks, and summarizing results. The remaining members (teammates) work independently, each with their own context window, and communicate directly with one another through a messaging system.
Unlike Sub-agents, which run within a single session and can only report results to the main agent, members of Agent Teams can communicate directly with each other, and you can also bypass the lead to talk directly to any member. When to Use Agent Teams
Agent Teams are most effective in tasks where parallel exploration can create real value. Typical scenarios include:
Research and review: Multiple members simultaneously investigate different aspects of a problem, then share and challenge each other's findings.
New Module Development: Each member is responsible for an independent module without interfering with others.
Competitive hypothesis debugging: Members test different hypotheses in parallel to converge on the correct answer faster.
Cross-layer coordination: Frontend, backend, and testing are each handled by different members, advancing in parallel.
Agent Teams introduce additional coordination overhead, and Token consumption is significantly higher than in a single session. They work best when members can operate independently. For sequential tasks, edits to the same file, or work with complex dependencies, a single session or sub-agents are more suitable.
Comparison with Sub-Agents
|
Context | Has an independent context window and returns results to the caller. | Independent context window, fully isolated. |
Communication | Can only report results to the main agent. | Members can directly send messages to each other. |
Coordination | The main agent manages all work. | A shared task list where members claim tasks autonomously. |
Use Cases | Focused tasks that only require the final result. | Complex work requiring discussion and collaboration |
Token Consumption | Low: Results are aggregated back to the main context. | Higher: Each member is an independent instance. |
In short: use sub-agents for independent subtasks that need to be executed quickly, and use Agent Teams for complex tasks that require communication and coordination among members.
Creating Your First Team
Use natural language to tell CodeBuddy what kind of team you want. CodeBuddy will automatically create the team, generate members, and assign tasks based on your description.
I am designing a CLI tool that helps developers track TODO comments in their code.
Create a team to explore this problem from different angles: one member is responsible for user experience design,
One is responsible for the technical architecture, and another plays the role of a "critic" to raise challenges.
CodeBuddy will:
1. Create a team and a shared task list.
2. Generate an independent member for each role.
3. Coordinate the work of each member.
4. Summarize the final results.
After the team is created, the terminal displays all members and their current status. You can directly talk to any member by using @member name.
Interface After Team Creation
After successful creation, you will see information similar to the following:
Team design-review created
Then the leader generates members through the Agent tool. Each member is displayed in the format of @member name · description and marked with a different color.
Controlling Your Team
Tell the leader your intent in natural language, and it will handle team coordination, task assignment, and work delegation.
Interacting with Members
You can directly talk to any member without going through the leader.
@Mention Completion: Enter @ in the input box to trigger Tab autocomplete for member names. Fuzzy search is supported, so entering part of a name can find matches. The dropdown menu displays names in each member's color and indicates their status (such as ✓ completed). After selecting a member, enter your message to send it directly.
@all Broadcast: Enter @all to send a message to all members at the same time, which is equivalent to broadcasting. When the number of members is greater than 1, the @all option appears at the top of the completion list.
Note:
Members that have completed their tasks also appear in the @ completion list. You can select a completed member and send a message to wake it up and resume work.
Real-Time Status Bar
A team status bar is displayed below the input box, showing the work status of each member:
Team (2 active) · @ux-designer ● @tech-architect ● @devils-advocate ✓
● indicates that the member is working.
✓ indicates that the task is completed.
✗ indicates failure.
— indicates that the task is canceled or terminated.
Each member name is rendered in its assigned color, and Token consumption and tool call counts are displayed in real time. When the completion dropdown menu is opened, the status bar is automatically hidden to avoid obstruction.
Member Focus Navigation
When the input box is empty, press ↓ to enter member switching mode, use the arrow keys to select a member, and press Enter to confirm the switch:
|
↓ | Enter member switching mode. |
←/→ | Switch selection between members. |
Enter | Confirm and switch to the view of the selected member. |
Esc | Cancel the selection and exit switching mode. |
Ctrl+O | Return to the main view (team lead). |
After focusing on a member:
The terminal displays the member's complete conversation history, real-time progress, and Token consumption.
The input box is automatically switched to a mode for sending messages to that member. You can then type directly to send a message.
Use @main to route messages back to the main agent (team leader).
Note:
Focus navigation is the most convenient way to view member work details. While @member name can only send messages, focus navigation also allows you to browse a member's conversation history and current work status.
Specifying Members and Models
CodeBuddy automatically decides how many members to generate based on the task, or you can specify the number explicitly:
Create a four-member team to refactor these modules in parallel, with each member using the lite model.
Team members and regular subagents use the same model resolution rules and match persistent configurations by subagent_type:
A model explicitly specified in the prompt belongs to the settings for this invocation and can still be uniformly overridden by CODEBUDDY_CODE_SUBAGENT_MODEL.
When no model is explicitly specified, the system considers project-level and user-global per-subagent settings, then built-in declarations, and finally inherits the team leader's primary model.
Use /agents to manage per-subagent settings, and use /model to manage the specific models corresponding to lite / reasoning.
Requiring Members to Submit Plans Before Implementation
For complex or high-risk tasks, you can require members to submit a plan before implementation:
Generate an architect member to refactor the authentication module, and require the member to submit a plan for approval before modifying any code.
After completing the plan, the member sends a plan approval request to the leader. The leader reviews it and then approves or rejects it with feedback. A rejected member remains in plan mode, revises the plan, and resubmits it.
Delegation Mode
By default, the leader may implement tasks themselves rather than waiting for members to complete them. Press Shift+Tab to switch to Delegate Mode, which limits the leader to using only coordination tools (Agent, TaskStop, SendMessage, AskUserQuestion, StructuredOutput) and prevents them from directly modifying code or reading files.
In Delegate Mode:
The leader cannot explore code, run commands, or edit files directly. All work is completed through subagents/members.
Subagents use the default permission mode (full tool access) by default and do not inherit the leader's delegation restrictions.
You can specify a permission mode for an individual subagent through the mode parameter of the Agent tool, for example, mode: "bypassPermissions".
In Delegate Mode, the fork path is not used, and standard subagents are enforced.
This is suitable for scenarios where you want the leader to focus on task breakdown, assignment, and summarization.
Task Assignment and Claiming
The shared task list is central to team coordination. Tasks have three states: Pending, In Progress, and Completed. Tasks also support dependencies: when a prerequisite task is completed, downstream tasks are automatically unblocked.
Leader Assignment: Tell the leader which task to assign to which member.
Member Self-Assignment: After completing the current task, a member automatically claims the next unassigned and unblocked task from the list.
Press Ctrl+T to toggle the display of the task list in the terminal.
Disabling a Member
To gracefully end a member's session:
Disable the researcher member.
The leader sends a shutdown request, and the member can accept it (to exit gracefully) or reject it (with an explanation).
Cleaning Up a Team
After the work is completed, have the leader clean up team resources:
This removes the shared team resource directory. Before cleaning up, disable all active members first, otherwise the operation will fail.
Note:
Always clean up the team through the leader. Members should not perform cleanup operations because their team context may not be resolved correctly.
How It Works
Team Structure
An Agent Team consists of the following components:
|
Team Lead | Main session for creating teams, generating members, and coordinating work |
Teammates | Standalone CodeBuddy Code instances that each execute assigned tasks |
Task List | A shared work list for all members that supports task claiming and status tracking |
Mailbox | Communication mechanism between members that supports direct messages and broadcasts |
Execution Mode
Members run in-process within the main terminal. All members share the same terminal window and interact with a specific member by using @member name.
Context and Communication
Each member has an independent context window. When created, the member loads the same project context as a regular session (CODEBUDDY.md, MCP servers, skills, and so on) and receives the leader's initial Prompt. The leader's conversation history is not passed to the member.
Message Type:
|
message
| Send a message to the specified member. |
broadcast
| Broadcast to all members (use with caution; Token consumption increases linearly with the number of members). |
shutdown_request
| Request members to shut down. |
shutdown_response
| A member responds to the shutdown request. |
plan_approval_response
| Plan approval response |
Automatic Restart Mechanism: A member that has completed its task is automatically restarted when it receives a new message, without manual intervention. This means you can send a message to any member at any time, even if it has already completed its work.
Data storage
Team and task data is stored locally:
Team Configuration: ~/.codebuddy/teams/{team-name}/config.json
Member Inbox: ~/.codebuddy/teams/{team-name}/inboxes/{member}.json
Task List: ~/.codebuddy/tasks/{team-name}/
Permission
A member's permission mode is determined by the following priority order:
1. Agent mode Parameter: Specifies the permission mode for an individual member, for example, Agent({ mode: "bypassPermissions" }).
2. CLI --subagent-permission-mode: The default permission for all subagents in this session.
3. Environment Variable CODEBUDDY_SUBAGENT_PERMISSION_MODE: Process-level override
4. Settings permissions.subagentPermissionMode: Global or project-level configuration
5. Inherit Main session: Inherits the leader's permission mode by default. However, delegation mode is not inherited, and the subagent uses default.
Special Rules for Delegation Mode: Tool restrictions in delegation mode apply only to the leader. Subagents and members use the default permission (full tool access) by default because they need full capabilities to perform the actual work.
Example Usage Scenarios
Parallel Code Review
Split the review criteria into independent dimensions, with each member focusing on one area:
Create a team review for PR
- One focuses on security impact.
- One checks for performance bottlenecks.
- One verifies test coverage.
Have them review independently and report their findings.
Each reviewer examines the same PR from a different perspective. The leader consolidates the findings after all reviewers have completed their reviews.
Competitive Hypothesis Debugging
When the root cause is unclear, have multiple members validate different hypotheses in parallel:
Users reported that the application disconnected after sending a message.
Generate five members to investigate different hypotheses separately. Have them discuss with each other,
Attempt to refute each other's theories, as in a scientific debate.
Update the final consensus in the troubleshooting document.
The key to this "debate" structure lies in overcoming anchoring bias: sequential investigations are easily dominated by the first explanation found, whereas when multiple independent investigators challenge each other, the theory that ultimately survives 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 batch import feature to the user management module. Create a team:
- One is responsible for backend APIs and database migrations.
- One is responsible for the frontend interface and interactions.
- One is responsible for writing integration tests.
First, have the architect members design the API specifications, and then have the others develop in parallel based on the specifications.
Usage Recommendations
Providing Sufficient Context for Members
Members automatically load the project context but do not inherit the leader's conversation history. Include the specific information required for the task in the initial Prompt:
Create a security reviewer with the following Prompt:
Review the authentication module in the `src/auth/` directory, with a focus on Token handling.
Session management and input validation. The application stores JWT tokens in httpOnly cookies.
Report the identified issues sorted by severity level.
Reasonably Dividing Task Granularity
Too small: Coordination overhead exceeds the benefits of parallelism.
Too large: Members do not report for a long time, increasing the risk of rework.
Appropriate: A self-contained work unit that produces a clear deliverable (a function, a test file, or a review report).
Note:
The leader automatically breaks down work into tasks and assigns them. If you feel the tasks are not broken down finely enough, you can ask the leader to break them down further. Keeping 5-6 tasks per member helps everyone stay productive and makes it easier for the leader to reassign work when someone gets stuck.
Waiting for Members to Complete
Sometimes the leader implements the work directly instead of waiting for members to complete it. If you notice this:
Continue only after your members have completed their respective tasks.
Or switch directly to Delegate Mode.
Avoiding File Conflicts
If two members edit the same file at the same time, they may overwrite each other's changes. When splitting up work, make sure each member is responsible for a different set of files.
Checking Progress Regularly
Monitor members' progress, correct any deviations promptly, and consolidate interim results at any time. Teams that remain unsupervised for long periods are more likely to generate waste.
Troubleshooting
Member Not Present
Check the team status bar to confirm whether members have been generated and are running.
Confirm that the task complexity warrants a team. CodeBuddy determines whether to generate members based on the task.
Excessive Permission Requests
Permission requests from members are routed to the leader, which may cause interruptions. Before generating members, pre-approve common operations in [Permission Settings].
Member Stopped After Encountering an Error
A member may stop working after encountering an error. Send additional instructions directly to the member via @MemberName, or have the leader generate a replacement member to continue the work.
Leader Ended Prematurely
The leader may consider the work finished before all tasks are completed. If this happens, tell it to keep 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 Resume: /resume and /rewind do not restore members. After a session is resumed, the leader may attempt to send messages to members that no longer exist. In this case, have the leader regenerate the members.
Task status may lag: Members sometimes fail to mark tasks as completed in a timely manner, causing dependent tasks to be blocked. If you find a task stuck, manually check whether the work is completed and update the status.
Disabling may be slow: Members first complete the current request or tool call before shutting down.
Each session can manage only one team: You must clear the current team before creating a new one.
Nested teams are not supported: Members cannot create their own sub-teams. Only the leader can manage the team.
The leader role is fixed: The session that created the team remains the leader throughout its entire lifecycle and cannot be transferred.
Permissions are determined at creation: All members inherit the leader's permission mode.
Note:
CODEBUDDY.md works as expected. Members read the CODEBUDDY.md file from their working directory. You can use this to provide project-level guidance to all members.
Related Features
Lightweight Delegation: Sub-agents spawn helper agents within a session, making them suitable for focused tasks that do not require coordination between members. Manual Parallelism: Git worktrees allow you to run multiple CodeBuddy Code sessions manually without automated team coordination.