DOCSEARCHbyAlgolia
Submit Docs

Hermes UI

repository·main·Indexed 41 days ago

https://github.com/pyrate-llama/hermes-ui

A single-file, React 18-based HTML command center for managing and interacting with the Hermes Agent. It provides a glassmorphic interface featuring a full-featured chat, Kanban task board, workspace-aware file browser, skills browser, and real-time monitoring of agentic tasks and logs. It connects to the Hermes Agent backend via a lightweight Python proxy server.

Tokens
5.4K
Snippets
15
Records
30
Agent score
53%

What's inside Hermes UI

  1. Overview of Hermes UI features and capabilities

    main

    Hermes UI is a multi-work command center designed for managing AI agent workflows. Key functional areas include:

    • Chat: Advanced conversation interface with per-message model switching, Mermaid diagram rendering, and context pressure monitoring.
    • Tasks / Kanban Board: Live tracking of Hermes todos and delegated subagent work with automatic task detection.
    • Spaces / Workspaces: Ability to manage multiple workspace roots, making the File Browser and chat context workspace-aware.
    • Operations & Health: A consolidated health screen for monitoring Hermes heartbeat, agent/model/provider status, and redacted logs.
    • Tools & Extensions: Integrated support for MCP Tools, Terminal tabs, Cron Jobs, and a Skills Browser.
    • File Management: A workspace-aware File Browser to navigate local project structures.

  2. Overview of Hermes UI features

    main

    Hermes UI is a comprehensive interface for interacting with the Hermes Agent. Key functional areas include:

    • Chat Interface: Supports SSE streaming, tool call visualization, slash commands (like /tasks or /workspace), and document uploads (.pdf, .md, .py, etc.).
    • Artifact Panel: A dedicated side panel that auto-detects and renders HTML, SVG, PDF, and CSV outputs from the agent.
    • Spaces / Workspaces: Manage multiple project roots and switch between them using the sidebar or the /workspace [name or path] command.
    • Tasks / Kanban: A live board generated from chat signals to track todos, subagent work, and tool calls.
    • Skills & MCP Browser: Search and manage installed skills and browse connected MCP (Model Context Protocol) servers and tools.
    • File Browser & Terminal: In-place file editing within the active workspace and real-time log streaming for Shell, Hermes, and Claude Code flows.
    • Dashboard & Health: Monitor live stats (tokens, messages) and system status (model, provider, uptime).

  3. Overview of Hermes UI

    main
    Hermes UI is a command center for the Hermes Agent. It is a single-file HTML application built with React 18 that provides a glassmorphic interface to chat with agents, steer their behavior, browse files, manage skills, and monitor real-time logs and tasks. It operates through a lightweight Python proxy server that connects the UI to the backend agent.

  4. Understand the Behavioral Guidelines principles

    main

    The Behavioral Guidelines are designed to bias the LLM toward caution and precision rather than speed. They are distilled from Andrej Karpathy's coding principles and focus on four core areas:

    1. Think Before Coding

    Avoid assumptions. The LLM should explicitly state assumptions, present multiple interpretations of a request, and surface tradeoffs or confusion before writing code.

    2. Simplicity First

    Focus on the minimum code required to solve the problem. This means avoiding speculative abstractions, unrequested configurability, or error handling for impossible scenarios. If code can be reduced from 200 lines to 50, it should be.

    3. Surgical Changes

    When editing existing files, the LLM should touch only what is strictly necessary.

    • Do not refactor adjacent code, comments, or formatting that isn't broken.
    • Do not delete pre-existing dead code (mention it instead).
    • Do match the existing style.
    • Do remove imports or variables that your specific changes made unused.

    4. Goal-Driven Execution

    Tasks should be transformed into verifiable goals. Instead of vague objectives, use a plan-and-verify approach:

    1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

    Examples of transforming tasks:

    • "Add validation" $\rightarrow$ "Write tests for invalid inputs, then make them pass"
    • "Fix the bug" $\rightarrow$ "Write a test that reproduces it, then make it pass"

  5. Understand the Hermes UI Architecture

    main

    Hermes UI follows a three-tier architecture consisting of a React-based frontend, a Python proxy server, and the Hermes Agent backend:

    1. Browser (React 18): The frontend is contained in a single file, hermes-ui.html, which includes React components, CSS, and markup. It uses Babel standalone for in-browser JSX compilation.
    2. serve_lite.py (Port 3333): A lightweight Python proxy (using only the standard library) that serves static files, proxies the /api/chat/* two-step SSE flow to the agent, streams logs via SSE, and provides shell/Claude CLI execution and file browsing/editing within ~/.hermes.
    3. Hermes Agent (Port 8642): The core WebAPI backend.

    Note: serve.py is a backwards-compatibility shim that executes serve_lite.py. You should use serve_lite.py for new deployments.

    ┌─────────────┐    ┌────────────────┐    ┌──────────────────┐
│  Browser     │───▶│  serve_lite.py │───▶│  Hermes Agent    │
│  (React 18)  │    │  port 3333     │    │  port 8642       │
│              │◀───│  proxy +       │◀───│  (WebAPI)        │
│  Single HTML │    │  log stream    │    │                  │
└─────────────┘    └────────────────┘    └──────────────────┘

  6. Core Features of Hermes UI

    main

    Hermes UI provides several integrated modules for managing agentic workflows:

    • Chat: A full-featured interface supporting inline image generation, live terminal panels, split log panels, and streaming response visibility.
    • Tasks / Live Work: A board to monitor active tool work and track background follow-up tasks.
    • Dashboard: Real-time statistics, recent activity logs, and a list of installed skills.
    • Skills Browser: Interface to browse and manage installed Hermes skills.
    • Cron Jobs: Management of scheduled tasks with controls to edit, pause, or run jobs immediately.
    • MCP Tools: A view of connected Model Context Protocol (MCP) servers, grouped by category.
    • File Browser: A live file browser for the active workspace with inline file previews.
    • Terminal: A built-in terminal area featuring tabs for both Hermes and Claude Code.

  7. Access Hermes UI remotely via Tailscale

    main

    You can access the Hermes UI from any device (mobile, tablet, etc.) using Tailscale without exposing public ports.

    1. On the server running Hermes: Install Tailscale and bring it up:
      # macOS
brew install tailscale
# Linux
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
    2. On your remote device: Install the Tailscale app and log in with the same account.
    3. Connect: Find your server's Tailscale IP using tailscale ip and visit: http://<your-tailscale-ip>:3333/hermes-ui.html
    4. (Optional) Enable HTTPS via Tailscale Serve:
      tailscale serve --bg 3333
      Then access via https://<your-machine-name>.<tailnet-name>.ts.net.

    Configuration guidance is available in the UI under Settings → Remote Access (设置 → 远程访问).

    tailscale up
tailscale serve --bg 3333

  8. Install and run Hermes UI

    main

    Hermes UI is a local-first interface that requires no npm install or build steps. It runs via a Python proxy server that connects to a running Hermes Agent instance.

    Prerequisites

    Installation Steps

    1. Clone the repository:
      git clone https://github.com/pyrate-llama/hermes-ui.git
cd hermes-ui
    2. Start the proxy server using the Hermes virtual environment interpreter:
      ~/.hermes/hermes-agent/venv/bin/python3 serve_lite.py
    3. Access the UI in your browser at: http://localhost:3333/hermes-ui.html

    Custom Port

    You can specify a custom port using the --port flag:

    ~/.hermes/hermes-agent/venv/bin/python3 serve_lite.py --port 8080

    Note: While serve.py is available for backward compatibility, new setups should use serve_lite.py directly.

    # Clone the repo
git clone https://github.com/pyrate-llama/hermes-ui.git
cd hermes-ui

# Start the proxy server with the Hermes venv interpreter
~/.hermes/hermes-agent/venv/bin/python3 serve_lite.py

  9. Manage Spaces and Workspaces

    main

    Hermes UI uses 'Spaces' to define workspace roots. You can manage them through the sidebar and the Spaces view:

    • Add a Space: Use the 'Browse' option in the Spaces view to select a folder and save it.
    • Switching Spaces: You can switch the active workspace using the sidebar Space selector or the Spaces list.
    • Workspace Context: The 'Files' view and the 'Chat' context are tied to the active space. You can verify the active workspace by asking the chat.
    • Command Line Switching: Use the /workspace <space name> slash command to change the active space.
    • Deletion Safety: Removing a space within the UI removes it from the selector but does not delete the actual files on disk.

  10. Use Chat and Composer features

    main

    The Chat interface supports several interactive features:

    • Streaming: Standard chat messages support streaming responses.
    • Slash Commands: Type / to open the slash command menu.
    • Chat Profiles: You can switch chat profiles to change the style of outgoing responses.
    • Mermaid Diagrams: The UI supports rendering Mermaid diagrams if they are pasted or typed into the chat.
    • Side Questions: Triggering side questions preserves the current active workspace context.

  11. Enable Behavioral Guidelines in Hermes UI

    main

    You can instruct the LLM to follow specific coding principles to reduce mistakes and overcomplication. These guidelines are loaded by serve_lite.py and appended to the system prompt.

    To activate them:

    1. Navigate to Settings.
    2. Go to General.
    3. Toggle "Apply behavioral guidelines" to ON.

  12. Enable Web Extraction with Scrapling

    main

    Hermes UI can surface web extraction capabilities if the Hermes Agent exposes web_extract via MCP tools. While a generic fallback exists, using Scrapling is the preferred backend.

    To add Scrapling, you can use the following MCP launch command:

    uvx scrapling mcp

    Once enabled, the status will be visible in the MCP Tools section of the UI, distinguishing between Scrapling Active and Hermes Fallback.

    After configuration, you can ask the agent to extract, summarize, or gather data from a URL directly in the chat.