Agent Teams - Qoder

Agent Teams turns one interactive Qoder CLI session into a small group of collaborating agents. The entry point stays the same: describe the goal in the current session, and the main Agent can create teammates to research, implement, review, and hand work to each other. Use Agent Teams when a task is large enough to benefit from multiple focused members working in parallel, such as exploring several modules, separating implementation from review, or moving a refactor through research, coding, and validation.

Beta Agent Teams is currently a beta feature and is not enabled by default. Set the feature flag before starting Qoder CLI: QODER_AGENT_TEAMS=1 qodercli. The flag can also be stored as QODER_AGENT_TEAMS=1 in the user-level configuration .env file so later sessions enable Agent Teams automatically. Default user-level configuration path: $HOME/.qoder/.env on macOS/Linux, and %USERPROFILE%\.qoder\.env on Windows. Restart Qoder CLI after changing .env.

What Agent Teams are

An Agent Team has two kinds of participants:

Role	Description
Main Agent	The Agent that talks directly with the user. It understands the goal, splits work, summarizes results, and reports important progress.
Teammate	A member created by the main Agent, such as `researcher`, `coder`, or `reviewer`. A teammate has its own context and can receive follow-up SendMessage and Tasks.

Qoder CLI session
+-- main conversation
|   `-- The main Agent talks with the user, delegates work, and summarizes results
|
+-- Agent Team
|   +-- @researcher  explores code paths
|   +-- @coder       implements changes
|   `-- @reviewer    checks risks
|
`-- shared Task list
    +-- Task A  owner=@researcher
    +-- Task B  owner=@coder
    `-- Task C  owner=@reviewer

No manual team creation is required. An interactive session has one current team. When the main Agent needs a teammate, it creates a named Agent and adds that member to the team.

How to use Agent Teams

The most reliable request style is to mention Agent Teams explicitly and describe the teammate roles:

Use Agent Teams for this refactor.
Create three teammates: researcher, coder, and reviewer.
1. researcher traces the auth module call flow.
2. coder changes the code based on researcher's findings.
3. reviewer checks risks and missing tests.
Return a change summary, changed files, and verification results.

If the request only says “parallelize” or “have a few agents look at this,” Qoder CLI may choose ordinary Subagents, background tasks, or a workflow. Ask for Agent Teams directly when teammates should keep collaborating in the same session.

How it works

Agent Teams are built around teammates, SendMessage, and a shared Task list.

Collaboration flow

Agent Teams can be understood as a collaboration loop organized by the main Agent. The main Agent understands the goal, creates teammates, assigns Tasks, uses SendMessage to coordinate questions and findings, and summarizes results. Teammates do the focused work, while the shared Task list records ownership and progress.

User goal
  |
  v
+------------+
| main Agent |
+------------+
  |  Create teammates
  |  Assign / update shared Tasks
  |  Collect and summarize results
  |
  +-----------------------+
  |                       |
  v                       v
+------------------+   +------------------------+
| shared Task list |   | SendMessage            |
| owner / status   |   | asks / finds / results |
+------------------+   +------------------------+
  |                       |
  +-----------+-----------+
              |
              v
+-------------+ SendMessage +----------+
| @researcher | <---------> | @reviewer |
+-------------+             +----------+
       |                         |
       +-----------+-------------+
                   |
                   v
            progress and results
                   |
                   v
              main Agent
                   |
                   v
              final response

Lifecycle and resume

An Agent Team exists only inside the currently open TUI session. Each time an interactive session starts with Agent Teams enabled, Qoder CLI prepares a temporary team for that session. The main Agent creates teammates inside that team. Within the same TUI, a teammate can move through running -> idle -> running multiple times. idle means the teammate has no active work; it does not mean the teammate has exited.

Current TUI session
+-- main conversation
+-- Agent Team
|   +-- @researcher  running / idle
|   `-- @reviewer    running / idle
`-- shared Task list

When the TUI exits, Qoder CLI stops the teammates from that session and clears that team state. Later, resume restores the main conversation history, but it does not bring back the teammates created in the previous TUI or their last running or idle state. Summaries or SendMessage content already visible in the main conversation remain as history, but the previous teammates are no longer running. If team collaboration is still needed after resume, the main Agent should create new teammates. Teammates only live inside the current TUI session and do not carry over to the next resume after the TUI exits.

TUI display

Agent Teams are currently displayed inside one TUI window. The bottom of the conversation shows an agents list. The down arrow opens the list, the up and down arrows select the main conversation or a teammate, Enter switches to the selected view, and Esc returns to the main conversation. Multiple split TUI panes are not currently supported. Teammates are not shown side by side; their conversation views are opened by switching inside the same window.

Teammates

When the main Agent creates a teammate, it gives that member a stable name such as researcher. The team can use that name later for SendMessage, Task assignment, and status tracking. After a teammate finishes its current work, it usually becomes idle. Idle does not mean exited; it means the teammate has no active work and can be woken by a new SendMessage or Task.

@researcher running -> idle -> running -> idle
                      ^        |
                      |        `-- Woken by a new task
                      `-- Current turn finished

SendMessage

The main Agent and teammates can use SendMessage to communicate with each other. A teammate's normal text output is not automatically sent through SendMessage; information meant for a specific team member is sent through SendMessage. In the UI, SendMessage content usually appears as “Message from @researcher,” making questions, findings, and results easier to follow during collaboration.

Shared Tasks

Agent Teams can use the shared Task list. The main Agent can create tasks first, then teammates can handle the matching pieces of work.

shared Task list
+-- [in progress] Map old API call sites       owner=@researcher
+-- [pending]     Implement the new adapter    owner=@coder
`-- [pending]     Add migration tests          owner=@tester

The shared Task list makes collaboration easier to follow: it records who owns each task, what is complete, and what depends on other work. Completing a Task does not shut down the teammate; the teammate can remain available for more work.

Agent Teams vs. Subagents

Agent Teams use Agent capabilities, but they are different from ordinary Subagent delegation.

Area	Subagent	Agent Teams
Best for	One focused subtask	Complex work with several collaborating members
Lifecycle	Usually returns one result and ends	Teammates can become idle and receive more work in the same session
Communication	Results mainly return to the main Agent	Main Agent and teammates can communicate through SendMessage
Coordination	Mostly orchestrated by the main Agent	Can use a shared Task list for assignment and tracking
Identity	Based on Subagent type	Based on runtime names such as `@coder` or `@reviewer`

In short:

Use a Subagent for handing off one clear subtask and getting a result back.
Use Agent Teams for multiple teammates that should keep collaborating, communicate through SendMessage, claim Tasks, and move through phases together.

When to use Agent Teams

Good fits:

Scenario	Why it fits
Large code exploration	Different teammates can inspect different areas and report findings to the main Agent.
Implementation plus review	One member can write code while another independently reviews risks, tests, and edge cases.
Parallel work streams	Independent subtasks can move at the same time.
Repeated handoffs	Teammates keep their names and context for follow-up work.
Visible coordination	Shared Tasks show owners, status, and dependencies.

Poor fits:

Scenario	Better option
Reading one file or finding one symbol	Ask the main Agent to read or search directly.
One independent subtask	Use an ordinary Subagent.
A fixed reusable multi-stage process	Use a workflow.
A small low-cost task	Use fewer agents to avoid extra context and token usage.

Tips

Give every teammate a short name and clear role, such as researcher, coder, or reviewer.
State the expected output, such as root cause, change summary, verification results, risks, or follow-up suggestions.
Use shared Tasks when the work has more than a few steps, so ownership, status, and dependencies are easy to follow.
Keep the team small at first. Two to four teammates is enough for most tasks.
Treat idle as available, not finished. Ask the main Agent to shut down teammates when collaboration is no longer needed.

Examples

Parallel exploration

Use Agent Teams to analyze this login issue.
Create two teammates:
1. researcher checks auth and session code.
2. tester checks existing tests and reproduction paths.
Return the likely root cause, impact scope, risks, and a recommended fix.

Implementation with independent review

Use Agent Teams for this fix.
Have coder make the code change, then have reviewer independently review the final diff.
reviewer should check edge cases, test coverage, and possible regressions.
Return what changed, how it was verified, and any remaining risk.

Shared Task list

Use Agent Teams and the shared Task list for this migration.
Create these Tasks:
1. Map old API call sites.
2. Implement the new API adapter.
3. Add migration tests.
Then create researcher, coder, and tester teammates to claim those tasks.
Include each Task's completion status, key changes, and verification results in the final result.

​What Agent Teams are

​How to use Agent Teams

​How it works

​Collaboration flow

​Lifecycle and resume

​TUI display

​Teammates

​SendMessage

​Shared Tasks

​Agent Teams vs. Subagents

​When to use Agent Teams

​Tips

​Examples

​Parallel exploration

​Implementation with independent review

​Shared Task list