# Hermes Self Update

> Update Hermes Agent and repair Node/npm version drift.

- Skill: `jajabong/hermes-self-update` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jajabong/hermes-self-update`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jajabong/hermes-self-update/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: MIT
- Author: jajabong (https://skillmd.com/u/jajabong)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jajabong/hermes-self-update

---


# Hermes Self-Update

> Pull a new Hermes release, fix the toolchain when `hermes update` reports `npm EBADENGINE`, verify the install.

## When to Use

- User says "update hermes", "upgrade hermes", "跑 hermes update".
- `hermes update` exits 0 but prints `npm error code EBADENGINE` / `Web UI npm install failed` / `Desktop dependency install failed`.
- After a major version bump (0.19 -> 0.20) - Node engine requirement often rises with it.

Don't use for: plugin / skill / cron / OAuth-only changes (those don't need a full update).

## Prerequisites

- macOS with Homebrew (Linux: see "Linux variant" below).
- `~/.hermes/hermes-agent/` is a git checkout.
- A working `git` and `brew` on PATH.

## How to Run

```bash
hermes update                        # auto: pull, reinstall Python deps, refresh model catalog
hermes doctor                        # confirm green
hermes doctor 2>&1 | tail -25        # compact summary
```

If `hermes update` reports any of the warnings below, jump to the matching Procedure.

## Quick Reference

| Symptom | Fix |
|---|---|
| `npm error code EBADENGINE` (Node too old) | Update Node via Homebrew, see Procedure 1 |
| `Web UI npm install failed` | Same root cause - Node version |
| `Desktop dependency install failed` | Same root cause - Node version |
| `npm install failed in repo root` | Same root cause - Node version |
| `Local changes detected - stashing` | Expected; review `git stash list` after update |
| `Gateway PID ... still running after 0.0s` | Normal; launchd forces restart |
| `~1 user-modified (kept)` for bundled skills | Intentional - see `hermes skills list-modified` |

## Procedure 1 - Repair Node/npm version drift on macOS

**Trigger:** `hermes update` shows `EBADENGINE` against `hermes-agent@1.0.0` requiring `node >=22.22.0` (or whatever the package.json declares). Cause: Homebrew installed a newer Node but `/usr/local/bin/node` (often the legacy node@16 installer) shadows it on PATH.

**Check first:**

```bash
which node && node -v && which npm && npm -v
/opt/homebrew/bin/node -v          # what Homebrew actually installed
```

If `which node` returns `/opt/homebrew/bin/node` and version is already >= required, the `hermes update` warning was stale - re-run `hermes update`. Otherwise pick one fix.

### Option A - Brew link only (no sudo)

Works only if no legacy `/usr/local/bin/node` shadows PATH.

```bash
brew unlink node && brew link node
hash -r
node -v && npm -v                   # should now report Homebrew version
```

If `which node` still shows `/usr/local/bin/node`, fall through to Option B.

### Option B - Replace root-owned legacy binary (needs sudo)

The legacy `node` install from `https://nodejs.org/dist/` (the .pkg installer) writes to `/usr/local/bin/` as root and stays on PATH ahead of Homebrew. `brew link --overwrite` cannot remove it.

Give the user the exact commands to run themselves (do NOT run sudo in Queen - it blocks on password):

```bash
sudo rm -f /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack
sudo ln -sf /opt/homebrew/bin/node    /usr/local/bin/node
sudo ln -sf /opt/homebrew/bin/npm     /usr/local/bin/npm
sudo ln -sf /opt/homebrew/bin/npx     /usr/local/bin/npx
sudo ln -sf /opt/homebrew/bin/corepack /usr/local/bin/corepack
hash -r
node -v   # should print the Homebrew version, e.g. v26.7.0
```

After the user confirms:

```bash
hermes update