webui/README.md

Hermes Web UI

A lightweight, dark-themed browser interface for Hermes. Full parity with the CLI experience -- everything you can do from a terminal, you can do from this UI. No build step, no framework, no bundler. Just Python and vanilla JS.

Layout: three-panel Claude-style. Left sidebar for sessions and tools, center for chat, right for workspace file browsing.

---

Quick start

git clone <this-repo> hermes-webui
cd hermes-webui
./start.sh

That is it. The script will:

1. Locate your Hermes agent checkout automatically.
2. Find (or create) a Python environment with the required dependencies.
3. Start the server.
4. Print the URL (and SSH tunnel command if you are on a remote machine).

---

What start.sh discovers automatically

Thing	How it finds it
Hermes agent dir	HERMES_WEBUI_AGENT_DIR env, then ~/.hermes/hermes-agent, then sibling ../hermes-agent
Python executable	Agent venv first, then .venv in this repo, then system python3
State directory	HERMES_WEBUI_STATE_DIR env, then ~/.hermes/webui-mvp
Default workspace	HERMES_WEBUI_DEFAULT_WORKSPACE env, then ~/workspace, then state dir
Port	HERMES_WEBUI_PORT env or first argument, default 8787

If discovery finds everything, nothing else is required.

---

Overrides (only needed if auto-detection misses)

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
export HERMES_WEBUI_PYTHON=/path/to/python
export HERMES_WEBUI_PORT=9000
./start.sh

Or inline:

HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

Full list of environment variables:

Variable	Default	Description
HERMES_WEBUI_AGENT_DIR	auto-discovered	Path to the hermes-agent checkout
HERMES_WEBUI_PYTHON	auto-discovered	Python executable
HERMES_WEBUI_HOST	127.0.0.1	Bind address
HERMES_WEBUI_PORT	8787	Port
HERMES_WEBUI_STATE_DIR	~/.hermes/webui-mvp	Where sessions and state are stored
HERMES_WEBUI_DEFAULT_WORKSPACE	~/workspace	Default workspace
HERMES_WEBUI_DEFAULT_MODEL	openai/gpt-5.4-mini	Default model
HERMES_HOME	~/.hermes	Base directory for Hermes state (affects all paths above)
HERMES_CONFIG_PATH	~/.hermes/config.yaml	Path to Hermes config file

---

Accessing from a remote machine

The server binds to 127.0.0.1 by default (loopback only). If you are running Hermes on a VPS or remote server, use an SSH tunnel from your local machine:

ssh -N -L <local-port>:127.0.0.1:<remote-port> <user>@<server-host>

Example:

ssh -N -L 8787:127.0.0.1:8787 user@your.server.com

Then open http://localhost:8787 in your local browser.

start.sh will print this command for you automatically when it detects you are running over SSH.

---

Manual launch (without start.sh)

If you prefer to launch the server directly:

cd /path/to/hermes-agent          # or wherever sys.path can find Hermes modules
HERMES_WEBUI_PORT=8787 python /path/to/hermes-webui/server.py

Health check:

curl http://127.0.0.1:8787/health

---

Running tests

Tests discover the repo and the Hermes agent dynamically -- no hardcoded paths.

cd hermes-webui
python -m pytest tests/ -v

Or using the agent venv explicitly:

/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v

Tests run against an isolated server on port 8788 with a separate state directory. Production data and real cron jobs are never touched.

---

Features

Chat and agent

• Streaming responses via SSE (tokens appear as they are generated)
• 10+ models across OpenAI, Anthropic, and other providers; last-used model persists
• Send a message while one is processing -- it queues automatically
• Edit any past user message inline and regenerate from that point
• Retry the last assistant response with one click
• Cancel a running task from the activity bar
• Tool call cards inline -- each shows the tool name, args, and result snippet
• Approval card for dangerous shell commands (allow once / session / always / deny)
• File attachments persist across page reloads

Sessions

• Create, rename, delete, search by title and message content
• Grouped by Today / Yesterday / Earlier in the sidebar
• Download as Markdown transcript or full JSON export
• Sessions persist across page reloads and SSH tunnel reconnects

Workspace file browser

• Browse directory tree with type icons
• Preview text, code, Markdown (rendered), and images inline
• Edit files in the browser
• Create and delete files
• Right panel is drag-resizable

Panels

• Chat -- session list, search, new conversation
• Tasks -- view, create, edit, run, pause/resume, delete cron jobs
• Skills -- list all skills by category, search, preview, create/edit
• Memory -- view and edit MEMORY.md and USER.md inline
• Todos -- live task list from the current session
• Spaces -- add, rename, remove workspaces; quick-switch from topbar

---

Architecture

server.py               HTTP routing shell
api/
  config.py             Discovery + globals (HOST, PORT, SESSIONS, etc.)
  helpers.py            HTTP helpers: j(), bad(), require(), safe_resolve()
  models.py             Session model + CRUD
  workspace.py          File ops: list_dir, read_file_content, workspace helpers
  upload.py             Multipart parser, file upload handler
  streaming.py          SSE engine, run_agent integration, cancel support
static/
  index.html            HTML template
  style.css             All CSS
  ui.js                 DOM helpers, renderMd, tool cards
  workspace.js          File tree, preview, file ops
  sessions.js           Session CRUD, list rendering, search
  messages.js           send(), SSE event handlers, approval, transcript
  panels.js             Cron, skills, memory, workspace, todo, switchPanel
  boot.js               Event wiring + boot IIFE
tests/
  conftest.py           Isolated test server (port 8788, separate HERMES_HOME)
  test_sprint1-10.py    Feature tests per sprint
  test_regressions.py   Permanent regression gate

State lives outside the repo at ~/.hermes/webui-mvp/ by default (sessions, workspaces, last_workspace). Override with HERMES_WEBUI_STATE_DIR.

---

Docs

• ROADMAP.md -- feature roadmap and sprint history
• ARCHITECTURE.md -- system design, all API endpoints, implementation notes
• TESTING.md -- manual browser test plan and automated coverage reference
• CHANGELOG.md -- release notes

Repo

git@github.com:<your-username>/hermes-webui.git