Keryx
A live visual activity monitor for Hermes Agent.
Keryx reads the agent's own records (its SQLite state, cron store and logs) without touching them, and turns them into a 3D force-graph dashboard where shape, colour and position carry meaning. It runs as a small container beside Hermes and serves a web page on port 9120.
Named after κῆρυξ, the Greek herald who carried messages for Hermes. Keryx is an open-source project of Aflux Systems LLC. Website: https://rafreid.github.io/keryx/
- Read-only. Keryx opens Hermes' files, never writes them, and never talks to the agent.
- Live. A server-sent-events stream pushes an update whenever a Hermes file changes; every panel refreshes on that one clock.
- One rule for the picture. Shape says what a thing is, colour says how it is doing, position says when it started.
- Triage first. The attention list is grouped into needs action, watch and info, says since when, and every line leads to the node or the tab that explains it.
- Honest about liveness. A strip under the header says when Keryx last heard from the backend and goes amber, then red, within half a minute of the backend going away. It never shows "live" over a dead connection.
- Works on a phone, from the keyboard, in both themes. The graph and the panel take turns at full width; every card, row and section is a real control; light and dark are both designed, not inverted; reduced motion is honoured.
Screenshots
All screenshots are taken from the synthetic fixture the tests use, never from a real install.
| |
|---|
| |
| A selected session: status, request, latest step and context, then the trace as turns. | The kanban board, read-only, with a card open. |
| |
| Analytics: insights, momentum, cache trend, provider mix, when Hermes works. | Tasks: delegations, scheduled jobs, incidents, the delivery queue. |
| |
| Logs: every file Hermes writes, filtered by level; session-tagged lines link to their session. | The light theme: every accent reads at 5:1 or better. |
What's new in 2.9
2.9 is a graph release that came out of a visual and interaction review of the 3D view (14 findings, all addressed). Nothing changed in what Keryx reads; the picture got honest colours, legible labels and depth. 2.8's usability changes are in the changelog.
- Colours that mean one thing. A running session is green even while it is busy: "active" (touched in the last 5 min) is now a halo ring and link particles, not a red fill that read as failure. Every node and link colour is a CSS token with a light-theme value that clears 3:1 on the page, where the old dark-theme hexes fell to 1.3:1. Switching theme repaints the 3D background too.
- Labels you can read. Text stays about 11 px on screen at any zoom. The overview labels the hub, the platforms, running and waiting sessions and the newest four; everything is labelled when you zoom in; a label that would overprint another is hidden; nothing outside the hovered or selected neighbourhood keeps one. Tool labels say
write_file ×3 · 1 failed.
- Depth in the 3D view. A thin stem drops from every session to the floor ring, so height (start time) reads at any angle; the overview sits at 42° instead of 31°; a ring marks the selected node; fog follows the camera distance so what is behind the structure fades a little at every zoom.
- A tighter frame and a lit hub. The overview fits the sessions and platforms to 62 % of the canvas instead of 40 %. The hub is accent-coloured in both themes, where it used to be a black sphere on the light page.
- Phone map. The map refits when the phone rotates or the panel is resized, labels only the sessions that matter when zoomed out, and the history trail stays out of the way (the browser's back button does the same job).
- Less work per frame. Label textures are redrawn only when their size or colour changes, instead of twice per label per frame; the 2D canvas pauses its loop under reduced motion.
Quick start
You need a Hermes Agent install whose data directory you can read, on the same machine, and Docker. A prebuilt image is published for every release, so Node is not required. (Python 3.11+ works without Docker, but that path builds the front end from source and needs Node 18+ once.)
Nothing to clone: run the published image against your Hermes data directory (~/.hermes for a native install; for Hermes in Docker use the host directory you mount at /opt/data and the uid that owns it, see Doing it by hand):
This is the beginning of the README. Read the rest at the original. Read the full README ↗
