Hermes Agent Deep Cuts: The Persistence of Worktrees
Hermes Agent Deep Cuts: The Persistence of Worktrees
You’re trying to debug a memory leak in the core engine while simultaneously prototyping a new UI component. If you do this in a single linear session, your context becomes a mess of “where was I?” and “wait, is that fix for the leak or the UI?”.
Instead, you switch. You move into the debug-leak worktree, find the culprit, and then jump back to the ui-prototype worktree. You haven’t just changed your folder; you’ve changed your agent’s entire context.
The Mechanism: Branch-Isolated Persistence
Most agents rely on a linear stream of memory. While effective, it struggles with high-cardinality tasks. Worktrees solve this by leveraging Git’s structure.
A worktree in Hermes is a named, persistent branch-state. It isn’t just a temporary “folder” you visit; it’s a durable checkpoint where the agent’s HEAD, its local changes, and its specific context live. When you create a worktree, Hermes creates a new directory in .worktrees/ and a corresponding Git branch. This allows the agent to maintain “parallel universes” of progress.
Crucially, because each worktree is its own branch, an agent can “zoom in” on a specific problem, resolve it, and “zoom out” without losing the progress of other tasks.
More than just -w
For the daily operator, hermes -w is the easiest way to enter automatic worktree mode, but the real power lies in configuration and subagent delegation.
1. Worktree Isolation in Delegation
When you use delegate_task, the default behavior can lead to “context collision” where multiple subagents fight over the same branch. By setting delegation.worktree_isolation: true in your config, each child agent is born into its own unique worktree.
# config.yaml
delegation:
worktree_isolation: trueThis ensures that if you ask for a “Refactor the API” and a “Write the Docs” task simultaneously, they don’t overwrite each other’s files or get confused by each other’s local changes.
2. The .worktreeinclude Strategy
By default, Hermes tries to manage the worktree contents for you. However, you can fine-tune what persists using .worktreeinclude. This is vital for large projects where you don’t want to carry the weight of the entire repo’s node_modules or build/ folders into every single worktree.
3. Manual Management
You can also interact with worktrees directly via the CLI to see your “parallel universes”:
hermes worktree listThis command gives you a bird’s-eye view of every named state you’ve explored, showing the branch name, the last commit, and the status of the changes.
A Common Pitfall: The Drift Problem
The biggest mistake is treating a worktree as a “set it and forget it” folder. Because each worktree is an independent branch, they can drift.
If you spend an hour in the refactor worktree, the main branch doesn’t know what happened. Unlike memory, which is naturally cumulative, worktrees are divergent. To keep your agent’s world from falling apart, you must eventually merge your worktrees back into the main branch or use worktree_sync to ensure that changes in your primary checkout propagate to your active worktrees.
The Bottom Line
Worktrees turn the agent from a “linear thinker” into a “multi-tasker.” They are the difference between a chef trying to cook five dishes in one pan and a chef with five separate burners. Use worktrees when your tasks have distinct goals that don’t need to share the same immediate “workspace” but do need to share the same “world.”