diff --git a/website/docs/user-guide/checkpoints-and-rollback.md b/website/docs/user-guide/checkpoints-and-rollback.md new file mode 100644 index 0000000000..a7a34115f4 --- /dev/null +++ b/website/docs/user-guide/checkpoints-and-rollback.md @@ -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//` +- 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/"] + + 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 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 -- .` 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/ + ├── / # shadow git repo for one working directory + ├── / + └── ... +``` + +Each `` 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). + diff --git a/website/docs/user-guide/git-worktrees.md b/website/docs/user-guide/git-worktrees.md new file mode 100644 index 0000000000..cc5c641f18 --- /dev/null +++ b/website/docs/user-guide/git-worktrees.md @@ -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-`). +- 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. +