Skip to content

Hermes HUD UI

Hermes HUD UI is a web-based monitoring dashboard for the Hermes Agent framework.^[001-TODO__Hermes_HUD_UI_-AI_Agent_网页监控面板.md] It serves as a visual "consciousness monitor," providing a real-time, comprehensive view of an AI agent's internal state—such as memory, skills, token costs, and active processes—through a browser interface.^[001-TODO__Hermes_HUD_Web_UI-_Agent_意识监控仪表盘.md]

Designed to address the "black box" nature of running Hermes agents, where internal logic and resource consumption are often invisible, Hermes HUD UI makes these states observable and manageable without relying on terminal commands.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

Overview

Hermes HUD UI functions as a companion interface for Hermes Agent. It connects directly to the agent's local data directory (typically ~/.hermes/) and utilizes WebSockets to stream real-time updates to the frontend, eliminating the need for manual page refreshes.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Feature Description
Repository joeynyc/hermes-hudui^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
Tech Stack Python 3.11+ (FastAPI), Node.js 18+ (React), WebSocket^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]
Data Source Direct read access to ~/.hermes/ directory^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
Platform macOS, Linux, WSL^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Interface Features

The dashboard is organized into 13 tabs grouped into five functional categories, designed to give users full visibility over the agent's operations.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

1. Global Overview

  • Dashboard: Displays the agent's overall status, including online status, recent activities, and key performance indicators at a glance.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

2. Memory & Session Management

  • Memory: Allows users to view and edit the agent's persistent memory and user profiles directly in the browser.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Sessions: Provides a browsable history of past conversations and interactions.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

3. Analytics & Health

  • Costs: Tracks token consumption and financial costs, broken down by the specific AI models used (e.g., GPT-4, Claude).^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Health: Monitors the operational health and status of the agent.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Patterns: Analyzes usage habits and behavioral patterns.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

4. Agent Management

  • Skills: Lists and manages the skills currently learned by the agent.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Cron: Manages scheduled tasks and cron jobs.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Projects: Displays current project information.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Agents: Shows the status of sub-agents.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Profiles: Manages agent role configurations.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Corrections: Views records of corrections made to the agent's outputs.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

5. Interaction

  • Chat: Enables direct communication with the Hermes Agent through the web interface, removing the need to use a terminal.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

Themes & Customization

The interface supports visual customization via four distinct themes, which can be toggled using the t shortcut:^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

  • Neural Awakening: Cyberpunk aesthetic with a Cyan color scheme.
  • Blade Runner: Inspired by the film, using Amber tones.
  • fsociety: "Mr. Robot" inspired, using Green tones.
  • Anime: A style utilizing Purple tones.

Themes also include CRT scanline effects for a retro terminal look.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Technical Architecture

Hermes HUD UI uses a client-server architecture that separates the Python backend from the React frontend.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

  • Backend: Built with FastAPI and Uvicorn, it handles REST API requests and manages WebSocket connections. It uses watchfiles to monitor the ~/.hermes/ directory for changes and invalidates caches based on file modification times (mtime).^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]
  • Frontend: Built with React 19, Vite, and Tailwind CSS. It utilizes SWR (Stale-While-Revalidate) for data fetching and caching, ensuring the UI stays consistent with the file system state.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]
  • Data Flow: File changes trigger the backend file watcher, which clears the relevant cache and broadcasts an event via WebSocket. The frontend then automatically revalidates the data.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Installation & Usage

Prerequisites

  • Python 3.11+
  • Node.js 18+
  • An existing installation of Hermes Agent (specifically the ~/.hermes/ data directory)^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Setup

Clone the repository and run the installation script:^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

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

To start the dashboard:^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

source venv/bin/activate && hermes-hudui

The UI will typically be available at http://localhost:3001.^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]

Keyboard Shortcuts

  • 1-9, 0: Switch between tabs^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • t: Open theme selector^[001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md]
  • Ctrl+K: Open Command Palette^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Comparison with TUI Version

Hermes HUD UI is the web-based counterpart to the terminal-based hermes-hud (TUI). Both tools can be run simultaneously as they read from the same data source.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

Features unique to the Web UI include:^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md] * Dedicated tabs for Memory, Skills, and Sessions. * Token cost tracking broken down by model. * The Command Palette (Ctrl+K). * Direct web-based Chat interface. * Theme switcher.

Localization

The interface supports multi-language switching, primarily between English and Chinese. The language preference is persisted in localStorage. When set to Chinese, the agent's responses in the Chat tab will also be localized to Chinese.^[001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md]

  • Hermes Agent
  • [[WebSocket]]
  • [[FastAPI]]
  • [[Observable Systems]]

Sources

  • 001-TODO__Hermes_HUD_UI_-_AI_Agent_网页监控面板.md
  • 001-TODO__Hermes_HUD_Web_UI_-_Agent_意识监控仪表盘.md