Worktree as an Isolation Boundary

+15 Mana ✨
Hermes Worktree Flag(DOCUMENTATION)Git Worktree(DOCUMENTATION)

Introduction

There is a class of tasks you want the agent to attempt but not on your main branch: experimental refactors, risky cleanups, parallel explorations. Hermes ships a single flag for this: -w (or --worktree). Pass it at launch and Hermes runs in a fresh git worktree, isolated from your current working copy. The agent can edit, create branches, and commit without touching the files you are actively working on.

Key Concepts

  • Git worktree: A separate working directory backed by the same repository. Two worktrees can have different files checked out at the same time.
  • -w / --worktree flag: Tells Hermes to launch in a freshly-created worktree of the current repo.
  • Isolation boundary: File-level isolation, not just a different terminal session.
  • Parallel agents: Two hermes -w instances can run simultaneously without conflict.

Real World Context

A developer is mid-feature on main and wants the agent to try a different architecture for the same feature without losing their current work. They open a second terminal, run hermes -w "try the alternative design with a state machine instead of callbacks", and let the agent work. Their original terminal keeps editing in their original worktree. Forty minutes later they have two implementations to compare, and the experiment did not collide with their in-progress files.

Deep Dive

Git worktrees are a long-standing feature: one repository can have multiple working directories, each with its own branch and checked-out files. git worktree add creates a new directory backed by the same .git. Hermes uses this primitive to create a sandbox for risky agent work.

When you launch with -w:

bash
hermes -w                       # interactive session in a new worktree
hermes -w -q "Fix issue #123"   # one-shot query in a new worktree
hermes -w -z "refactor X"       # scripted one-shot in a new worktree

Hermes does roughly this under the hood:

text
1. Check that the current directory is inside a git repository.
2. Pick a temporary path under your worktree root (e.g., ~/.hermes/worktrees/<branch>/).
3. Run `git worktree add <path> -b agent/<short-id>` to create a new branch in a new directory.
4. cd into the new worktree.
5. Start the agent session there.

The agent's filesystem tools now see the worktree's files. Edits land in agent/<short-id> branch, not in your current branch. When the session ends, the worktree is cleaned up automatically if the agent did not commit, or preserved if it did.

When to use -w

  • Experimental refactors: "Try a different architecture and tell me what you think."
  • Parallel agents: Two long-running tasks side by side, each in its own worktree.
  • Safe automation: A cron-triggered Hermes that should never touch your live working copy.
  • Pull request reviews: An agent that checks out the PR branch in a fresh worktree to comment without disrupting your local state.

When not to use -w

  • You want the changes in your current working tree: The whole point of -w is to keep them separate. Use a regular hermes launch when you want the diffs in front of you.
  • The task is read-only: If the agent is only reading files, isolation buys you nothing.
  • You are not in a git repository: -w requires git. Outside a repo it is meaningless.

Common Pitfalls

  1. Forgetting you are in a worktree: You finish a session, exit, and a day later wonder where the changes went. They are on agent/<short-id> in the worktree, not your main branch. Run git worktree list to find them.
  2. Using -w for everything: Most coding sessions benefit from changes showing up in your current working tree. Reserve -w for genuinely risky or parallel work.

Best Practices

  1. Pair -w with a clear intent in the prompt: "Try X, commit on success, otherwise discard" is much better than ambiguous instructions, because cleanup depends on the agent's behavior.
  2. Run git worktree list periodically: Stale worktrees accumulate if you forget about them. Cleanup is git worktree remove <path>.

Summary

  • -w (or --worktree) launches Hermes in a fresh git worktree, isolating file changes.
  • The agent gets its own working directory and branch (agent/<short-id>).
  • Use it for experimental refactors, parallel agents, and safe automation.
  • Stale worktrees should be cleaned up with git worktree remove.

Code Examples

bash
# Three ways the -w flag combines with other launch modes
hermes -w                                       # interactive in a fresh worktree
hermes -w -q "Try a state-machine refactor"     # one-shot interactive query
hermes -w -z "Run the test suite and report"    # scripted, plain-stdout output

# Inspect and clean up worktrees later
git worktree list                                # see every worktree the repo has
git worktree remove ~/.hermes/worktrees/abc123   # delete one you no longer need
✓ Completed