hermes-hudui: A Browser Dashboard for a Hermes Agent's On-Disk State
Web UI consciousness monitor for Hermes — the AI agent with persistent memory
At a glance
- What is it?
- hermes-hudui reads ~/.hermes/ and the hermes CLI directly, then serves 19 tabs of memory, cost, gateway and replay data over a local-only WebSocket. It is a read-only window onto agent state, not a control plane, and it pins its expectations to specific state.db schema versions.
- Who is it for?
- Adopt hermes-hudui if you already run a Hermes agent and want to inspect memory, sessions, spend and gateway routing without a terminal, and if your state.db schema is v16, v23 or v26. Do not adopt it as an agent control plane or as a hosted multi-user service: it is local-only by default, and the README states that authentication and TLS belong in front of it before any exposure.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 11 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills: agent state you cannot see from the terminal
A Hermes agent keeps persistent memory, so its behaviour drifts over time in ways that are hard to attribute from a chat transcript alone. hermes-hudui exists to make that state visible. The README frames it as a browser companion to the earlier hermes-hud TUI, reading the same data directory independently. Both tools can run against ~/.hermes/ at the same time, which tells you the design assumes no locking and no single writer.
The intended user is someone already running Hermes who wants to answer questions like: which session cost the most, whether web search is routed through Nous Tool Gateway or a direct key, which plugins are loaded and what auth commands they need, and what the agent's cron jobs and corrections look like. The README lists 19 tabs, including Memory, Skills, Sessions, Replay, Health, Providers, Gateway, Model and Plugins, several of which the TUI does not have. The Dashboard opens with an executive summary covering health, spend pulse, top model, provider and gateway risk, highest-cost session, and action items.
That is a narrower audience than a general observability tool. If you do not run Hermes, or your agent has no data in ~/.hermes/, there is nothing here for you to look at.
How the HUD reads the agent: filesystem first, WebSocket second
The mechanism is direct file and process access rather than an agent-side API. The README states that the HUD reads ~/.hermes/ and the hermes CLI directly, so it tracks the agent's on-disk layout. That choice explains both the tool's reach and its fragility: it can show fields the agent never exposes over a network interface, but it breaks when the layout changes underneath it.
The README is explicit about version pinning. The release is verified against Hermes Agent v0.20.3 with state.db schema v26, and compatibility is retained for schemas v16 and v23. Two checks in the Health tab, Agent data layout and Agent schema version, flag when your agent's data drifts from that baseline. Read that as the project's own admission that schema drift is the primary failure mode.
Updates arrive in real time over WebSocket, so no manual refresh is required. The README notes that Health reacts to filesystem and WebSocket updates while expensive refresh paths stay throttled, which implies the polling and event paths are budgeted separately rather than treated uniformly. Native filesystem events are the default; polling is the fallback, controlled by an environment variable described below.
Running it: install.sh, port 3001, and the two environment switches that matter
The Quick Start is four commands. Clone the repository, change into it, run ./install.sh, then run hermes-hudui, and open http://localhost:3001. Requirements are Python 3.11+, Node.js 22.12+, and a running Hermes agent with data in ~/.hermes/. On later runs the README gives source venv/bin/activate && hermes-hudui.
Two environment and flag details are worth pulling out because they change behaviour rather than cosmetics. First, HERMES_HUD_FORCE_POLLING=1 forces polling instead of native filesystem events, and the README recommends it for NFS, WSL1, VM shares, or bind mounts that do not deliver events reliably. Without it, on those filesystems, the live-update behaviour the tool advertises is the part that will quietly stop working. Second, the server is local-only by default and rejects cross-site browser requests, untrusted WebSocket origins, and non-loopback host access. Binding to a LAN is a deliberate opt-in: --host 0.0.0.0 --unsafe-allow-remote, with each browser origin added via --allowed-origin https://hud.example.test. The flag name itself signals intent.
There is also an optional TUI integration: pip install 'hermes-hudui[tui]'. The README notes the quotes are required in zsh, where unquoted [tui] is interpreted as a glob pattern, and that bash and fish accept the unquoted form.
Replay: redaction and local signing, with a clear integrity boundary
Replay is the most opinionated feature and the one with the most caveats. It turns agent runs into redacted, shareable artifacts. The workflow is: open the Replay tab, choose a session, inspect the normalized timeline, review the run receipt, then export. The MVP exporter writes local files under ~/.hermes-hud/replays/ and does not upload anything by default.
Exports come in five forms: redacted JSON, GitHub-ready Markdown, standalone HTML, a 1200 x 630 PNG share card, and a fork-safe fork.json. Safe Share Mode is the default export posture and redacts raw tool arguments, terminal output, assistant reasoning, token-like values, emails and local paths before anything is written. That default matters, because the artifacts are designed to be attached to issues and PRs.
The signing claim deserves careful reading. Exports include local hashes and Ed25519 signatures generated on this machine, and the README states plainly that they prove local artifact integrity, not external third-party attestation. That is an unusually honest boundary. If you need provenance that a third party can verify independently, this does not provide it.
Remote publishing is optional and off by default. You configure a git repository (owner/name for GitHub Pages, or any git URL) and a branch in the Remote Publishing panel, then press Sync now. The sync builds a static site from published replays, listing public ones on a gallery index and making unlisted ones reachable only through an unguessable hash path, then pushes with your normal git credentials. Only Safe-Share-Mode artifacts are ever included, and the README states that local filesystem paths and publish manifests never leave the machine. Note that the unguessable-path model for unlisted replays is obscurity, not access control.
Where it is the wrong tool
The first limitation is the schema coupling. Supporting v16, v23 and v26 is a maintenance commitment, and the Health tab checks exist precisely because the project cannot guarantee forward compatibility. If your agent is on a schema newer than v26, the README does not claim support, and the honest expectation is that tabs reading state.db fields may show incomplete or incorrect data rather than failing loudly.
The second is the security posture. Local-only by default is the right default, but it also means hermes-hudui is not a multi-user dashboard. The README instructs you to put authentication and TLS in front of the HUD before exposing it beyond a trusted network. There is no built-in user model described. If your requirement is a shared dashboard for a team, this is not that product.
The third is platform scope. macOS, Linux and WSL are listed. WSL1 appears in the list of filesystems needing forced polling, which is a hint that WSL support is functional rather than first-class. And the fourth: with 19 tabs, this is a broad surface, and the README does not describe a permissions model distinguishing read actions from the enable, disable, update and Update hermes actions. The Update hermes action is described as deliberately two-click with last-run logs and status, which is a mitigation, not an authorization boundary.
The alternative: the hermes-hud TUI, and what actually differs
The obvious alternative is the project's own sibling, hermes-hud, the terminal UI. The difference is not cosmetic. Both read ~/.hermes/ independently, so neither owns the data, and you can run both simultaneously. The Web UI is described as fully standalone and adds tabs the TUI lacks: Memory, Skills, Sessions, Replay, Health, Providers, Gateway, Model and Plugins, plus per-model token and cost analytics, gateway managed-tool visibility, actionable diagnostics, a command palette, live chat and a theme switcher.
So the choice is between a terminal tool and a browser tool over the same data, with the browser side carrying the newer feature work. If you work over SSH on a headless box, the TUI avoids the Node.js 22.12+ requirement and the port-3001 binding question entirely. If you want the Replay export pipeline, the plugin hub, or the gateway routing view, those are Web UI features and the README does not describe equivalents in the TUI.
A second alternative worth naming is simply reading ~/.hermes/ yourself. Because the HUD is a read-only view over files and a CLI, a script that parses state.db gets you the raw data without the schema-compatibility contract. What you give up is the normalized timeline, the redaction pipeline, and the executive summary that precomputes which session cost the most.
Maintenance cost and the MIT licence
The release cadence visible in the repository is roughly monthly: v0.9.1 in June 2026, v0.10.0 in late June, v0.11.0 in late July, with the last push to main in early September 2026. That is a project that is still moving, which cuts both ways. Fixes arrive, and so do layout assumptions.
Upgrade cost is concentrated in one place: the Hermes agent's state.db schema. Every schema bump on the agent side is a potential breakage on the HUD side, and the Health tab's schema and data-layout checks are the mechanism for detecting it before you trust a tab's numbers. Budget for checking those two Health checks after any agent upgrade, not after any HUD upgrade. The Node.js 22.12+ floor is a second, quieter cost: it is a runtime you must maintain alongside the Python virtualenv that install.sh creates.
On licensing, the repository is MIT, which permits commercial and private use and modification with the licence and copyright notice retained. That is a statement about the repository's terms as given, not legal advice, and it says nothing about the Hermes agent itself, which is a separate project with its own terms. If you plan to redistribute the HUD or bundle it into a product, read the LICENSE file in the repository rather than relying on the one-word summary.
Editorial conclusion
Adopt hermes-hudui if you already run a Hermes agent and want to inspect memory, sessions, spend and gateway routing without a terminal, and if your state.db schema is v16, v23 or v26. Do not adopt it as an agent control plane or as a hosted multi-user service: it is local-only by default, and the README states that authentication and TLS belong in front of it before any exposure. Verify your schema version and agent data layout in the Health tab first, and check whether your filesystem delivers native events, because on NFS, WSL1, VM shares or bind mounts you will need HERMES_HUD_FORCE_POLLING=1.
Community notes