rafreid/keryx

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. One ranked attention list says what needs a look, and every line leads to the node or the tab that explains it.
• Works on a phone, in both themes. The graph and the panel take turns at full width; light and dark are both designed, not inverted.

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, 2D view.

Quick start

You need a Hermes Agent install whose data directory you can read, and either Docker or Python 3.11+. Node is not required: a prebuilt image is published for every release.

git clone https://github.com/rafreid/keryx.git
cd keryx
./quickstart.sh

Then open http://localhost:9120/.

The script finds your Hermes data directory (~/.hermes for a native install, /opt/hermes-data or /opt/data for the Docker install), works out which user owns it, pulls the Keryx image and starts it with Docker Compose. Without Docker it falls back to a Python virtualenv. Options:

Doing it by hand

Docker. Hermes keeps its data directory mode 0700, so Keryx must run as the user that owns it. For a native install that is you; for the official Hermes container it is the HERMES_UID/HERMES_GID you gave it (default 10000).

# native Hermes install, data in ~/.hermes
HERMES_HOME=~/.hermes HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d

# Hermes in Docker with its data at /opt/hermes-data, owned by uid 10000
HERMES_HOME=/opt/hermes-data docker compose up -d

If Hermes already runs from a compose file, paste the keryx service from docker-compose.yml into it and mount the same host directory you give Hermes. The image is ghcr.io/rafreid/keryx:latest; add HERMES_DASHBOARD_URL=http://<host>:9119 to get links into the Hermes dashboard.

Python.

cd frontend && npm install && npm run build && cd ..     # once; writes backend/static
cd backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
HERMES_DATA=~/.hermes .venv/bin/uvicorn app:app --host 0.0.0.0 --port 9120

Check it works

curl http://localhost:9120/api/health should answer with "state_db": true. If it says false, HERMES_DATA does not point at a directory containing state.db, or the Keryx user cannot read it. See Troubleshooting.

Updating

git pull
docker compose pull keryx && docker compose up -d keryx      # Docker
# or, from source:  cd frontend && npm run build && cd .. && docker compose up -d --build keryx

What you see

Compacted conversations. When Hermes compacts a long chat it ends the session and continues in a child session. Keryx folds that lineage into one node: it starts when the first segment started, takes its colour from the latest segment, and its trace shows every segment with a ⟲ marker where the context was compacted. The node keeps the first segment's id, so a #session:… link to any segment opens the same node. Branches the user made (/branch) stay separate sessions joined to their origin by a teal link; delegated subagents keep their purple link.

Reading a session. The trace is shown as turns: your question, a collapsible steps · N block (every tool call with a kind glyph, a one-line title such as the command or path, duration, exit code, and +added −removed for file edits; Hermes' own events; intermediate notes), then Hermes' reply. An outline lists every question with its step count, failures and edits and jumps to it. all / chat / changes shows the whole thing, the conversation alone, or only the file edits. find in session dims everything that does not match. 💭 shows the model's reasoning where the provider returned it (hidden by default, head of each one, searchable and exported while shown). ⎘ md copies the session as Markdown and ⤓ downloads it. Busy turns start collapsed; failed or running ones start open.

Session colours: running, waiting for you (open, last message is Hermes' reply: the next move is yours), stale (mid-turn and idle for 30 min), ended, closed by user, orphaned (killed by a gateway restart), failed (ended with tool errors). Tool failures come from the JSON result Hermes stores, not keyword matching.

Using it

Reading the graph. Hover highlights a neighbourhood. Click a node to select it; sessions fan their tools out in a ring facing you. Click a platform to collapse it. Search dims everything that does not match. The legend in the overview tab has checkboxes to hide any kind or status.

Time. The window selector (last hour to all time) sets what is loaded. The replay bar re-queries the graph as of any moment in the window. The ruler along the bottom of the graph is clickable: each label keeps only the sessions that started in that span, and the stats bar reads "showing N of M". Times are shown in your browser's zone (named in the header); analytics days are counted in UTC.

Spacing. ⇔ spacing scales rings, link lengths and repulsion together (compact / normal / airy / wide, or a slider). ⌖ recenter frames the whole graph again. Both settings are remembered per browser.

Navigation history. Every selection (graph click, now-card, side-panel link, toast) is a browser history entry that remembers the selection, the side-panel tab and the camera pose just before the move. The trail under the toolbar shows ‹ back, the last few stops (click one to jump there) and › forward. The URL hash (#session:…, #cron:…) is a deep link: share it, or scan it from the 📱 QR popover, and the page opens on that node.

Keyboard.

Every icon button carries a label for screen readers and a visible focus ring.

Other buttons. 🔔 enables desktop notifications; 🔈 adds a short sound per notification (synthesised in the browser, off by default). 📱 shows a QR code of the current page for your phone; Keryx ships a web-app manifest, so "add to home screen" keeps it as an app there. ? reopens the first-run card. ☾/☀ toggles the theme. ⤓ diagnostics (overview tab) downloads a redacted snapshot to attach to a bug report.

Configuration

All settings are environment variables.

Colours and labels live in frontend/src/util.js; rebuild after changing them.

What Keryx reads

Everything comes from the Hermes data directory, read-only: state.db (and its WAL, including Hermes' full-text index messages_fts when present), gateway_state.json (the gateway's own process and per-platform state), context_length_cache.yaml and the model: section of config.yaml (context windows), kanban.db and kanban/boards/*/kanban.db (the task queue), plugin-data/hermes-achievements/state.json (achievement unlocks), cron/jobs.json, cron/executions.db, cron/incidents.db, cron/deliveries.db, cron/ticker_heartbeat, logs/*.log, skills/.usage.json (the skill ledger) and, only with KERYX_SHOW_MEMORY=1, memories/MEMORY.md, memories/USER.md and the memory: section of config.yaml. Files that an older Hermes does not write are skipped, and columns are feature-detected, so Keryx works across Hermes versions. The volume is mounted read-write only because SQLite in WAL mode must be able to create its -shm file; Keryx itself never writes.

Security

Keryx shows everything Hermes recorded, including prompts, replies and tool output. Keep it on a private network: bind the port to 127.0.0.1 and reach it over an SSH tunnel, or use a VPN such as Tailscale. Do not expose it to the internet.

Setting KERYX_TOKEN adds a shared secret on top of that: every /api route then needs Authorization: Bearer <token>, a keryx_token cookie, or ?token=. The page asks for the token once and keeps it as a cookie; curl and scripts send the header. /api/health stays open for liveness probes but omits the data path without the token. This is a lock on the door, not a user system: there is one token, and anyone with it sees everything.

The only endpoint designed to be shared is /api/diagnostics, which is redacted (counts, states, ids, error lines with secrets masked; no message content).

Troubleshooting

Attach /api/diagnostics (the ⤓ link in the overview tab) to a bug report; it contains no message content.

Developing

cd frontend
npm install
KERYX_API=http://localhost:9120 npm run dev     # Vite dev server with /api proxied to a running backend
npm run build                                  # production build into backend/static
npm test                                       # vitest: layout, turns, grouping, notification, sound and plural logic

Backend tests build a miniature Hermes data directory (state.db, cron store, logs) in a temp folder and run the real builders and routes against it:

cd backend
python3 -m venv .venv && .venv/bin/pip install -r requirements-dev.txt
.venv/bin/pytest

CI runs both test suites, builds the front end and smoke-tests the Docker image on every push and pull request. Pushes to main and v* tags publish ghcr.io/rafreid/keryx for amd64 and arm64.

Layout:

backend/   FastAPI app (app.py), Dockerfile, requirements.txt, tests/, static/ (built front end, not committed)
frontend/  Vite + React + react-force-graph source; src/hooks/ holds the camera, time-axis, media-query and refresh-tick hooks
docs/      the project website (GitHub Pages) and screenshots

After a change, rebuild the front end and rebuild the container (docker compose up -d --build keryx), or restart uvicorn if you run it directly.

API

• GET /api/graph?hours=24[&at=<epoch>] nodes/links; at replays the graph as of that moment; aliases maps compacted segment ids to their node
• GET /api/now running + waiting sessions digest
• GET /api/status health checks (platform checks carry kind: "platform"), the ranked attention list (severity, source, label, detail, node or tab), dashboard links, and hermes (gateway state, desired state, version, pid, served profiles, restart requested) from gateway_state.json, or null without it
• GET /api/cost?hours=24 tokens/cost per model; cost_basis says whether the money is provider-reported (actual), priced from a table (estimated), included in a subscription or unknown
• GET /api/tasks delegations (goals, children, duration, delivery), cron jobs (next run, history, missed slots, open incidents), scheduler heartbeat, incidents, delivery queue, kanban counts
• GET /api/kanban?board=<slug>&archived=0 the kanban board as lanes in Hermes' workflow order, every task with links, comment count, latest run and a stale flag for silent workers; boards lists the others
• GET /api/kanban/{task_id}?board=<slug> one card in full: comments, run history, event timeline, attachment count
• GET /api/analytics?days=30 daily trend with per-day cost, a 53-week heatmap, model share, Hermes' skill ledger (skills), totals, providers (token share per billing provider), clock (hour of day and weekday × hour), velocity, insights, achievements
• GET /api/search?q=text&limit=30 sessions whose conversation mentions the text (Hermes' FTS5 index, LIKE fallback), with snippets; segments of a compacted conversation fold into one hit
• GET /api/memory MEMORY.md / USER.md entries with character budgets; enabled: false unless KERYX_SHOW_MEMORY=1
• GET /api/session/{id}/trace?limit=300[&tool=name] ordered steps (user / assistant / tool call with args + result / event / compaction), across every segment of a compacted conversation; tool calls carry tool_kind, title, diff (added/removed lines for write_file and patch), exit_code, lines; thinking steps carry the head of the model's reasoning when the provider returned it
• GET /api/session/{id}/todo the agent's current plan: the newest todo_list result in the conversation
• GET /api/session/{id}/context what fills the context of the conversation's current segment: characters by part (your messages, replies, tool-call arguments, tool output, compaction summaries) and by tool, the largest output, and the gauge
• GET /api/logs?file=<stem of any logs/*.log>&level=WARNING&q=text&lines=200 entries carry the session id when Hermes logged the line inside a session
• GET /api/diagnostics redacted JSON snapshot for bug reports
• GET /api/qr?text= SVG QR code
• GET /api/stream?hours=24 server-sent events, one update per data change; one watcher serves every connected client
• GET /api/health liveness

Credits

Built on 3d-force-graph through react-force-graph. Some ideas came from AionUi (waiting-vs-running state and turn-completed notifications, context usage, task board, files touched, diagnostics export) and Ekko Studio (usage analytics, tool-call traces, log viewer, themes).

Only the ideas were borrowed. No code, documentation or assets from either project is in Keryx: every feature was written from scratch against Hermes' own data, and a line-by-line and ten-word-shingle comparison of the Keryx sources against both repositories found nothing shared beyond generic boilerplate (Vite's HTML template head, React's import line, common CSS phrases). Keryx is MIT licensed and is not subject to either project's licence. For the record: AionUi is under the Apache License 2.0, and Ekko Studio is under the Business Source License 1.1 (non-commercial use only, converting to Apache 2.0 on 2029-05-10), which is why nothing from it may be copied into an MIT project.

About

Keryx is an open-source project of Aflux Systems LLC, released under the MIT license. Issues and pull requests are welcome at github.com/rafreid/keryx.