hermesd: A Read-Only TUI Dashboard for Hermes Agent With Zero Write Access
When Hermes Agent runs at full capacity - gateway handling four messaging platforms, cron jobs firing on schedule, multiple CLI sessions with sub-agents spawning sub-agents, 80-plus MCP tools loaded, 7-plus LLM providers configured - the only way to answer "is everything working?" was to run hermes status, hermes sessions list, hermes cron list, tail log files, and mentally stitch together a picture from five different sources.
hermesd, released today by @mudrii, replaces that workflow with a single terminal command.
What it is
hermesd is a read-only TUI dashboard for Hermes Agent. It reads from ~/.hermes/ and renders 10 live-updating panels in a Rich UI. No config file, no API keys, no network access, zero writes to agent state.
| Panel | What It Shows |
|---|---|
| 1. Gateway | Live gateway PID, Hermes version, update status, per-platform connection dots |
| 2. Sessions | Active/total count, message and tool call totals, parent-session lineage |
| 3. Tokens / Cost | Today's and all-time token usage, estimated ~USD cost, per-model breakdown |
| 4. Tools | Tool call leaders, available tools grid, background processes, checkpoints |
| 5. Config | Model, provider, personality, routing, memory, Tool Gateway settings |
| 6. Cron | Scheduler tick, job table with schedule, delivery target, error count, output summary |
| 7. Skills | Provider auth status, plugins, MCP servers, skills grouped by category with descriptions |
| 8. Logs | Agent, gateway, error, and cron logs with tab switching, filtering, color-coded levels |
| 9. Profiles | Profile discovery with session counts, log freshness, skill counts, DB size, SOUL excerpts |
| 10. Memory | Memory provider, MEMORY.md/USER.md word counts, SOUL.md size and excerpt |
The read-only constraint
The architectural decision that defines hermesd: it never writes to ~/.hermes/ and never imports a line of Hermes Agent code. It operates purely as an observer, reading SQLite databases and log files through read-only interfaces.
This constraint runs through every layer of the implementation:
- Read-only SQLite URIs. The dashboard opens the agent's SQLite databases with
mode=roso even accidental writes are blocked at the filesystem level. - Cache preservation on transient errors. If a log file becomes temporarily unreadable, hermesd keeps displaying the last known good data instead of blanking out. The display never goes dark because of a transient filesystem hiccup.
- WAL-aware snapshots. Hermes Agent uses WAL-mode SQLite, which means uncommitted data is visible to readers. hermesd reads these snapshots without touching the live database, so it sees recent writes without ever participating in the write path.
"The hard constraint that shapes the whole project: hermesd is strictly read-only. It never writes to the agent's data directory and never imports a line of agent code. It's a pure observer - so it can't corrupt the thing it's watching." - @mudrii, June 3, 2026
How it updates
hermesd polls every 5 seconds by default, configurable with --refresh-rate. It reads the full state of ~/.hermes/ on each cycle and diffs against the previous frame. Only changed panels re-render, so the terminal stays responsive even with hundreds of sessions in the database.
For one-shot use, --snapshot renders a single frame to stdout and exits. --snapshot-format json emits the full internal state as JSON for piping into scripts or alerting pipelines. Panel-specific snapshots are available with --snapshot-panel N.
Keyboard navigation
The dashboard is fully keyboard-driven. Pressing 1 through 9 or 0 expands the corresponding panel to full-screen detail. Pressing f toggles between the overview grid and the last selected detail panel.
Detail views add their own controls:
/filters sessions, logs, and skills with field-aware queries (message:term,level:ERROR,minlevel:WARNING)scycles session sorting between recency, cost, and token orderj/kandg/Gscroll through lists and log streamsccopies the current view as plain text via OSC 52Tabswitches between log tabs (agent, gateway, errors, cron)
Layout adaptation
hermesd adapts its layout to the terminal dimensions. On wide terminals, all 10 panels render in a grid. In vertical tmux splits, it switches to a tall-narrow single-column layout. On 80x24 terminals, it uses a denser all-panel overview that fits every section without scrolling.
Health indicators
A footer dot shows how many collector sources succeeded on the last refresh cycle. Green means all sources healthy. Yellow and red surface the names of failed sources inline. When Hermes Agent appears inactive - no recent writes to the database, no running gateway PID - the header and footer display an AGENT OFFLINE warning instead of silently showing stale data.
Release 2026.6.3
The latest release is a security-and-quality update:
- Cleared CVE-2026-45409 by bumping a transitive dependency - lockfile-only, runtime closure untouched
- Refactored the token-summary path to build its validated model once at the boundary instead of mutating it in place, closing a path where Pydantic validation could be skipped
- Added regression tests pinning the three behaviors the refactor had to preserve
The project has 396 tests, uses TDD throughout, supports Python 3.11 through 3.13, and is MIT licensed. It has accumulated 68 GitHub stars since its first commit on April 9, 2026.
Why it matters
Agent observability splits into two categories: the agent's own tools for introspection, and external monitoring that can't interfere. hermes status and hermes sessions list are the first category - they run inside the agent process and can be blocked by a deadlocked session or a hung model call. hermesd is the second category - a separate process that reads files on disk and reports what it finds, regardless of whether the agent is healthy or stuck.
The distinction is practical. If the agent can't respond to hermes status because it's OOM, hermesd still shows you the last session data, the error log tail, and the AGENT OFFLINE warning. You don't need the agent to be alive to know it's dead.
"When you run Hermes Agent seriously - gateway handling Telegram, Discord, Slack, and WhatsApp simultaneously, cron jobs firing reminders, multiple CLI sessions with sub-agents spawning sub-agents, dozens of skills loaded, 7+ LLM providers configured - the information gets scattered fast." - @mudrii, hermesd README
hermesd collapses that information into a single command. It does not replace the Hermes CLI or the Telegram interface. It is the at-a-glance layer that answers "is everything healthy and where are my tokens going" without hunting for data.
[^1]: mudrii. "hermesd 2026.6.3 is out." X. June 3, 2026.
[^2]: mudrii. "hermesd: TUI monitoring dashboard for Hermes AI agent." GitHub. 2026.