Updating Hermes Desktop from a Fork

Hermes Desktop updates from GitHub release tags, not every new commit on upstream main. When a fork needs to test newer code early, synchronize the source checkout manually.

Confirm the situation

cd ~/.hermes/hermes-agent
git log --oneline -1
git describe --tags --always
git remote -v

Compare the latest release with upstream main. If the release is unchanged but main moved forward, automatic updating is behaving as designed.

Workflow

1. Back up configuration and inspect the workspace

Back up configuration and inspect local changes:

cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak.$(date +%Y%m%d_%H%M%S)
git status --short

Handle local changes first. Generated build output should not be edited or committed manually; commit valuable source changes to your own branch before synchronizing.

2. Fetch upstream

Fetch the official repository, not just your fork:

git fetch upstream main

origin normally points to your fork, while upstream points to the official repository. Running only git pull origin main may leave you on outdated fork code.

3. Merge or rebase

If the fork has no additional commits:

git merge upstream/main --ff-only

If the fork has its own commits, rebase instead:

git rebase upstream/main

Resolve conflicts, stage the files, and run git rebase --continue.

4. Update the virtual environment and verify

Install the editable package and verify it:

./venv/bin/pip3 install -e .
./venv/bin/python3 -m hermes_cli.main --version
./venv/bin/python3 -m hermes_cli.main doctor

Restart Hermes Desktop after the checks pass; an already-running process will not load the new source automatically.

Key conclusions

• No new release means no automatic desktop update; that is expected.
• fetch upstream plus merge/rebase is the core fork-sync workflow.
• User configuration, skills, and sessions are separate from the source checkout, but should still be backed up.
• Extra commits may appear in git describe while the release version remains unchanged.
• Pin a known-good commit and keep a rollback point; git reflog can recover the pre-rebase state.