Best Practices — 10 Tips

Think of Hermes Agent like a chef in a busy kitchen. You wouldn’t let every cook chop vegetables on the same cutting board while also plating desserts — you’d give each one their own station. The same logic applies to your codebase.

---

1. One Worktree Per Experiment

Imagine you’re painting a house. You wouldn’t paint the living room and the bathroom at the same time with the same brush — you’d mess both up. Git worktrees let you give each Hermes task its own “room” to work in.

Instead of letting Hermes edit files directly in your main project folder, create a separate workspace for each experiment. This keeps your main code safe and your changes tidy.

2. Name Branches After the Experiment

Give your branches clear, descriptive names so you (and future you) know what each one is for:

git checkout -b feature/hermes-checkpoints-docs

Not branch-1 or test-fix. Be specific — you’ll thank yourself later.

3. Commit Frequently

Think of commits like saving your progress in a video game. You don’t want to play for three hours and then lose everything because you didn’t save.

Commit at high-level milestones:

git add .
git commit -m "Add checkpoint documentation"

For smaller, tool-driven edits in between, use Hermes’ checkpoints and /rollback as a safety net.

4. Avoid Running from the Bare Repo Root

When using worktrees, don’t run Hermes from the original repo folder. Instead, cd into the worktree directory. This gives each agent a clear scope and prevents accidental cross-contamination.

5. Use hermes -w for Automatic Worktrees

Don’t want to set up worktrees manually? Hermes has a built-in shortcut:

cd /path/to/your/repo
hermes -w

This automatically creates a disposable worktree with its own branch. You can even combine it with a single query:

hermes -w -z "Fix issue #123"

6. Run Parallel Agents Safely

Want multiple Hermes agents working at once? Just open several terminals and run hermes -w in each. Every session gets its own isolated worktree and branch automatically. No more agents stepping on each other’s toes.

7. Use Checkpoints + /rollback

Mistakes happen. That’s okay. Hermes lets you create checkpoints during a session and roll back to them if something goes wrong. It’s like having an “undo” button for your agent’s actions.

8. Combine Worktrees, Branches, and Checkpoints

Here’s the winning formula:

• Worktrees = clean checkouts for each session
• Branches = high-level history of experiments
• Checkpoints + /rollback = quick recovery from mistakes

Together, they give you fast iteration, easy recovery, and clean pull requests.

9. Handle UI Development Smartly

If you’re working on the TUI or desktop app across multiple worktrees, you’ll need node_modules for each. That’s a lot of duplicated files. Check out the htui / hgui helpers that share one install by symlink — it saves disk space and setup time.

10. Keep Your Main Branch Clean

The whole point of these practices is to keep your main branch stable and production-ready. Only merge worktree branches when they’re tested and complete.

---

Summary

Think of worktrees as separate desks in an office. Each Hermes agent gets its own desk with its own tools, so nobody messes up someone else’s work. Branches are your filing system, and checkpoints are your sticky notes for “I was here.”

Practical tip: Start with just hermes -w for your next task. It’s the easiest way to get isolation without any manual setup. Once you’re comfortable, add checkpoints and rollback into your workflow. You’ll wonder how you ever worked without them.