Supercharge Your AI Agent Workflow: Git Worktrees + Hermes Agent

Supercharge Your AI Agent Workflow: Git Worktrees + Hermes Agent

Hermes Agent··9 min read·hermes-agentgit-worktreesparallel-workflowsdeveloper-tools

Use Git worktrees with Hermes Agent for safe parallel AI workflows — manual setup, hermes -w, and best practices.

Picture this: You’re deep in a coding session with Hermes Agent, an autonomous AI that’s refactoring your authentication module. It’s making great progress—until you realize you need to run a second experiment in parallel. Maybe you want to test a different approach to that same bug, or you need to keep one agent working on features while another investigates a performance issue.

If you try to run both experiments in the same directory, you’re asking for trouble. The agents will step on each other’s toes, overwrite files, and create a tangled mess of conflicting changes. This is where Git worktrees come to the rescue—and Hermes Agent has built-in support that makes parallel AI workflows not just possible, but elegant.

Why Worktrees Matter When Working with AI Agents

Here’s the fundamental issue: Hermes treats your current working directory as the project root. When you launch an agent, it sees the entire directory as its sandbox. It reads files, modifies code, runs tests, and commits changes—all within that single working tree.

The problem? Multiple agents on the same checkout cause conflicts. If Agent A modifies src/utils.ts while Agent B is reading it, Agent B might work with stale code. Worse, if both agents run git commit, you’ll get interleaved histories and merge chaos.

Git worktrees solve this by giving each agent its own isolated workspace—a separate directory, a separate branch, and a separate working tree—all backed by the same Git repository. It’s like giving each AI its own office while they all share the same filing cabinet.

The Manual Approach: Creating a Worktree by Hand

Let’s start with the classic method, which gives you full control. Suppose you’re working on a project called my-app and you want to run an experiment for a new feature.

First, navigate to your project and create a new worktree:

cd ~/projects/my-app
git worktree add ../my-app-feature feature/hermes-experiment

This command does two things:

  1. Creates a new branch called feature/hermes-experiment
  2. Checks out that branch into a new directory at ../my-app-feature

Now you have two separate working directories pointing to the same repository. The key insight here is that each worktree gets its own branch, working directory, AND separate Checkpoint Manager history. This means when you use /rollback in Hermes, it only rolls back changes within that specific worktree—it won’t touch your main working directory.

To use this with Hermes, simply navigate into the new directory and launch the agent:

cd ../my-app-feature
hermes

The agent will work entirely within this isolated environment. You can run your main development in ~/projects/my-app while Hermes experiments freely in ~/projects/my-app-feature.

The Automatic Mode: hermes -w for Instant Isolation

While manual worktrees are powerful, they require you to remember the exact commands and manage the directories yourself. Hermes Agent has a better way: the -w flag.

When you run hermes -w, the agent automatically:

  1. Creates a disposable worktree under .worktrees/ in your project
  2. Creates an isolated branch (e.g., hermes/hermes-<hash>) for the session
  3. Runs the full CLI session inside that worktree

Here’s the magic in action:

cd ~/projects/my-app
hermes -w "Refactor the database connection pool"

That’s it. Hermes handles the entire worktree lifecycle for you. The agent will work in a fresh, isolated environment with its own branch, and when you’re done, the temporary worktree is removed.

For a one-shot query—where you just want a quick answer or a single task completed—combine -w with the -z flag:

hermes -w -z "Fix issue #123 in the payment module"

This runs Hermes in disposable mode with a single query. It’s perfect for CI/CD pipelines, cron jobs, or when you just want a quick autonomous fix without polluting your main workspace.

Running Parallel Agents: The Real Power Move

Now for the exciting part. The -w flag is designed for running multiple agents in parallel. Here’s a realistic scenario:

Situation: Your team needs three things done simultaneously:

  1. Fix a critical bug in the login flow
  2. Implement a new API endpoint
  3. Refactor the frontend state management

Solution: Open three terminals and run:

# Terminal 1 - Bug fix
hermes -w -z "Fix the race condition in login flow, issue #45"

# Terminal 2 - New feature
hermes -w -z "Create a new /api/v2/users endpoint with pagination"

# Terminal 3 - Refactoring
hermes -w -z "Refactor Redux store to use Zustand, update all imports"

Each command creates its own isolated worktree under .worktrees/, runs independently, and reports back with its results. Your main working directory stays clean and untouched.

But wait—there’s a subtlety. Each of these agents runs in its own worktree with its own branch. When they finish, you’ll have three separate branches with changes. To integrate them, you’ll need to merge or rebase:

# After all agents complete
git checkout main
git merge feature/bugfix-login-race
git merge feature/api-v2-users
git merge feature/refactor-zustand

This workflow is incredibly powerful because it lets you parallelize AI work without the fear of conflicts. Each agent operates in complete isolation.

The Checkpoint Advantage: Why Isolation Matters More Than You Think

One of the most underrated features of Hermes is its Checkpoint Manager. When an agent makes changes, it periodically saves checkpoints that you can roll back to. This is a safety net that lets you undo AI mistakes.

But here’s the kicker: checkpoints are tied to the working directory. When you use worktrees, each worktree maintains its own checkpoint history, derived from a shadow repo hash based on the worktree path. If Agent A’s experiment goes sideways, you can roll back its changes without affecting Agent B’s work.

However, there’s a caveat to keep in mind: checkpoint data under ~/.hermes/checkpoints/ is not automatically pruned. If you run many parallel agents, you might accumulate checkpoint data. It’s a good practice to periodically review and clean up old checkpoints, especially for disposable worktrees.

Cleanup: Keeping Your Repository Tidy

When your parallel experiments are done, you need to clean up. For manually created worktrees, removal is straightforward:

# First, ensure no agent is still running in that worktree
cd ~/projects/my-app
git worktree remove ../my-app-feature

If you have uncommitted changes you want to keep, you’ll need to commit them first or use --force:

git worktree remove --force ../my-app-feature

For Hermes-created worktrees (the ones under .worktrees/), they’re designed to be disposable. When the agent session ends, Hermes typically cleans them up. But if something goes wrong, you can manually remove them:

# List all worktrees
git worktree list

# Remove a stale worktree
git worktree remove .worktrees/agent-session-abc123

# Prune stale worktree metadata
git worktree prune

Best Practices for Production-Ready Parallel AI Workflows

Based on real-world usage, here are the practices that will save you headaches:

1. One worktree per experiment. Never run two different experiments in the same worktree. If you need to test two approaches, create two worktrees. This keeps checkpoint histories clean and rollbacks predictable.

2. Name branches after the experiment. Instead of feature/hermes-experiment, use descriptive names like feature/login-race-fix or experiment/api-pagination. This makes it obvious which branch corresponds to which task when you’re merging.

3. Commit frequently. Even though Hermes manages checkpoints, you should encourage the agent to commit regularly. This creates a Git-level safety net that complements the checkpoint system. A good practice is to have Hermes commit after each logical unit of work.

4. Use -w for one-off tasks, manual worktrees for long-running sessions. If you’re launching a quick fix, -w is perfect. If you’re running a multi-hour refactoring session, a manually created worktree gives you more control and easier cleanup.

5. Monitor your checkpoint storage. Since ~/.hermes/checkpoints/ isn’t auto-pruned, periodically check its size:

du -sh ~/.hermes/checkpoints/

If it’s getting large, you can safely remove old checkpoint directories for experiments you’ve completed.

6. Keep your main branch clean. The whole point of worktrees is to protect your main working directory. Resist the urge to run agents directly on main—always use a worktree, even for small tasks.

A Complete Real-World Example

Let’s put it all together with a realistic scenario. You’re maintaining a web application and need to:

  • Add a new feature (dark mode toggle)
  • Fix a security vulnerability
  • Optimize the build process

Here’s the complete workflow:

# Step 1: Create manual worktrees for long-running tasks
cd ~/projects/my-webapp
git worktree add ../my-webapp-darkmode feature/dark-mode
git worktree add ../my-webapp-security fix/security-vuln

# Step 2: Launch parallel agents in each worktree
# Terminal 1
cd ../my-webapp-darkmode
hermes "Implement dark mode using CSS variables, update all components"

# Terminal 2
cd ../my-webapp-security
hermes "Fix the SQL injection vulnerability in the login endpoint"

# Step 3: Use automatic mode for the quick build optimization
# Terminal 3
cd ~/projects/my-webapp
hermes -w -z "Optimize webpack config for faster builds, reduce bundle size by 30%"

# Step 4: When agents finish, review and merge
git checkout main
git merge feature/dark-mode
git merge fix/security-vuln
# The webpack optimization was a disposable worktree, so it's already cleaned up

# Step 5: Clean up manual worktrees
git worktree remove ../my-webapp-darkmode
git worktree remove ../my-webapp-security

This entire workflow can be completed in minutes, with three AI agents working simultaneously on different aspects of your codebase.

The Bottom Line

Git worktrees transform how you work with AI agents on real projects. They turn Hermes Agent from a single-task tool into a parallel processing powerhouse. Whether you’re running quick experiments with hermes -w -z or orchestrating complex multi-agent workflows with manual worktrees, the isolation they provide means your main codebase stays pristine while AI does its work.

The best part? This isn’t just a theoretical pattern—it’s built directly into Hermes. The -w flag is designed for exactly this use case, and the team at Nous Research has made it seamless. No more worrying about agents overwriting each other’s work or polluting your commit history.

So next time you’re about to launch an agent, ask yourself: should this run in isolation? If the answer is yes—and it usually is—reach for worktrees. Your future self (and your Git history) will thank you.

References

[1] Hermes Agent [2] Hermes treats your current working directory as the project root [3] each worktree gets its own branch, working directory, AND separate Checkpoint Manager history

📖 Related Reads

  • NiteAgent — AI agent development, frameworks, and production patterns
  • CodeIntel Log — code quality, debugging, and software engineering benchmarks
  • ToolBrain — tool reviews, LLM comparisons, and AI workflow guides

Cross-links automatically generated from Hermes Tutorials.