Guided Tutorials

Multi-Agent Team for Large Features

Coordinate multiple Autohand agents working in parallel on different parts of a large feature. Each agent gets its own git worktree so they can work independently without stepping on each other, then you merge their output together.

Advanced 30 min
autohand "We need to add a notification system. Create a plan, then use worktrees to implement the database schema, API endpoints, and frontend components in parallel."

What you'll learn

  • How to plan a feature so multiple agents can work on it in parallel without conflicts
  • How to use the --worktree flag to launch isolated agent sessions
  • How to merge and resolve conflicts across parallel agent branches
  • How to run an integration review on the combined output before opening a PR

Before you start

  • Autohand Code installed
  • Git 2.5 or newer (worktrees require it; run git --version to check)
  • A project with clear layer separation (data, API, and UI in distinct directories)
  • An Autohand Pro or Team account that supports concurrent sessions (contact sales)
  • Enough disk space for multiple worktrees (each worktree is a full working copy)

Tip: Start with a feature that naturally decomposes into three independent tracks: a data layer change, a server-side change, and a client-side change. Notifications, user settings, and file management features all fit this pattern well.

Plan the feature first

Before dispatching agents, spend one session generating a detailed plan. This becomes the shared specification that all agents work from, which is the key to avoiding integration conflicts.

bash

autohand "We need to add a notification system to this application.
Read the codebase and create a detailed implementation plan that covers:
1. Database schema changes needed
2. API endpoints (REST or matching our existing pattern)
3. Frontend components and state management
4. How the three tracks interface with each other (shared types, API contracts)
Output the plan as a structured document with clear boundaries between the three tracks."

Save the output to a file that all agents can reference.

bash

# In the Autohand session
Save this plan to docs/notifications-implementation-plan.md

The plan document becomes critical. It defines the shared API contract between agents. If the database agent creates a notifications table and the API agent expects a user_notifications table, the merge will be painful. A good plan eliminates that category of conflict entirely.

Set up worktrees

Autohand has built-in worktree support. Instead of managing git worktrees manually, use the --worktree flag to launch each agent in its own isolated working copy.

bash

# Launch an agent in its own worktree
autohand --worktree "Implement the database schema track for notifications"

# Each --worktree session gets its own branch and working directory
# You can run multiple worktree sessions in parallel from separate terminals

Each worktree is a separate directory with its own working tree and branch but shares the same git object store. Changes in one worktree do not appear in others until you merge. Autohand handles the worktree creation, branch naming, and cleanup automatically.

Tip: The --worktree flag handles dependency installation, branch creation, and cleanup for you. You do not need to manage any of this manually.

Dispatch parallel agents

Open three terminal windows. Launch each agent with --worktree and give each its specific track from the plan document.

Terminal 1 - database track.

bash

autohand --worktree "Read docs/notifications-implementation-plan.md and implement
the DATABASE SCHEMA TRACK only. Create all migrations described in the plan.
Do not touch any API or frontend code. Commit your changes when complete."

Terminal 2 - API track.

bash

autohand --worktree "Read docs/notifications-implementation-plan.md and implement
the API ENDPOINTS TRACK only. Assume the database schema from the plan exists.
Create all routes, controllers, and service layer code described.
Do not modify migrations or frontend code. Commit when complete."

Terminal 3 - frontend track.

bash

autohand --worktree "Read docs/notifications-implementation-plan.md and implement
the FRONTEND COMPONENTS TRACK only. Assume the API endpoints from the plan exist.
Create all UI components, hooks, and state management described.
Use mock data for development since the API is not running yet. Commit when complete."

All three agents now run concurrently in isolated worktrees. You can watch their progress in each terminal window.

Monitor progress

While agents work, you can check their status without interrupting them by looking at the git log in each worktree.

bash

# Check what each agent has committed so far
git -C ../notifications-db log --oneline feature/notifications-db ^main
git -C ../notifications-api log --oneline feature/notifications-api ^main
git -C ../notifications-ui log --oneline feature/notifications-ui ^main

If an agent gets stuck or produces unexpected output, you can send a follow-up message in its terminal without stopping and restarting. Agents keep their context within a session.

Look for these warning signs during monitoring.

  • An agent that has made no commits after 10 minutes may be stuck on a clarification question. Check the terminal output.
  • An agent that is touching files outside its assigned track. Intervene with a redirect prompt.
  • Very large single commits. These suggest the agent is batching work that should be split across multiple commits. This makes the merge review harder.

Merge the results

Once all three agents have committed and signaled completion, merge their branches into a single integration branch.

bash

# Create an integration branch from main
git checkout -b feature/notifications-integration main

# Merge in this order: database first, then API, then UI
git merge feature/notifications-db --no-ff -m "merge: notifications database schema"
git merge feature/notifications-api --no-ff -m "merge: notifications API endpoints"
git merge feature/notifications-ui --no-ff -m "merge: notifications frontend components"

Merge in dependency order: data layer before API layer before UI layer. This ensures that when you hit conflicts, you are resolving them in the context of their dependencies.

Tip: Use --no-ff to keep merge commits in the history. This makes it much easier to identify which agent introduced a specific change if you need to trace a bug back to its source.

Resolve conflicts

Conflicts are common when merging parallel agent work. The most frequent types are shared type definition files, configuration files touched by multiple agents, and import paths in index files.

For conflicts in shared type files, open an Autohand session on the integration branch and let it resolve them.

bash

cd path/to/main-repo
git checkout feature/notifications-integration
autohand "There are merge conflicts in these files after merging three agent branches:
- src/types/notifications.ts (conflict between API and UI agent versions)
- src/index.ts (both API and UI agents added exports)

Read the implementation plan at docs/notifications-implementation-plan.md and
resolve the conflicts so both versions are correctly integrated. Run the
TypeScript compiler after resolving to confirm there are no type errors."

Autohand reads both conflict sides, the original plan, and the full context of each agent's work before proposing a resolution. This is more reliable than resolving manually because the agent understands the intent behind each side of the conflict.

Review the integrated feature

Once merges are complete and conflicts are resolved, do a full integration review before opening a pull request.

bash

autohand "The three agent branches have been merged into feature/notifications-integration.
Do a full integration review:
1. Read the implementation plan at docs/notifications-implementation-plan.md
2. Check that all planned features are present
3. Verify the API contract between the database, API, and frontend layers is consistent
4. Look for any missing error handling at layer boundaries
5. Check that all new code has test coverage
List any gaps as numbered items I need to address before opening a PR."

Run your test suite on the integration branch.

bash

npm run test
npm run build

If tests fail, paste the failure output into the Autohand session. The agent has context on all three tracks and can identify whether the failure is in the data layer, API layer, or UI layer quickly.

What you learned

  • You created a shared implementation plan that multiple agents can follow independently
  • You launched parallel agents in isolated git worktrees using the --worktree flag
  • You merged agent branches in dependency order and resolved integration conflicts with Autohand
  • You ran a full integration review to verify the combined output before opening a PR
Try next autohand --worktree "Read the codebase and add comprehensive test coverage for the notification system. Write unit tests for the service layer and integration tests for the API endpoints."

Related tutorials

Build a Custom MCP Server

Create tools that give your agents access to custom data sources and internal APIs.

Create an Evolve Pipeline

Set up continuous improvement pipelines that run agents on a schedule.