APEX/BrowserUse_and_ComputerUse_skills
5
0
Fork 0
Code Issues 6 Pull requests 1 Projects 1 Releases Packages Wiki Activity Actions

docs: explain checkpoints, /rollback, and git worktrees

Browse source 
* docs: explain checkpoints, rollback, and git worktrees

* fix: correct hermes -w description — auto-creates worktree, takes no path arg

---------

Co-authored-by: aydnOktay <xaydinoktay@gmail.com>
This commit is contained in:
Teknium 2026-03-15 23:04:07 -07:00 • committed by GitHub
parent 4298c6fd9a
commit aaacab7de7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 353 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

180
website/docs/user-guide/checkpoints-and-rollback.md Normal file
View file

@ -0,0 +1,180 @@
---
sidebar_position: 8
title: "Checkpoints and /rollback"
description: "Filesystem safety nets for destructive operations using shadow git repos and automatic snapshots"
---
# Checkpoints and `/rollback`
Hermes Agent can automatically snapshot your project before **destructive operations** (like file write/patch tools) and restore it later with a single command.
This safety net is powered by an internal **Checkpoint Manager** that keeps a separate shadow git repository under `~/.hermes/checkpoints/` — your real project `.git` is never touched.
## How Checkpoints Work
At a high level:
- Hermes detects when tools are about to **modify files** in your working tree.
- Once per conversation turn (per directory), it:
- Resolves a reasonable project root for the file.
- Initialises or reuses a **shadow git repo** tied to that directory.
- Stages and commits the current state with a short, human‑readable reason.
- These commits form a checkpoint history that you can inspect and restore via `/rollback`.
Internally, the Checkpoint Manager:
- Stores shadow repos under:
- `~/.hermes/checkpoints/<hash>/`
- Keeps metadata about:
- The original working directory (`HERMES_WORKDIR` file in the shadow repo).
- Excluded paths such as:
- `node_modules/`, `dist/`, `build/`
- `.venv/`, `__pycache__/`, `*.pyc`
- `.git/`, `.cache/`, `.pytest_cache/`, etc.
The agent creates **at most one checkpoint per directory per turn**, so long running sessions do not spam snapshots.
```mermaid
flowchart LR
user["User command\n(hermes, gateway)"]
agent["AIAgent\n(run_agent.py)"]
tools["File tools\n(write/patch)"]
cpMgr["CheckpointManager"]
shadowRepo["Shadow git repo\n~/.hermes/checkpoints/<hash>"]
user --> agent
agent -->|"tool call"| tools
tools -->|"before mutate\nensure_checkpoint()"| cpMgr
cpMgr -->|"git add/commit"| shadowRepo
cpMgr -->|"OK / skipped"| tools
tools -->|"apply changes"| agent
```
## Enabling Checkpoints
Checkpoints are controlled by a simple on/off flag and a maximum snapshot count **per directory**:
- `checkpoints_enabled` – master switch
- `checkpoint_max_snapshots` – soft cap on history depth per directory
You can configure these in `~/.hermes/config.yaml`:
```yaml
agent:
checkpoints_enabled: true
checkpoint_max_snapshots: 50
```
Or via CLI flags (exact wiring may depend on your version of the CLI):
```bash
hermes --checkpoints
# or
hermes chat --checkpoints
```
When disabled, the Checkpoint Manager is a no‑op and never attempts git operations.
## Listing Checkpoints
Hermes exposes an interactive way to list checkpoints for the current working directory.
From the CLI session where you are working on a project:
```bash
# Ask Hermes to show checkpoints for the current directory
/rollback
```
Hermes responds with a formatted list similar to:
```text
📸 Checkpoints for /path/to/project:
1. a1b2c3d 2026-03-13 10:24 auto: before apply_patch
2. d4e5f6a 2026-03-13 10:15 pre-rollback snapshot (restoring to a1b2c3d0)
Use /rollback <number> to restore, e.g. /rollback 1
```
Each entry shows:
- Short hash
- Timestamp
- Reason (commit message for the snapshot)
## Restoring with `/rollback`
Once you have identified the snapshot you want to go back to, use `/rollback` with the number from the list:
```bash
# Restore to the most recent snapshot
/rollback 1
```
Behind the scenes, Hermes:
1. Verifies the target commit exists in the shadow repo.
2. Takes a **pre‑rollback snapshot** of the current state so you can “undo the undo” later.
3. Runs `git checkout <hash> -- .` in the shadow repo, restoring tracked files in your working directory.
On success, Hermes responds with a short summary like:
```text
✅ Restored /path/to/project to a1b2c3d
Reason: auto: before apply_patch
```
If something goes wrong (missing commit, git error), you will see a clear error message and details will be logged.
## Safety and Performance Guards
To keep checkpointing safe and fast, Hermes applies several guardrails:
- **Git availability**
- If `git` is not found on `PATH`, checkpoints are transparently disabled.
- A debug log entry is emitted, but your session continues normally.
- **Directory scope**
- Hermes skips overly broad directories such as:
- Root (`/`)
- Your home directory (`$HOME`)
- This prevents accidental snapshots of your entire filesystem.
- **Repository size**
- Before committing, Hermes performs a quick file count.
- If the directory has more than a configured threshold (e.g. `50,000` files),
checkpoints are skipped to avoid large git operations.
- **No‑change snapshots**
- If there are no changes since the last snapshot, the checkpoint is skipped
instead of committing an empty diff.
All errors inside the Checkpoint Manager are treated as **non‑fatal**: they are logged at debug level and your tools continue to run.
## Where Checkpoints Live
By default, all shadow repos live under:
```text
~/.hermes/checkpoints/
├── <hash1>/ # shadow git repo for one working directory
├── <hash2>/
└── ...
```
Each `<hash>` is derived from the absolute path of the working directory. Inside each shadow repo you will find:
- Standard git internals (`HEAD`, `refs/`, `objects/`)
- An `info/exclude` file containing a curated ignore list
- A `HERMES_WORKDIR` file pointing back to the original project root
You normally never need to touch these manually; they are documented here so advanced users understand how the safety net works.
## Best Practices
- **Keep checkpoints enabled** for interactive development and refactors.
- **Use `/rollback` instead of `git reset`** when you want to undo agent‑driven changes only.
- **Combine with Git branches and worktrees** for maximum safety:
- Keep each Hermes session in its own worktree/branch.
- Let checkpoints act as an extra layer of protection on top.
For running multiple agents in parallel on the same repo without interfering with each other, see the dedicated guide on [Git worktrees](./git-worktrees.md).

173
website/docs/user-guide/git-worktrees.md Normal file
View file

@ -0,0 +1,173 @@
---
sidebar_position: 9
title: "Git Worktrees"
description: "Run multiple Hermes agents safely on the same repository using git worktrees and isolated checkouts"
---
# Git Worktrees
Hermes Agent is often used on large, long‑lived repositories. When you want to:
- Run **multiple agents in parallel** on the same project, or
- Keep experimental refactors isolated from your main branch,
Git **worktrees** are the safest way to give each agent its own checkout without duplicating the entire repository.
This page shows how to combine worktrees with Hermes so each session has a clean, isolated working directory.
## Why Use Worktrees with Hermes?
Hermes treats the **current working directory** as the project root:
- CLI: the directory where you run `hermes` or `hermes chat`
- Messaging gateways: the directory set by `MESSAGING_CWD`
If you run multiple agents in the **same checkout**, their changes can interfere with each other:
- One agent may delete or rewrite files the other is using.
- It becomes harder to understand which changes belong to which experiment.
With worktrees, each agent gets:
- Its **own branch and working directory**
- Its **own Checkpoint Manager history** for `/rollback`
See also: [Checkpoints and /rollback](./checkpoints-and-rollback.md).
## Quick Start: Creating a Worktree
From your main repository (containing `.git/`), create a new worktree for a feature branch:
```bash
# From the main repo root
cd /path/to/your/repo
# Create a new branch and worktree in ../repo-feature
git worktree add ../repo-feature feature/hermes-experiment
```
This creates:
- A new directory: `../repo-feature`
- A new branch: `feature/hermes-experiment` checked out in that directory
Now you can `cd` into the new worktree and run Hermes there:
```bash
cd ../repo-feature
# Start Hermes in the worktree
hermes
```
Hermes will:
- See `../repo-feature` as the project root.
- Use that directory for context files, code edits, and tools.
- Use a **separate checkpoint history** for `/rollback` scoped to this worktree.
## Running Multiple Agents in Parallel
You can create multiple worktrees, each with its own branch:
```bash
cd /path/to/your/repo
git worktree add ../repo-experiment-a feature/hermes-a
git worktree add ../repo-experiment-b feature/hermes-b
```
In separate terminals:
```bash
# Terminal 1
cd ../repo-experiment-a
hermes
# Terminal 2
cd ../repo-experiment-b
hermes
```
Each Hermes process:
- Works on its own branch (`feature/hermes-a` vs `feature/hermes-b`).
- Writes checkpoints under a different shadow repo hash (derived from the worktree path).
- Can use `/rollback` independently without affecting the other.
This is especially useful when:
- Running batch refactors.
- Trying different approaches to the same task.
- Pairing CLI + gateway sessions against the same upstream repo.
## Cleaning Up Worktrees Safely
When you are done with an experiment:
1. Decide whether to keep or discard the work.
2. If you want to keep it:
- Merge the branch into your main branch as usual.
3. Remove the worktree:
```bash
cd /path/to/your/repo
# Remove the worktree directory and its reference
git worktree remove ../repo-feature
```
Notes:
- `git worktree remove` will refuse to remove a worktree with uncommitted changes unless you force it.
- Removing a worktree does **not** automatically delete the branch; you can delete or keep the branch using normal `git branch` commands.
- Hermes checkpoint data under `~/.hermes/checkpoints/` is not automatically pruned when you remove a worktree, but it is usually very small.
## Best Practices
- **One worktree per Hermes experiment**
- Create a dedicated branch/worktree for each substantial change.
- This keeps diffs focused and PRs small and reviewable.
- **Name branches after the experiment**
- e.g. `feature/hermes-checkpoints-docs`, `feature/hermes-refactor-tests`.
- **Commit frequently**
- Use git commits for high‑level milestones.
- Use [checkpoints and /rollback](./checkpoints-and-rollback.md) as a safety net for tool‑driven edits in between.
- **Avoid running Hermes from the bare repo root when using worktrees**
- Prefer the worktree directories instead, so each agent has a clear scope.
## Using `hermes -w` (Automatic Worktree Mode)
Hermes has a built‑in `-w` flag that **automatically creates a disposable git worktree** with its own branch. You don't need to set up worktrees manually — just `cd` into your repo and run:
```bash
cd /path/to/your/repo
hermes -w
```
Hermes will:
- Create a temporary worktree under `.worktrees/` inside your repo.
- Check out an isolated branch (e.g. `hermes/hermes-<hash>`).
- Run the full CLI session inside that worktree.
This is the easiest way to get worktree isolation. You can also combine it with a single query:
```bash
hermes -w -q "Fix issue #123"
```
For parallel agents, open multiple terminals and run `hermes -w` in each — every invocation gets its own worktree and branch automatically.
## Putting It All Together
- Use **git worktrees** to give each Hermes session its own clean checkout.
- Use **branches** to capture the high‑level history of your experiments.
- Use **checkpoints + `/rollback`** to recover from mistakes inside each worktree.
This combination gives you:
- Strong guarantees that different agents and experiments do not step on each other.
- Fast iteration cycles with easy recovery from bad edits.
- Clean, reviewable pull requests targeted at v0.2.0’s new capabilities.