Hermes Chat ⚡

A native Rust desktop chat client for Hermes Agent, built with iced.

Features

• SSE Streaming — Real-time token-by-token responses with live markdown rendering
• Markdown — Syntax-highlighted code blocks, headings, lists, tables
• Tool Progress — Inline indicators when the agent runs tools (💻 🔍 📁)
• Dual API Mode — Chat Completions (stateless) and Responses API (server-side state)
• Multi-Profile — Switch between Hermes agent profiles on the fly
• Conversations — Persistent chat history with auto-generated titles
• Dark Theme — Terminal-aesthetic dark UI
• Keyboard Shortcuts — Ctrl+N (new chat), Escape (stop streaming), Enter/Shift+Enter
• Lightweight — ~23 MB native binary, no Electron, no web runtime

Prerequisites

• Hermes Agent installed and configured
• API server enabled in Hermes

Setup

1. Enable the Hermes API server

Add to ~/.hermes/.env:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key

2. Start the gateway

hermes gateway start

3. Build and install

git clone https://github.com/tuxclaw/hermes-chat.git
cd hermes-chat
cargo build --release
cp target/release/hermes-chat ~/.local/bin/

4. Configure

On first run, Hermes Chat creates ~/.config/hermes-chat/config.toml:

active_profile = "default"

[[profiles]]
name = "default"
host = "127.0.0.1"
port = 8642
api_key = "your-secret-key"

Add more profiles to connect to different Hermes agent instances:

[[profiles]]
name = "woody"
host = "127.0.0.1"
port = 8643
api_key = "your-secret-key"

5. Launch

hermes-chat

Architecture

Two-crate Rust workspace:

• core/ — Data models, API client, SSE parser, persistence (no UI dependency)
• src/ — iced GUI application

Built on the Elm architecture via iced: State → Message → Update → View

Key Technologies

Component	Technology
GUI	iced 0.15-dev (wgpu-accelerated)
HTTP	reqwest with SSE streaming
Streaming	sipper (iced's async stream pattern)
Markdown	iced::widget::markdown (built-in)
Persistence	JSON (conversations), TOML (config)
Async	tokio

API Compatibility

Hermes Chat connects to the Hermes Agent API server which exposes an OpenAI-compatible HTTP API:

• POST /v1/chat/completions — Stateless chat with SSE streaming
• POST /v1/responses — Stateful chat with server-side conversation tracking
• GET /health — Connection health check

License

MIT