Building a Consciousness Monitor for AI Agents: Inside Hermes HUDUI

#webdev #ai #productivity #opensource

AI agents with persistent memory are fascinating—but watching them think, learn, and operate in real-time is even better. Let me introduce Hermes HUDUI, a web-based dashboard that gives you a window into your AI agent's "mind."

What is Hermes HUDUI?

Hermes HUDUI is a browser-based consciousness monitor for Hermes—an AI agent with persistent memory. Think of it as a mission control center for your agent, showing you everything it knows about itself: identity, memory, skills, sessions, costs, health, and more.

It's the web companion to my popular TUI version, hermes-hud. Both read from the same ~/.hermes/ data directory independently—use either one, or both simultaneously.

The Tech Stack

Backend (Python):

FastAPI for the REST API and WebSocket server
uvicorn as the ASGI server
watchfiles for hot-reloading file system changes
Smart caching with automatic invalidation

Frontend (TypeScript/React):

React 19 with TypeScript
Vite for lightning-fast builds
TailwindCSS for styling
SWR for data fetching and caching
react-markdown with syntax highlighting
WebSocket for real-time updates

The architecture is straightforward: a FastAPI backend watches the Hermes data directory, serves APIs, and broadcasts changes via WebSocket. The React frontend consumes these APIs and updates in real-time without manual refreshes.

13 Tabs of Insight

The dashboard covers everything your agent knows about itself across 13 tabs:

Dashboard — Identity, stats, memory bars, service health, skills, projects, cron jobs, tool usage, daily sparkline
Memory — Agent memory and user profile with capacity bars
Skills — Category chart, skill details, custom skill badges
Sessions — Session history with message/token counts and sparklines
Cron — Scheduled jobs with schedule, status, and prompt preview
Projects — Repos grouped by activity, branch info, language detection
Health — API key status, service health with PIDs
Agents — Live processes, operator alerts, recent session history
Profiles — Full profile cards with model, provider, soul summary, toolsets
Costs — Per-model USD estimates, daily trend, token breakdown
Patterns — Task clusters, hourly activity heatmap, repeated prompts
Corrections — View corrections grouped by severity
Chat — Live chat with your Hermes agent

Real-Time Everything

The most powerful feature is real-time updates via WebSocket. When your agent creates a new memory, completes a session, or updates its state—the dashboard reflects it instantly. No manual refresh needed.

This is powered by a file watcher that monitors the Hermes data directory and broadcasts changes to all connected clients.

Live Chat Integration

The Chat tab lets you converse with your agent directly in the browser. Features include:

Multiple independent sessions with message history
Streaming responses via SSE
Markdown rendering with syntax-highlighted code blocks
Tool call visibility (web_search, terminal, etc.) with arguments
Collapsible "Thinking" sections showing agent reasoning
Chat history persistence across page refreshes
Session search with full-text search across transcripts

Internationalization

Version 0.4.0 added full i18n support—English and Chinese. Every UI string across all 13 tabs is translated. A language toggle in the header switches instantly, and the choice persists to localStorage. When set to Chinese, chat responses from your agent also come back in Chinese.

Cyberpunk Aesthetics

Because monitoring AI agents should feel futuristic, Hermes HUDUI includes four cyberpunk-inspired themes:

Neural Awakening (cyan) — clean, clinical
Blade Runner (amber) — dystopian neon
fsociety (green) — hacker terminal
Anime (purple) — vibrant anime aesthetic

Plus optional CRT scanlines for that authentic retro feel. Press t to cycle through themes.

Keyboard-First Design

Power users will appreciate the keyboard shortcuts:

1–9, 0 — Switch tabs instantly
t — Open theme picker
Ctrl+K — Command palette to jump anywhere

Getting Started

Prerequisites: Python 3.11+, Node.js 18+, and a running Hermes agent with data in ~/.hermes/

git clone https://github.com/joeynyc/hermes-hudui.git
cd hermes-hudui
./install.sh
hermes-hudui

Open http://localhost:3001 and you're in.

For subsequent runs:

source venv/bin/activate && hermes-hudui

What Makes It Unique

Unlike generic monitoring tools, Hermes HUDUI is purpose-built for AI agents with persistent memory. It understands the structure of Hermes data and presents it in ways that make sense for understanding agent behavior:

Memory editing — Inline edit, delete, and add memory entries directly
Session transcript viewer — Click any session to read the full conversation with per-message token counts
Per-model cost tracking — See USD estimates broken down by model
Activity heatmaps — Visualize when your agent is most active