hermes-hud: a terminal dashboard that reads an agent's own state

Reading the agent's data directory instead of wrapping the agent

hermes-hud describes itself as a consciousness monitor for AI agents: a terminal dashboard that watches an agent think, its memory, its mistakes, its growth over time. It is built for Hermes, the AI assistant with persistent memory.

The mechanism is the interesting part. There is no SDK hook, no plugin API and no monkey patching of the agent. The tool reads from ~/.hermes and surfaces what the agent knows about itself: conversations held, skills acquired, mistakes corrected, memory capacity, tool usage patterns, active projects. Every value comes from the agent's own data files, so the dashboard reflects the state of one particular agent rather than some average.

That constraint shapes everything. hermes-hud can only report what is written down, so a conversation that was never persisted leaves no trace in the HUD, and a mistake the agent never recorded on disk never appears in the corrections log. The output is a view of the agent's memory of itself, which is one layer removed from the agent's behaviour.

The interface is a Textual application. The dependency list is short: textual>=1.0.0 for the TUI and pyyaml>=6.0 for configuration, with pyfiglet>=1.0 as an optional extra named neofetch for the ASCII banner art. The console entry point is hermes_hud.hud:main, exposed on the command line as hermes-hud.

Nine tabs, from corrections log to prompt patterns

The feature list covers a lot of ground for a terminal program, and the tabs are the unit of organisation.

A dashboard tab is the default view. A corrections log records every mistake the agent made and what it learned from it, which is the closest thing in the project to an audit trail and, for most users, the reason to install it at all. Growth tracking compares snapshot diffs to show what changed since yesterday. A cron monitor lists scheduled jobs along with their execution history.

Then there is a project tracker that reports the git repositories the agent works on, the languages used and uncommitted changes. Health checks cover API keys, running services and gateway status at a glance. A profiles tab lists all agent profiles with model, backend, memory, session stats and service status.

Two tabs are more unusual. The tmux operator view maps live agents to panes and adds jump hints plus an operator queue for approvals and errors. Prompt patterns does task clustering, repeated request detection, peak hours and common tool chains, which is a usage-analytics view of the prompts the agent receives.

Keyboard navigation is minimal and predictable: 1 to 9 switch tabs, j and k scroll, g and G jump to top and bottom, r refreshes data, q quits. Colour themes are chosen from the command palette with ctrl+p, with Neural Awakening in blues and cyans as the default, plus Blade Runner, fsociety and Digital Soul.

Installing on macOS and Linux with Python 3.11

The requirements are Python 3.11 or newer, and the project states it works on macOS and Linux. There is no Windows support mentioned anywhere in the documentation, which is worth knowing if that is your platform.

The install is a clone, a virtual environment and an editable install.

git clone https://github.com/joeynyc/hermes-hud.git
cd hermes-hud
python3.11 -m venv venv
source venv/bin/activate
pip install -e .

Note that pip install -e . alone gives you the core dashboard. The ASCII neofetch banners need the optional extra, which the Makefile dev target installs.

make dev

That target runs the editable install with the neofetch extra, so pyfiglet comes along with it. The Makefile also offers install, venv, clean and test, with the interpreter overridable through the PYTHON variable, and the test target runs pytest against tests/.

For contributors the documented sequence is the same clone and virtual environment setup, then make dev, then pytest tests/ -v.

If the agent does not live in the default place, three environment variables adjust the behaviour.

Three variables adjust the behaviour. The default for HERMES_HOME is ~/.hermes, the default for HERMES_HUD_PROJECTS_DIR is ~/projects, and HERMES_HUD_NOBOOT is unset by default.

HERMES_HOME points at the agent data directory, HERMES_HUD_PROJECTS_DIR is the directory scanned for git repositories, and HERMES_HUD_NOBOOT skips the boot animation, which matters when the tool runs in a script.

Non-interactive output for scripts and status checks

The command line accepts a set of flags, and the most useful one for automation is --text, which prints a text summary to stdout instead of opening the interactive interface.

hermes-hud              # Interactive TUI
hermes-hud --text       # Text summary to stdout
hermes-hud --snapshot   # Save a snapshot for diff tracking
hermes-hud --ai         # AI awakening neofetch
hermes-hud --br         # Blade Runner neofetch
hermes-hud --fsociety   # Mr. Robot neofetch
hermes-hud --anime      # Mewtwo ASCII art neofetch
hermes-hud --help       # Show all options

The snapshot flag pairs with the growth tracking feature. Saving a snapshot writes a point in time, and later runs diff against what was stored, which is how the tool can say what changed since yesterday. Snapshot writing is explicit rather than automatic, so the resolution of the diff depends on how often you invoke it.

The four neofetch variants print a themed banner, and these are the paths that depend on pyfiglet. On a base install without the neofetch extra, those flags are the ones most likely to fail, which is another reason to use make dev rather than a bare pip install -e ..

The themed boot screen with its gradient ANSI art intro is skipped entirely when HERMES_HUD_NOBOOT is set, so scripted runs do not pay for the animation.

What hermes-hud cannot do, and where a different tool fits

The limits are structural rather than accidental. This is a read and report tool. Nothing in the nine tabs approves anything, pauses anything or redirects an agent, and the tmux operator view, despite its name, surfaces an operator queue for approvals and errors rather than resolving them.

It also depends on the shape of the agent's data. If a Hermes deployment keeps its state in a database, in a remote service or in a non-default layout, the directory scan will find nothing, and the only supported way to point the tool elsewhere is HERMES_HOME. The same applies to project detection, which is a scan of HERMES_HUD_PROJECTS_DIR rather than a lookup of what the agent is actually working on.

The alternative approach is to instrument the agent at runtime instead of reading its files afterwards. A wrapper that logs each request, tool call and token of context as it happens gives you live truth, at the cost of touching the agent's execution path and accepting that instrumentation can perturb what you are measuring. hermes-hud takes the opposite trade: no coupling to the agent's internals and no risk of altering behaviour, but only what was already persisted and only after the fact.

If you need per-request cost accounting, prompt history at full fidelity or intervention in a running agent, a runtime wrapper or the agent's own event log fits better. If you want a readable picture of what the agent has learned and how it is changing, hermes-hud is the faster path.

Release history, alpha status and MIT licensing

Three tagged releases are visible, all within a single week in early April 2026: v0.3.0 on 2026-04-04 adding the profiles tab, v0.4.0 on 2026-04-06 adding the tmux operator view, and v0.5.0 on 2026-04-06 adding prompt patterns. The last push was on 2026-07-05, so the tree has seen work since the newest tag without a further release being cut.

The package metadata classifies the project as Development Status :: 3 - Alpha and lists Python 3.11, 3.12 and 3.13 as supported. Alpha status in this ecosystem means the interface may change between releases, and the release naming suggests features arrive as discrete visible additions rather than as refinements.

Licensing is MIT, a permissive licence with attribution requirements and no copyleft obligations. That carries no legal advice, but it does mean a fork can be modified and redistributed with the notice preserved.

Because the release line is short and the project is young, upgrading is mostly a matter of pulling and reinstalling, and there is no documented upgrade procedure or migration guide for saved snapshots. The CHANGELOG.md file in the repository holds the version history.

Editorial conclusion

hermes-hud suits someone running a Hermes agent on a workstation who wants to see memory growth, repeated corrections and scheduled job history without leaving the terminal, and the non-interactive mode makes it usable from a status script. It does not suit anyone whose Hermes data lives outside the directory the tool scans by default, since HERMES_HOME, HERMES_HUD_PROJECTS_DIR and HERMES_HUD_NOBOOT are the only knobs exposed, and it is not a governance tool, because nothing in the nine tabs can approve, pause or redirect an agent. Before adopting it, point HERMES_HOME at your real agent directory, run hermes-hud --text once to confirm it finds data, and check the project version, which the package metadata lists as 0.5.0 with a Development Status of 3 - Alpha.

Frequently asked questions

Official sources

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