Parallel agents are safe only when they do not share mutable repository state. A Git worktree gives each Hermes process its own directory and branch while reusing the repository’s object database.
- Delegate work that benefits from a fresh context or parallel reasoning.
- Give every editing worker a separate worktree and branch.
- Pass complete task context; children do not inherit the conversation.
- Review diffs and rerun tests in the integration checkout before merging.
1. Separate context isolation from filesystem isolation
A delegated child has its own conversation and terminal session. It receives the goal and context supplied by the parent, not the parent’s full conversation. That protects the context window, but it does not automatically make two workers safe inside one checkout.
Filesystem isolation comes from separate worktrees. Each worktree has its own index, checked-out files, branch, and working directory. Two agents can edit at the same time without rewriting each other’s uncommitted files.
Use both boundaries for parallel code changes: fresh agent context and a dedicated Git worktree.
2. Run the deterministic worktree fixture
The example creates a temporary repository, a baseline commit, and two worktrees. One branch writes documentation; the other writes a test note. It checks that the changed-file sets do not overlap before merging.
workspace=$(mktemp -d)
python3 worktree_demo.py --workspace "$workspace" --jsonThe report names both branches, the merged files, isolation status, clean-tree status, and the number of non-merge commits. It does not invoke Hermes or a model, so the Git mechanics remain reproducible without provider credentials.
The workspace must be empty. The script configures user.name and user.email only in its temporary repository, leaving the user’s global Git configuration unchanged.
3. Create worktrees manually when paths matter
From an existing repository, create one branch and directory per assignment:
git worktree add ../project-docs -b agent/docs
git worktree add ../project-tests -b agent/tests
git worktree listStart each Hermes process from its assigned directory. Hermes treats the current working directory as project scope, so context files, terminal commands, and file operations follow that checkout.
When an assignment is complete, keep its branch until review and integration finish. Removing a worktree does not delete the branch automatically.
4. Use Hermes automatic worktree mode
Hermes can create an isolated branch and worktree for a session:
hermes -w -z "Implement the assigned change, run tests, and commit it"Open separate terminals for independent workers. Automatic mode is convenient for one-off assignments; manual worktrees are easier when an orchestrator needs stable, named directories for handoffs and repeated inspection.
A child task must include the repository path, branch or worktree, allowed file scope, acceptance criteria, and exact test command. “Fix the bug we discussed” is not sufficient because the child has no conversation history.
5. Review the handoff instead of trusting the summary
A worker’s final message is a summary, not proof. In the integration checkout, inspect each branch before merging:
git diff --stat main..agent/docs
git diff --name-only main..agent/docs
git diff --check main..agent/docs
git log --oneline main..agent/docsCompare the changed files with the assignment. Read load-bearing edits, then run the project’s tests against the branch. Reject unrelated changes or a dirty worktree before integration.
When branches touch the same file, parallel execution may still save research time, but the merge is no longer independent. Resolve that overlap in one integration checkout with a named owner.
6. Merge and clean up in order
Merge reviewed branches from the integration branch. Run the full test suite after all merges because independently passing branches can interact.
After integration, remove worktrees and decide whether to retain the branches:
git worktree remove ../project-docs
git worktree remove ../project-tests
git branch -d agent/docs
git branch -d agent/testsGit refuses to remove a worktree with uncommitted changes unless forced. Treat that refusal as a safety signal. Inspect the directory rather than bypassing it automatically.
Delegation is not a durable queue. Closing the owning process can cancel or strand a child. Use Cron for scheduled durable work and Kanban for persistent multi-agent dependencies; worktrees solve mutable checkout isolation, not orchestration durability.
7. Test the isolation contract
Run the fixture tests from the example directory:
python3 -m unittest discover -s tests -vThe suite verifies two isolated branches, exact changed files, clean integration, commit count, and rejection of a non-empty target workspace. It uses real Git commands rather than mocking repository behavior.
The fixture avoids merge conflicts by assigning disjoint files. Production work still needs a review policy, branch ownership, conflict handling, and a final test run. Chapter 11 builds those handoffs into a durable Hermes Kanban board.
Leave a Reply