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.
What you'll learn
- How to plan a feature so multiple agents can work on it in parallel without conflicts
- How to use the
--worktreeflag 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 --versionto 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.
Save the output to a file that all agents can reference.
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.
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.
Terminal 2 - API track.
Terminal 3 - frontend track.
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.
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.
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.
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.
Run your test suite on the integration branch.
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
--worktreeflag - 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