--- title: "Agent Teams" source: https://docs.autohand.ai/working-with-autohand-code/agent-teams --- # Agent Teams Split large tasks across multiple AI agents that work in parallel. A lead agent coordinates the team, manages a shared task list, and merges results when teammates finish their work. ## 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. ![Autohand Agent Teams creating and managing parallel tasks](/demos/autohand-agent-teams.gif) **Availability:** Agent Teams require Autohand Code v0.18 or later. Run `autohand --version` to check. ## 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. ``` bash # 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: ``` bash # 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](https://github.com/autohandai/awesome-sub-agents), propose an exact match, and add the approved definition to the team in the same session. **Availability:** Catalog discovery and installation require Autohand Code `0.9.3` or newer. Run `autohand --version` to check. Describe the expertise you need instead of guessing catalog names: ``` bash 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](/docs/guides/sub-agent-catalog.html) for selection and security guidance, or follow [Build a Specialist Agent Team from the Catalog](/docs/tutorials/build-specialist-agent-team.html) for a complete walkthrough. ## Task management Every team has a shared task list that the lead agent maintains. Tasks move through a simple lifecycle: | Status | Icon | Meaning | |---|---|---| | pending | ○ | Ready to be picked up by any idle teammate | | in_progress | ◔ | Currently being worked on by a teammate | | completed | ● | Finished and verified by the lead | ### 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`. ``` json { "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. ``` bash # 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. ``` bash /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. ``` bash /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. ``` bash # 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. ``` bash # 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. ``` bash # 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). **Tmux required:** Install tmux with `brew install tmux` on macOS or `apt install tmux` on Linux. If tmux is not installed, Autohand falls back to in-process mode. ## Team hooks Agent Teams integrate with the [hooks system](/docs/working-with-autohand-code/hooks.html) through a set of team-specific events. You can use these to track team activity, send notifications, or enforce policies. ### Available events | Event | Trigger | Variables | |---|---|---| | team-created | A new team is formed | {{teamName}}, {{taskCount}} | | teammate-spawned | A teammate agent starts | {{teamName}}, {{teammateName}} | | teammate-idle | A teammate finishes and has no tasks | {{teamName}}, {{teammateName}} | | task-assigned | A task is assigned to a teammate | {{teamName}}, {{teammateName}}, {{teamTaskId}} | | task-completed | A teammate finishes a task | {{teamName}}, {{teamTaskOwner}}, {{teamTaskId}} | | team-shutdown | All tasks are done and the team dissolves | {{teamName}}, {{duration}} | ### Example: Slack notifications for team progress ``` json { "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 ``` json { "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 ``` bash 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: ``` bash [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: ``` bash [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 ``` bash [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 ``` bash [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 ``` ![Full Agent Teams workflow showing parallel task execution](/demos/autohand-team-workflow.gif) ## 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. ``` bash # 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 ### What are Agent Teams in Autohand? Agent Teams let you coordinate multiple AI agents working in parallel on different parts of a task. A lead agent manages task assignment, dependencies, and progress across up to 5 teammates. Each teammate runs in its own process and can use different tools and models. ### How many teammates can I have in an Autohand team? An Autohand team supports up to 5 teammates managed by one lead agent. Teammates can run as in-process workers or in separate tmux sessions. The lead assigns tasks, tracks dependencies, and handles recovery if a teammate crashes. ### How do I create an agent team? Type /team create my-team inside a session to start a team. Assign tasks with /tasks and communicate with teammates using /message name your instruction. The lead agent can also delegate tasks automatically based on the work description. ### Can Autohand find a specialist that is not installed? Yes. In Autohand Code 0.9.3 or newer, ask Autohand to search the default sub-agent catalog for the missing role. Autohand shows matching definitions and requests approval before installing an exact match for immediate delegation.