Agent Teams

What are Agent Teams

Agent Teams let you break a complex task into smaller pieces and assign those pieces to multiple agents running at the same time. The architecture follows a lead-managed model: one lead agent coordinates everything, and up to 5 teammate agents execute tasks independently.

Each teammate runs its own LLM loop. Teammates have their own tool access, their own context window, and their own working branch. The lead agent is responsible for decomposing the original task, creating the task list, spawning teammates, and collecting results.

This is useful when you have work that can be done in parallel. For example, building a new API endpoint might involve writing the route handler, the database migration, the input validation, and the tests. A team of 4 agents can work on all of those at the same time.

Creating a team

The fastest way to start a team is with the /team slash command inside an active session. Autohand walks you through an interactive wizard that asks for a team name, the number of teammates, and the initial task breakdown.

# Start the team wizard
/team

# The wizard prompts you:
# Team name: payment-refactor
# Max teammates (1-5): 3
# Describe the overall task:
#   Refactor the payment module to support Stripe and PayPal

When you confirm, the lead agent analyzes your description, breaks it into tasks, and adds them to a shared task list. Each task gets a unique ID, a description, and an initial status of pending.

From the CLI

You can also start a team directly from the command line:

# Start Autohand with a team prompt
autohand --team 3 "Refactor the payment module to support Stripe and PayPal"

# Start a team in tmux mode for persistent sessions
autohand --team 3 --tmux "Build the user settings page with API and tests"

The --team flag takes the number of teammates as its argument. The lead agent uses the prompt to generate the initial task list and then spawns teammates to start working.

How the lead agent works

Once a team is created, the lead agent takes on a coordination role. It does not write code directly. Its responsibilities are:

• Decomposing the overall goal into discrete, well-scoped tasks
• Assigning tasks to teammates as they become idle
• Tracking task progress and dependencies
• Sending messages to teammates with guidance or clarification
• Reviewing completed work and merging results
• Handling errors and reassigning failed tasks

Add specialists from the sub-agent catalog

If the right teammate is not installed, Autohand can search the default awesome-sub-agents catalog, propose an exact match, and add the approved definition to the team in the same session.

Describe the expertise you need instead of guessing catalog names:

autohand -p "Bring a team of UI design, security review, and API design specialists. \
Search the sub-agent catalog for missing roles, install exact matches, \
create the team, and delegate the work."

Autohand searches by role, category, tools, and use case. Every installation pauses for approval before a Markdown definition is written to ~/.autohand/agents/. Approved definitions are reloaded immediately, so the lead can delegate to the new specialist without restarting Autohand.

See the Sub-agent Catalog guide for selection and security guidance, or follow Build a Specialist Agent Team from the Catalog for a complete walkthrough.

Task management

Every team has a shared task list that the lead agent maintains. Tasks move through a simple lifecycle:

Task dependencies

Tasks can depend on other tasks through the blockedBy array. A blocked task stays in pending status and will not be assigned until all of its dependencies are marked completed.

{
  "tasks": [
    {
      "id": "task-1",
      "description": "Create the database migration for payment_methods table",
      "status": "pending",
      "blockedBy": []
    },
    {
      "id": "task-2",
      "description": "Write the Stripe integration service",
      "status": "pending",
      "blockedBy": ["task-1"]
    },
    {
      "id": "task-3",
      "description": "Write the PayPal integration service",
      "status": "pending",
      "blockedBy": ["task-1"]
    },
    {
      "id": "task-4",
      "description": "Add API route handlers for payment endpoints",
      "status": "pending",
      "blockedBy": ["task-2", "task-3"]
    }
  ]
}

In this example, task-2 and task-3 both depend on the database migration in task-1. Once the migration is done, Stripe and PayPal work can happen in parallel. The route handlers in task-4 wait for both integrations to finish.

Auto-assignment

When a teammate completes a task and goes idle, the lead agent automatically assigns the next available pending task. The lead checks the dependency graph and picks the highest-priority unblocked task. If no tasks are available, the teammate waits until a dependency is resolved.

Crash recovery

If a teammate crashes or disconnects, any tasks in in_progress status that were assigned to that teammate are automatically released back to pending. The lead agent logs the failure and makes the task available for another teammate to pick up.

# Lead agent output when a teammate crashes
[team] Teammate "backend-worker" disconnected unexpectedly
[team] Releasing task-2 "Write the Stripe integration service" back to pending
[team] Task is now available for reassignment

Team commands

During a team session, the lead agent has access to several slash commands for monitoring and communication.

/team

Shows the current team status including the team name, active teammates, and a summary of task progress.

/team

# Output:
# Team: payment-refactor
# Teammates: 3 active, 0 idle
#
# Tasks:  2 completed, 2 in progress, 1 pending
#
# Members:
#   backend-worker   [in_progress] task-2: Write the Stripe integration
#   frontend-worker  [in_progress] task-3: Write the PayPal integration
#   test-writer      [idle]        Waiting for available tasks

/tasks

Displays the full task list with status icons, assignees, and dependency information.

/tasks

# Output:
# ● task-1  Create the database migration           (completed by backend-worker)
# ◔ task-2  Write the Stripe integration service     (backend-worker)
# ◔ task-3  Write the PayPal integration service     (frontend-worker)
# ○ task-4  Add API route handlers                   (blocked by: task-2, task-3)
# ○ task-5  Write integration tests                  (blocked by: task-4)

/message

Send a direct message to a specific teammate. This is useful for giving extra context, adjusting requirements, or asking a teammate to change direction.

# Send guidance to a teammate
/message backend-worker Use the Stripe SDK v14, not v13. The API changed.

# Ask a teammate for a status update
/message frontend-worker How is the PayPal integration going?

The teammate receives the message in their context and can respond through the team communication channel. Messages are logged in the team history for the lead to review.

Teammate modes

Teammates can run in two rendering modes depending on your environment.

In-process mode

The default mode renders all teammates within the same terminal using the Ink TUI framework. Each teammate gets a panel in the interface showing its current task, output, and status. This works well for quick tasks and when you want to see everything in one place.

# In-process mode (default)
autohand --team 3 "Build the search feature"

Tmux mode

When Autohand detects a tmux environment, or when you use the --tmux flag, each teammate runs in its own tmux pane. This gives every teammate a full terminal with scrollback history, and the sessions persist even if you detach.

# Tmux mode with dedicated panes per teammate
autohand --team 3 --tmux "Build the search feature"

# Autohand auto-detects tmux if you're already in a tmux session
# and switches to tmux mode automatically

Tmux mode is the recommended approach for long-running team tasks. Each teammate's output is fully preserved, and you can switch between panes using standard tmux keybindings (Ctrl-B followed by arrow keys).

Team hooks

Agent Teams integrate with the hooks system through a set of team-specific events. You can use these to track team activity, send notifications, or enforce policies.

Available events

Example: Slack notifications for team progress

{
  "hooks": {
    "task-completed": [
      "curl -X POST $SLACK_WEBHOOK -H 'Content-type: application/json' -d '{\"text\": \"[{{teamName}}] {{teamTaskOwner}} completed {{teamTaskId}}\"}'"
    ],
    "team-shutdown": [
      "curl -X POST $SLACK_WEBHOOK -H 'Content-type: application/json' -d '{\"text\": \"Team {{teamName}} finished all tasks in {{duration}}ms\"}'"
    ]
  }
}

Example: Log task assignments for auditing

{
  "hooks": {
    "task-assigned": [
      "echo '{{teamName}} | {{teammateName}} | {{teamTaskId}} | assigned' >> ~/.autohand/team-audit.log"
    ],
    "task-completed": [
      "echo '{{teamName}} | {{teamTaskOwner}} | {{teamTaskId}} | completed' >> ~/.autohand/team-audit.log"
    ]
  }
}

Practical example

Here is a full walkthrough of using Agent Teams to build a user notifications feature. This covers the entire lifecycle from team creation to merged results.

Step 1: Start the team

autohand --team 3 --tmux "Build a user notification system with database, \
API endpoints, and a React notification bell component"

Step 2: Lead decomposes the task

The lead agent analyzes the codebase, understands the project structure, and creates a task list:

[lead] Analyzing project structure...
[lead] Detected: TypeScript, Express, React, PostgreSQL, Prisma
[lead] Creating task breakdown:

  task-1: Create Prisma migration for notifications table
  task-2: Build notification service (create, read, mark-as-read)  [blocked by: task-1]
  task-3: Add REST endpoints (GET /notifications, PATCH /notifications/:id)  [blocked by: task-2]
  task-4: Build React NotificationBell component with dropdown  [no blockers]
  task-5: Wire up the frontend to the API with React Query  [blocked by: task-3, task-4]
  task-6: Write integration tests for the notification flow  [blocked by: task-5]

[lead] Spawning 3 teammates...

Step 3: Teammates work in parallel

The lead assigns tasks based on the dependency graph. Tasks without blockers start immediately:

[lead] Assigning task-1 to db-worker
[lead] Assigning task-4 to frontend-worker
[lead] test-worker is idle (waiting for unblocked tasks)

# db-worker creates the Prisma schema and runs the migration
# frontend-worker builds the React component independently
# They work at the same time in separate tmux panes

Step 4: Dependencies resolve and work continues

[lead] db-worker completed task-1
[lead] task-2 is now unblocked, assigning to db-worker
[lead] frontend-worker completed task-4
[lead] frontend-worker is idle (task-5 still blocked)

# db-worker moves on to the notification service
# frontend-worker waits until both task-3 and task-4 are done

[lead] db-worker completed task-2
[lead] task-3 is now unblocked, assigning to test-worker
[lead] test-worker completed task-3
[lead] task-5 is now unblocked, assigning to frontend-worker
[lead] frontend-worker completed task-5
[lead] task-6 is now unblocked, assigning to db-worker
[lead] db-worker completed task-6

Step 5: Lead merges and reviews

[lead] All 6 tasks completed
[lead] Merging teammate branches...
[lead] Running final checks: npm run typecheck && npm test
[lead] All checks passed

Team "notifications" completed in 4m 32s
  6 tasks completed
  3 teammates used
  0 failures

Tips

When to use teams

Teams work best when a task can be cleanly divided into independent pieces. Good candidates:

• Building a feature that spans multiple layers (database, API, frontend, tests)
• Refactoring several modules that share an interface
• Writing tests for multiple services at once
• Migrating a set of files from one pattern to another

A single agent is better when the work is deeply sequential and each step depends heavily on the previous one, or when the task is small enough that the overhead of team coordination is not worth it.

Keep tasks small and focused

Each task should take a teammate roughly 2 to 5 minutes. If a task is too large, the teammate might run out of context or produce inconsistent results. If a task is too small, the coordination overhead slows things down.

# Too broad
"Build the entire payment system"

# Good granularity
"Create the Stripe webhook handler for payment.succeeded events"
"Write the PayPal IPN validation middleware"
"Add unit tests for the payment amount calculator"

Use tmux for long-running work

If your team will run for more than a few minutes, always use --tmux. This way you can detach from the session, do other work, and reattach later to check on progress. The teammates keep running in the background.

Set up task dependencies carefully

Think about what truly needs to be sequential and what can be parallel. Frontend components often have no dependency on backend services during development, so they can be built at the same time. Tests, on the other hand, usually need the code they test to exist first.

Review team output

After a team finishes, the lead agent runs your project's type checker and test suite. You should also review the changes yourself, especially for tasks that involved complex logic or cross-cutting concerns. Use git diff or your code review tool to inspect what each teammate produced.

Frequently asked questions