hermes-hudui: a browser dashboard for the Hermes agent's persistent memory

What hermes-hudui actually monitors

Hermes is an AI agent with persistent memory. Its state lives on disk, and hermes-hudui is a read-mostly window onto that state: a FastAPI backend plus a browser frontend that serves 19 tabs covering identity, memory, skills, sessions, replay, cron jobs, projects, health diagnostics, costs, model analytics, patterns, corrections, sudo governance, live chat, connected OAuth providers, gateway control, plugin management, and live model capabilities. The README describes it as the browser companion to the hermes-hud TUI, reading the same ~/.hermes/ directory independently. The audience is narrow and specific: someone who already runs Hermes and wants to see what the agent knows about itself. If you have never installed Hermes, this project has nothing to show you, because every tab is derived from agent data rather than from the HUD's own store.

How the HUD reads agent state and pushes updates

The architecture is a local server that reads files and a websocket that pushes changes. The README states the HUD reads ~/.hermes/ and the hermes CLI directly, so it tracks the agent's on-disk layout instead of calling a versioned API. Native filesystem events drive updates by default, which is why the README tells you to set HERMES_HUD_FORCE_POLLING=1 for NFS, WSL1, VM shares, or bind mounts that do not deliver events reliably. That is an honest admission of the failure mode: on those filesystems the dashboard can silently stop reflecting new agent activity until you switch to polling. The README also notes that health reacts to filesystem and WebSocket updates while expensive refresh paths stay throttled, which suggests the design accepts some staleness on costly queries rather than hammering the agent's database on every event.

Installing hermes-hudui and opening the first tab

The README gives a four-step quick start. Clone the repository, run the installer, then launch the CLI, which starts the server on port 3001. The install script is the only setup path documented; there is no pip install of the package itself in the README.

git clone https://github.com/joeynyc/hermes-hudui.git
cd hermes-hudui
./install.sh
hermes-hudui

After that, open http://localhost:3001 in a browser. Requirements listed are Python 3.11+, Node.js 22.12+, and a running Hermes agent with data in ~/.hermes/. On later runs the README shows activating the virtual environment first.

source venv/bin/activate && hermes-hudui

The pyproject.toml confirms the Python floor with requires-python = ">=3.11" and declares the console entry point hermes-hudui = "backend.main:cli", so the command in the README is a real installed script rather than a wrapper. Optional extras exist for the TUI and for chat: pip install 'hermes-hudui[tui]' pulls hermes-hud>=0.5.0, and the chat extra pulls hermes-agent>=0.1.0. The README notes the quotes around 'hermes-hudui[tui]' are required in zsh because the unquoted brackets are treated as a glob. Once the dashboard loads, the executive summary is the sensible first stop: health, spend pulse, top model, provider and gateway risk, highest-cost session, and action items.

Replay exports and what their signatures do not prove

The Replay tab turns agent runs into redacted artifacts you can attach to an issue. Choose a session, inspect the normalized timeline, review the run receipt, then export. The MVP exporter writes local files under ~/.hermes-hud/replays/ and uploads nothing by default. Current local exports are a redacted JSON replay, GitHub-ready Markdown, a standalone HTML replay, a 1200 x 630 PNG share card, and a fork-safe fork.json. Safe Share Mode is the default posture and redacts raw tool arguments, terminal output, assistant reasoning, token-like values, emails, and local paths before writing artifacts. Exports carry local hashes and Ed25519 signatures generated on the machine. The README is explicit that these prove local artifact integrity, not third-party attestation. Treat a signed replay as evidence that a file has not changed since export, not as proof that the run happened as described. Optional remote publishing syncs published replays to a static host through your normal git credentials; it is off by default, syncs only when triggered, and includes only Safe-Share-Mode artifacts.

The local-only security model and its limits

The server binds locally and rejects cross-site browser requests, untrusted WebSocket origins, and non-loopback host access. To bind it to a trusted LAN you pass --host 0.0.0.0 --unsafe-allow-remote, and each browser origin must be added with --allowed-origin. The flag name is the clearest statement of intent in the whole README: the project considers remote binding unsafe. There is no login screen, no session handling, and no TLS in the server itself. The README says to put authentication and TLS in front of the HUD before exposing it beyond a trusted network. For a single developer on a laptop this is fine. For a shared machine, a CI runner, or anything reachable from a network you do not control, the HUD is the wrong tool until you add that front layer yourself. Note also that the Update hermes action is deliberately two-click and shows last-run logs and status, which is a small but real guard against an accidental agent upgrade.

Schema drift is the main compatibility risk

Because the HUD reads the agent's files rather than a stable API, the agent's database schema is the contract. The README states the project is verified against Hermes Agent v0.20.3 with state.db schema v26, with compatibility retained for schemas v16 and v23. Anything outside that set is untested. The Health tab's Agent data layout and Agent schema version checks exist to flag exactly this drift, which is a reasonable design: rather than guessing, the dashboard tells you when its assumptions no longer hold. The practical consequence is that upgrading Hermes can break tabs without any change to hermes-hudui. If you pin the agent version, you inherit that coupling deliberately; if you track the agent's main branch, expect to check the Health tab after each upgrade. The README does not document a migration path or a rollback procedure for the HUD itself.

hermes-hudui versus the hermes-hud TUI

The obvious alternative is hermes-hud, the terminal dashboard from the same author. Both read ~/.hermes/ independently and can run at the same time, so this is not an either-or decision in the usual sense. The difference is scope. The README says the Web UI is fully standalone and adds dedicated Memory, Skills, Sessions, Replay, Health, Providers, Gateway, Model, and Plugins tabs, plus per-model token and cost analytics, gateway managed-tool visibility, actionable diagnostics, a command palette, live chat, and a theme switcher. The TUI is the lighter option for a terminal session; the Web UI is what you install when you want replay export, per-model cost breakdowns, or gateway routing visibility. If you only want a quick status glance, the Web UI's Python plus Node build and browser dependency is more machinery than the job needs.

Licence and upgrade cost

The project is MIT licensed, and pyproject.toml declares license = "MIT" alongside the LICENSE file at the repository root. MIT permits commercial and private use, modification and redistribution provided the copyright notice and licence text are retained; it offers no patent grant and no warranty. Running the HUD internally or forking it does not trigger a copyleft obligation on your own code. The upgrade cost is the schema coupling described above, not the licence. The dependency list is short and mainstream (fastapi, uvicorn[standard], pyyaml, watchfiles, pillow, cryptography), and the frontend requires Node.js 22.12+ to build, so a fresh machine needs both toolchains. The last push to the repository was on 2026-09-04, and the most recent release listed is v0.11.0 from 2026-07-26. The README does not describe a versioned migration process for the HUD's own data; the only persistent state it writes is replays under ~/.hermes-hud/replays/.

Editorial conclusion

Adopt hermes-hudui if you already run a Hermes agent with data in ~/.hermes/ and want to inspect memory, sessions, spend and gateway routing without leaving the browser. Do not adopt it as a general agent UI or a hosted dashboard: it is local-only by default, it has no login screen, and it depends on the agent's on-disk schema rather than a stable API. Before installing, check your Hermes agent version against the stated baseline of v0.20.3 and state.db schema v26, since the Health tab's Agent data layout and Agent schema version checks are what tell you whether the HUD still understands your data.

Frequently asked questions

Official sources

1. Issues
2. joeynyc/hermes-hudui on GitHub
3. License: MIT
4. README
5. Releases