How joeynyc/hermes-hudui works
1. Overall shape
- This is a split Python + TypeScript application: a FastAPI-style backend in backend/ and a React/Vite frontend in frontend/.
- The app is a browser-based dashboard for a local Hermes agent installation, reading primarily from the user’s ~/.hermes/ data directory rather than from a remote cloud service.
2. Runtime and deployment boundary
- The backend is the system-of-record for all Hermes data access, analytics, export, and live updates.
- The frontend is a single-page UI that talks to backend HTTP APIs and WebSockets, and the backend also serves the built static frontend from backend/static/.
3. Backend entrypoints and composition
- backend/main.py is the application entrypoint, with backend/__init__.py exposing the package.
- backend/api/ contains route modules grouped by feature area: dashboard, chat, sessions, memory, skills, projects, providers, plugins, gateway, replay, health, token costs, and more.
- backend/collectors/ contains the data-gathering layer for those same feature areas, which strongly suggests a pattern of “API route → collector/service → local Hermes data”.
4. Local data ingestion layer
- The main data source is the Hermes local state under ~/.hermes/, not a central database.
- Collector modules likely parse files, logs, snapshots, and metadata from that directory into normalized responses used by the UI.
- backend/file_watcher.py indicates filesystem-based change detection so the UI can react to local agent updates without manual refresh.
5. Live update path
- backend/websocket_manager.py supports push updates to the browser.
- The README confirms that the dashboard reacts to filesystem and WebSocket events, so the data flow is: local Hermes state changes → watcher/collector updates → WebSocket broadcast → frontend refreshes affected panels.
6. Chat subsystem
- backend/chat/ is a dedicated runtime for live agent chat, separated from dashboard data collection.
- It includes engine.py, streamer.py, models.py, and a fallback_tmux.py, which implies the chat feature can stream responses and may fall back to terminal/tmux-based interaction when needed.
- The frontend’s ChatPanel and supporting chat components consume this live stream and render reasoning/tool-call structure, not just plain messages.
7. Replay pipeline
- Replay is a distinct subsystem with its own model, normalization, redaction, signing, verification, and export flow.
- backend/models/replay.py defines the replay data model; backend/services/replay_normalizer.py, replay_redactor.py, replay_exporter.py, replay_signer.py, and replay_verifier.py form a pipeline for turning raw session data into shareable artifacts.
- This is a key architectural boundary: raw agent traces are transformed into sanitized, signed outputs before export.
8. Replay and shareability boundary
- The README emphasizes “Safe Share Mode” and local-only exports under ~/.hermes-hud/replays/.
- That means the replay feature is intentionally designed to avoid uploading sensitive agent content by default; redaction and signing happen locally, and signature integrity is machine-local rather than third-party attested.
9. Feature-domain collectors and APIs
- The feature modules in backend/api/ and backend/collectors/ mirror each other: agents, corrections, cron, gateway, health, memory, model_info, patterns, plugins, profiles, projects, providers, sessions, skills, sudo, timeline, and token_costs.
- This suggests a modular architecture where each domain has:
- a collector that reads or derives local state,
- an API route that serializes it for the UI,
- and a corresponding frontend panel.
10. Caching, serialization, and state
- backend/cache.py and backend/api/cache.py indicate explicit caching around expensive local queries.
- backend/api/serialize.py and backend/api/state.py imply a normalization/serialization layer for presenting heterogeneous Hermes data consistently to the browser.
- This matters because the dashboard mixes static metadata with expensive summaries and live status, so not every UI action should recompute from scratch.
11. Health, diagnostics, and governance
- Health, gateway, sudo, and corrections are treated as first-class operational concerns.
- backend/api/health.py, gateway.py, sudo.py, and corrections.py indicate the dashboard is not just observability; it also exposes control surfaces and safeguards around agent operation, tool routing, and privileged actions.
- The README’s “two-click Update hermes” and gateway visibility reinforce that some actions are intentionally gated.
12. Frontend structure
- The frontend is organized into feature panels in frontend/src/components/, with shared shell pieces like TopBar, BootScreen, CommandPalette, and a generic Panel.
- frontend/src/components/chat/ contains specialized chat rendering for reasoning blocks, tool-call cards, message threading, and session sidebars.
- frontend/src/hooks/ centralizes API access, WebSocket subscription, theme handling, and chat state, which keeps the panels mostly presentational.
13. User experience and state propagation
- frontend/src/i18n/ shows built-in localization, and theme support is handled client-side with persistent preference storage.
- frontend/src/lib/replayApi.ts and frontend/src/types/replay.ts reflect a typed integration for the replay domain specifically.
- The UI is therefore driven by backend data contracts, but retains local UX state such as language, theme, and panel navigation in the browser.
14. External dependencies and tooling
- The project is Python 3.11+ on the backend and Node.js 18+ for the frontend build.
- pyproject.toml, frontend/vite.config.ts, and ci.yml show standard packaging/build automation, while tests cover both backend logic and browser-facing behavior.
- The only “external services” materially implied by the architecture are Hermes itself, local OAuth/provider integrations, and the Nous tool gateway used for managed tool routing.
15. How to diagram it
- A good architecture diagram would place Hermes local data (~/.hermes/) at the center, feeding the collector/service layer in the Python backend.
- From there, branch to:
- REST APIs for each domain,
- WebSocket live updates for dashboard/chat refresh,
- Replay export/sign/verify pipeline for shareable artifacts,
- and the React SPA as the presentation layer.
- The main boundary is between read/transform/control logic in Python and interactive visualization in the browser.
Main entry points: api API routes · collectors Collectors · main.py Main app · App.tsx SPA shell
Components 20
Backend
Python API, collectors, chat runtime, and replay services.
- Main app · Application startup and backend composition.
backend/main.py - File watcher · Detects local Hermes changes for live dashboard updates.
backend/file_watcher.py - WebSocket hub · Broadcasts live state changes to connected browsers.
backend/websocket_manager.py - Cache · Shared caching around expensive local reads and summaries.
backend/cache.py - Collectors · Feature-specific readers that normalize local Hermes state.
backend/collectors - API routes · Feature modules exposing dashboard, chat, sessions, memory, providers, replay, health, and other endpoints.
backend/api - Serialize state · Normalization and serialization of heterogeneous backend data for the UI.
backend/api/serialize.py - Chat runtime · Dedicated live agent chat engine with streaming and tmux fallback.
backend/chat
Frontend
React/Vite single-page dashboard and panel system.
- SPA shell · Top-level frontend application and panel routing.
frontend/src/App.tsx - UI hooks · Browser-side hooks for API access, WebSocket subscriptions, chat state, and theme handling.
frontend/src/hooks - Panels · Feature panels for dashboard, chat, sessions, replay, health, gateway, memory, and other domains.
frontend/src/components - Chat UI · Specialized chat rendering for reasoning, tool calls, threads, and session context.
frontend/src/components/chat - Replay UI · Typed frontend integration for replay browsing and verification.
frontend/src/lib/replayApi.ts
Replay pipeline
Normalization, redaction, signing, verification, and export for shareable session artifacts.
- Replay model · Core replay data structure used across the replay pipeline.
backend/models/replay.py - Normalize · Converts raw session data into a replayable normalized form.
backend/services/replay_normalizer.py - Redact · Removes or masks sensitive content before sharing.
backend/services/replay_redactor.py - Sign · Adds local signature metadata to replay artifacts.
backend/services/replay_signer.py - Verify · Checks replay signatures and artifact validity.
backend/services/replay_verifier.py - Export · Writes local replay outputs for safe sharing.
backend/services/replay_exporter.py
Other components
- Hermes data · Local Hermes files and state under the user's ~/.hermes/ directory.
Connections 24
- Hermes data → Collectors: read local state · Collectors parse files, logs, snapshots, and metadata from Hermes local storage.
- File watcher → WebSocket hub: emit changes · Filesystem events trigger update broadcasts.
- Collectors → Cache: memoize · Expensive derived reads are cached.
- Collectors → Serialize state: normalize · Collected domain data is shaped for API responses.
- Main app → API routes: mount routes · Backend entrypoint composes the HTTP surface.
- Main app → Chat runtime: start chat · Backend entrypoint includes the live chat subsystem.
- Main app → WebSocket hub: init push · WebSocket manager is part of backend runtime coordination.
- API routes → Collectors: serve data · Feature endpoints delegate to collectors or services.
- API routes → Serialize state: shape payloads · API responses are serialized consistently for the browser.
- API routes → Chat runtime: chat stream · Chat endpoints expose the live agent stream.
- WebSocket hub → UI hooks: push live data · Browser subscriptions receive panel and chat updates.
- API routes → SPA shell: http api · The SPA consumes backend endpoints.
- UI hooks → Panels: feed views · Hooks supply data and actions to feature panels.
- UI hooks → Chat UI: drive chat · Chat state and streaming updates power the chat interface.
- SPA shell → Panels: render app · The top-level app composes the dashboard panels and shell.
- SPA shell → Chat UI: render chat · Chat experience is embedded in the SPA.
- Replay model → Normalize: input model · Raw replay traces are normalized around the shared model.
- Normalize → Redact: sanitize · Normalized traces are redacted before sharing.
- Redact → Sign: seal · Redacted artifacts are signed locally.
- Sign → Verify: check · Signatures and artifacts can be verified locally.
- Verify → Export: approve export · Verified artifacts are exported for safe sharing.
- API routes → Replay model: replay api · Replay endpoints expose the session trace domain.
- Export → Replay UI: browse artifacts · Frontend replay views consume replay artifacts and status.
- API routes → Replay UI: replay api · The replay UI talks to dedicated backend replay endpoints.