Parallel Hermes Agents with Git Worktrees

Git worktrees are the safest default when several Hermes coding sessions need to operate on one repository at the same time. Every agent receives its own checkout and branch while the repository shares Git objects efficiently.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/git-worktrees

Manual and automatic paths

A manual worktree is useful when branch names and directories must be planned in advance. Create it from the primary checkout with git worktree add <path> <branch>, enter that directory, and start Hermes there.

For disposable agent work, run hermes -w from a Git repository. Hermes creates an isolated worktree under .worktrees/ with its own generated branch. One-shot mode also supports this pattern, for example hermes -w -z "Run the focused task and verify it".

Parallel-work checklist

• Give every task a separate worktree and branch.
• Start each Hermes process from its assigned worktree.
• Keep acceptance criteria and test commands specific to that branch.
• Prevent two agents from editing the same checkout.
• Review each diff before integration.
• Resolve shared migrations and generated files deliberately.
• Confirm no process is still using a worktree before removal.
• Remove the worktree through Git rather than deleting the directory blindly.

Integration discipline

Isolation prevents accidental file collisions; it does not make two designs compatible. Review dependencies, migrations, generated artifacts, and test assumptions before merging. Integrate one branch at a time and rerun the broader suite after each merge when changes overlap semantically.

Pitfalls

• Running parallel agents in one checkout and trusting them not to collide.
• Confusing a clean worktree with a reviewed change.
• Removing a worktree that contains uncommitted evidence.
• Assuming checkpoint history substitutes for branch isolation.
• Merging several individually green branches without testing their combination.

Verification steps

1. Run git worktree list and confirm every worker has a distinct path and branch.
2. Ask each agent to report its current directory and branch before editing.
3. Make a harmless change in one worktree and confirm the others remain unchanged.
4. Run the focused tests in every worktree.
5. Inspect each diff from the primary repository.
6. Integrate in a controlled order and run the combined test suite.
7. Use git worktree remove only after changes and processes are accounted for.