DOCSEARCHbyAlgolia
Submit Docs

Hermes Studio Documentation

repository·main·Indexed 26 days ago

https://github.com/ekkolearnai/hermes-studio

A comprehensive management suite for Hermes Agents featuring a desktop app, local runtime, and a self-hosted AI chat dashboard (hermes-web-ui v0.6.34). The suite allows users to chat with agents, manage models, automate jobs, and control platform channels such as Telegram and Discord. It includes the Ekko Agent library for managing agentic lifecycles, model clients with OAuth presets, a tool registry for filesystem and terminal operations, and a skill management system.

Tokens
71.7K
Snippets
98
Records
472
Agent score
95%

What's inside Hermes Studio

  1. Overview of Hermes Studio capabilities

    main

    Hermes Studio is a desktop application, local runtime, and Web console for Hermes Agent. It provides a unified interface for:

    • Agent Chat: Real-time streaming, tool call tracking, and file management.
    • Local Console: Management of Profiles, Providers, models, credentials, memory, skills, and plugins.
    • Automation: Configuration of platform channels, Cron tasks, Kanban tasks, and MCP Servers.
    • Workspace Tools: File browser, Web terminal, Voice I/O, and Coding Agents.
    • Distribution: Available as Windows/macOS/Linux desktop apps, an npm CLI package, and Docker images.

  3. Understand the Ekko Agent Unified Memory System

    main
    Ekko Agent uses a single, unified long-term memory system isolated by Hermes profile. Unlike traditional systems, it does not use separate scopes like session, workspace, user, or global. Instead, all long-term information is stored as memory_nodes within a specific profile. Session messages and rolling summaries are used internally as cursors for organization but are not themselves queryable or modifiable long-term memory types.

  4. Understand Group Chat architecture

    main

    Group Chat uses a dedicated Socket.IO namespace /group-chat. While it shares the Agent Bridge and context-compressor with standard chats, it manages its own room state, members, and message history.

    Key Flow:

    1. Users/Agents join the /group-chat namespace.
    2. AgentClients perform mention routing to select target agents.
    3. Instructions and group history are passed to the AgentBridgeClient.
    4. Messages, tool calls, and reasoning are written to specific gc_* database tables.

    Troubleshooting Group Chat:

    • Check /group-chat socket handshake authentication (authUserId, source=agent).
    • Inspect GroupChatServer handlers for connection, join, and message events.
    • Verify ContextEngine and room-specific compression configurations (triggerTokens, maxHistoryTokens).

  5. Understand the Hermes Studio Architecture

    main

    Hermes Studio follows a layered architecture designed for multi-agent extensibility. The flow moves from the Browser through a Backend-for-Frontend (BFF) layer to the agent runtime.

    Architecture Flow:

    1. Browser: Frontend interface.
    2. BFF (Koa, running on port :8648): Handles Socket.IO chat streaming, agent bridging, session management, and file operations.
    3. Hermes Agent Bridge: Connects the BFF to the Hermes Agent runtime.
    4. Hermes Agent Runtime: Executes agent logic via Hermes CLI, profiles, and specific APIs (e.g., Tencent iLink for WeChat QR login).

    Extensibility: All Hermes-specific code is namespaced under hermes/ directories (API, components, views, stores), allowing developers to add new agent integrations easily.

  6. Understand the Agent Runner Gateway Architecture

    main

    The Agent Runner Gateway is a unified protocol pipeline designed to normalize upstream provider streams (like Claude Code and Codex) into a single internal event shape called CanonicalAgentEvent. This allows multiple subscribers—such as HTTP/SSE serializers, Socket.IO emitters, database persistence, and usage accounting—to consume the same stream.

    Architecture Flow

    Provider protocol $\rightarrow$ ProtocolAdapter $\rightarrow$ CanonicalAgentEvent stream $\rightarrow$ Subscribers (HTTP SSE, Socket.IO, DB, Usage, Logs).

  7. Understand Session Compression Cursor Scope

    main

    The session compression cursor is a mechanism used to manage model context in Hermes Bridge chat sessions. It optimizes how the server assembles context by using a stable database cursor instead of array positions.

    Important Scope Limitations:

    • Applies to: Hermes Bridge chat sessions where the Web UI server assembles the model context.
    • Does NOT apply to: Coding Agent execution. Coding Agents (like Claude Code or Codex) manage their own native session history, resumption, and internal compaction. The compression cursor does not affect their native runtimes.

  8. Understand the Chat Session execution flow

    main

    The standard Chat flow in Hermes Studio does not use the Hermes Gateway /v1/responses directly. Instead, it follows the Agent Bridge path with source=cli.

    Execution Chain: ChatPanel / ChatInput $\rightarrow$ Pinia chat store $\rightarrow$ packages/client/src/api/hermes/chat.ts $\rightarrow$ Socket.IO namespace /chat-run $\rightarrow$ ChatRunSocket $\rightarrow$ handleBridgeRun() $\rightarrow$ AgentBridgeClient $\rightarrow$ hermes_bridge.py broker $\rightarrow$ profile worker $\rightarrow$ AIAgent / Hermes Agent tools.

    Key Principles:

    • All long-connection events use the /chat-run namespace.
    • Sessions are stored in a local SQLite database in sessions/messages tables.
    • Context (profile, model, provider, workspace, source) is managed at the session level.
    • Multi-tab support is achieved by using resume to rejoin the same session:{id} room.
    • Only one active run is allowed per session; subsequent inputs are queued.

  9. Architecture of the Hermes Studio Desktop Built-in Browser

    main

    The Hermes Studio desktop application includes a built-in browser based on Electron WebContentsView. This browser is designed to allow both users and AI Agents (Ekko, Hermes, Codex, Claude Code) to interact with the same visible web pages in real-time.

    Control Pathways

    • User Manual Operations: Vue Browser UI $\rightarrow$ Trusted Preload API $\rightarrow$ Electron IPC $\rightarrow$ BrowserManager $\rightarrow$ WebContentsView.
    • Agent Operations: Agent $\rightarrow$ MCP (stdio) $\rightarrow$ Local Browser Broker (Private RPC) $\rightarrow$ BrowserManager / BrowserAutomation $\rightarrow$ WebContentsView.

    Technical Implementation Details

    • Navigation & Tabs: Uses Electron webContents APIs.
    • DOM Interaction: Uses webContents.debugger to send direct CDP (Chrome DevTools Protocol) commands for clicking, typing, scrolling, and screenshots.
    • Element Selection: Uses executeJavaScriptInIsolatedWorld() for DOM element selection and area bounding.
    • Security: The browser does not expose CDP endpoints, Electron objects, or raw IPC to the Agent. Remote web pages are restricted from accessing Node, Electron IPC, local files, or Web UI credentials.

  10. Understand Hermes Web UI architecture

    main

    The project follows a split client/server architecture:

    • Frontend: Located in packages/client/src.
    • Server: Located in packages/server/src.
    • Hermes-specific client code: Resides under hermes namespaces (API modules, views, stores, and components).
    • Chat Runtime: Socket.IO based, located in packages/server/src/services/hermes/run-chat.
    • Web UI State Directory: Managed via HERMES_WEB_UI_HOME or HERMES_WEBUI_STATE_DIR (defaults to ~/.hermes-web-ui).

    Server Design Pattern: Keep routes thin. Handle request logic in controllers and encapsulate reusable behavior in services.

  12. Run validation checks for Pull Requests

    main

    To validate changes in a Pull Request, run the standard harness check. For changes affecting shared behavior, release automation, authentication, persistence, or chat, you must escalate to broader checks including coverage, end-to-end tests, and builds.

    Standard check:

    npm run harness:check

    Broad/Shared changes (escalated):

    npm run test:coverage
npm run test:e2e
npm run build