gooneyryan/hermes-webui
1
0
Fork 0
mirror of https://github.com/nesquena/hermes-webui.git synced 2026-07-19 14:12:01 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh + reorganize README and key markdown files

Browse Source 
README:
- Add a Contents table of contents for navigability (800-line doc).
- Freshen stale snapshots: test count 5303/488 files -> ~7,150/~700 files;
  reframe contributor counts to point at CONTRIBUTORS.md as the live source.
- Rebuild the Architecture section: drop per-file exact LOC (drifts every
  release -> chronic staleness) in favor of a stable backend/frontend role map;
  add pyproject.toml + the ruff/browser/docker CI gates.
- Reorganize the Docs index by purpose (Start here / Using / Deploying /
  Contributing & design / Release history); add missing CONTRIBUTING.md,
  DESIGN.md, docs/workspace-git.md; convert bare paths to working links.

ARCHITECTURE.md: header v0.51.54/5303 -> v0.51.192/~7,150 + note that the
  numbers are a periodic snapshot (authoritative source = git tag + collect-only).

TESTING.md: header + footer test counts refreshed; drop the stale
  'through v0.50.21' framing; note the ruff/browser/docker gates.

ROADMAP.md: refresh the 'Last updated' stamp (v0.51.31/5028 -> v0.51.192/~7,150)
  with recent themes.

Markdown-only; all internal links verified to resolve.
This commit is contained in:
nesquena-hermes
2026-06-01 01:42:20 +00:00
parent 4c7c65192c
commit 31fcdfa39a
4 changed files with 104 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ARCHITECTURE.md
+5 -3
View File
@@ -7,10 +7,12 @@
>
> Keep this document updated as architecture changes are made.
> Current shipped build: `v0.51.54` (May 13, 2026).
> Automated coverage: 5303 tests via `pytest tests/ --collect-only -q`. CI runs on Python 3.11, 3.12, and 3.13 against every PR.
> Current shipped build: `v0.51.192` (May 31, 2026).
> Automated coverage: ~7,150 tests via `pytest tests/ --collect-only -q`. CI runs on
> Python 3.11, 3.12, and 3.13 (3 parallel shards each) against every PR, plus a ruff
> lint gate, a headless browser smoke test, and a Docker smoke test.
>
> Notable architecture state as of v0.51.54: the bootstrap and first-run onboarding flow own setup discovery; the default WebUI state directory is `~/.hermes/webui`; `ctl.sh` provides a daemon wrapper for homelab installs; chat streaming is still WebUI-owned SSE with stream-ownership guards, cancellation, async manual compression, and turn-journal audit plumbing; provider/model discovery is profile-aware with live-model cache invalidation and custom-provider scoping.
> Notable architecture state: the bootstrap and first-run onboarding flow own setup discovery; the default WebUI state directory is `~/.hermes/webui`; `ctl.sh` provides a daemon wrapper for homelab installs; chat streaming is still WebUI-owned SSE with stream-ownership guards, cancellation, async manual compression, and turn-journal audit plumbing; provider/model discovery is profile-aware with live-model cache invalidation and custom-provider scoping. (Version/test-count numbers above are a periodic snapshot — the authoritative source is the latest git tag and `pytest --collect-only`.)
---
README.md
+94 -48
View File
@@ -45,6 +45,20 @@ This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** wh
---
## Contents
- [Why Hermes](#why-hermes) — what it is and how it compares
- [Quick start](#quick-start) — clone + `bootstrap.py` / `start.sh` / `ctl.sh`
- [Docker](#docker) — single- and multi-container deploys
- [Configuration & access](#what-startsh-discovers-automatically) — auto-discovery, overrides, remote/Tailscale/phone, manual launch
- [Running tests](#running-tests)
- [Features](#features) — chat, sessions, workspace, voice, profiles, security, themes, panels, mobile
- [Architecture](#architecture) — backend/frontend layout, state dir
- [Docs](#docs) — the full documentation index
- [Contributors](#contributors)
---
## Why Hermes
Most AI tools reset every session. They don't know who you are, what you worked on, or what
@@ -480,7 +494,8 @@ Or using the agent venv explicitly:
Tests run against an isolated server with a separate state directory.
Production data and real cron jobs are never touched. Current snapshot:
**5303 tests collected** across **488 test files**.
**~7,150 tests collected** across **~700 test files**, run in CI on Python 3.11,
3.12, and 3.13 (3 parallel shards each).
---
@@ -607,69 +622,100 @@ Production data and real cron jobs are never touched. Current snapshot:
## Architecture
No build step, no framework, no bundler — a Python standard-library HTTP server
and vanilla JS. The backend lives in `api/`, the frontend in `static/`.
**Backend (`api/`)**
```
server.py HTTP routing shell + auth middleware (~446 lines)
server.py HTTP routing shell + auth middleware
api/
auth.py Optional password authentication, signed cookies (~366 lines)
config.py Discovery, globals, model detection, reloadable config (~4139 lines)
helpers.py HTTP helpers, security headers (~302 lines)
models.py Session model + CRUD + CLI bridge (~1927 lines)
onboarding.py First-run onboarding wizard, OAuth provider support (~1002 lines)
profiles.py Profile state management, hermes_cli wrapper (~1056 lines)
routes.py All GET + POST route handlers (~9772 lines)
state_sync.py /insights sync — message_count to state.db (~118 lines)
streaming.py SSE engine, run_agent, cancel support (~4420 lines)
updates.py Self-update check and release notes (~545 lines)
upload.py Multipart parser, file upload handler (~284 lines)
workspace.py File ops, workspace helpers, git detection (~810 lines)
static/
index.html HTML template (~1323 lines)
style.css All CSS incl. mobile responsive, themes (~3767 lines)
ui.js DOM helpers, renderMd, tool cards, context indicator (~7216 lines)
workspace.js File preview, file ops, git badge (~369 lines)
sessions.js Session CRUD, collapsible groups, search, reload recovery (~3517 lines)
messages.js send(), SSE handlers, live streaming, session recovery (~2301 lines)
panels.js Cron, skills, memory, profiles, settings (~6480 lines)
commands.js Slash command autocomplete (~1302 lines)
boot.js Mobile nav, voice input, boot IIFE (~1607 lines)
tests/
conftest.py Isolated test server/state fixtures
488 test files 5303 tests collected
Dockerfile python:3.12-slim container image
docker-compose.yml Compose with named volume and optional auth
.github/workflows/ CI: multi-arch Docker build + GitHub Release on tag
auth.py Optional password authentication, signed cookies, passkeys
config.py Discovery, globals, model detection, reloadable config
helpers.py HTTP helpers, security headers
models.py Session model + CRUD + CLI/state.db bridge
onboarding.py First-run onboarding wizard, OAuth provider support
profiles.py Profile state management, hermes_cli wrapper
routes.py All GET + POST route handlers (if/elif dispatch, no decorators)
state_sync.py /insights sync — message_count to state.db
streaming.py SSE engine, run_agent, cancellation, compression
updates.py Self-update check and release notes
upload.py Multipart parser, file upload handler
workspace.py File ops, workspace helpers, git detection
```
**Frontend (`static/`)**
```
index.html HTML template
style.css All CSS incl. mobile responsive, themes + skins
ui.js DOM helpers, renderMd, tool cards, context indicator
workspace.js File preview, file ops, git badge, central api() fetch wrapper
sessions.js Session CRUD, collapsible groups, search, reload recovery
messages.js send(), SSE handlers, live streaming, session recovery
panels.js Cron, skills, memory, profiles, settings (Control Center)
commands.js Slash command autocomplete
boot.js Mobile nav, voice input, theme/skin boot, bfcache handler
```
**Tests + packaging**
```
tests/ Pytest suite (~7,150 tests; isolated server/state fixtures)
pyproject.toml Tooling config (ruff lint gate) — not a packaged distribution
Dockerfile python:3.12-slim container image
docker-compose.yml Compose with named volume and optional auth
.github/workflows/ CI: ruff + sharded pytest, browser smoke, Docker smoke,
multi-arch Docker build + GitHub Release on tag
```
State lives outside the repo at `~/.hermes/webui/` by default
(sessions, workspaces, settings, projects, last_workspace). Override with `HERMES_WEBUI_STATE_DIR`.
Full design notes and the endpoint catalog are in [`ARCHITECTURE.md`](ARCHITECTURE.md).
---
## Docs
- `docs/why-hermes.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
- `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 per sprint
- `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets
- `THEMES.md` -- theme system documentation, custom theme guide
- `docs/CONTRACTS.md` -- project contract/RFC/design index for contributors and agents
- `docs/UIUX-GUIDE.md` -- UI/UX principles sourced from existing design docs and visual inventories
- `docs/docker.md` -- Docker compose setup, common failures, and bind-mount migration
- `docs/supervisor.md` -- launchd, systemd, supervisord, runit, and s6 process-supervisor setup
- `docs/onboarding.md` -- first-run wizard, provider setup, local model server Base URLs, and safe re-runs
- `docs/onboarding-agent-checklist.md` -- safety rules, evidence commands, and pass/fail checks for assistant-led install or reinstall support
- `docs/troubleshooting.md` -- diagnostic flows for common failures (e.g. "AIAgent not available")
- `docs/wsl-autostart.md` -- WSL2 auto-start at Windows login
- `docs/EXTENSIONS.md` -- administrator-controlled WebUI extension injection
- `docs/rfcs/README.md` -- RFC index for larger architecture and durability proposals
**Start here**
- [`docs/why-hermes.md`](docs/why-hermes.md) — why Hermes, the mental model, and a detailed comparison to Claude Code / Codex / OpenCode / Cursor
- [`docs/onboarding.md`](docs/onboarding.md) — first-run wizard, provider setup, local model server Base URLs, and safe re-runs
- [`docs/troubleshooting.md`](docs/troubleshooting.md) — diagnostic flows for common failures (e.g. "AIAgent not available")
**Using & customizing**
- [`THEMES.md`](THEMES.md) — theme + skin system, custom theme guide
- [`docs/workspace-git.md`](docs/workspace-git.md) — the workspace Git controls
- [`docs/EXTENSIONS.md`](docs/EXTENSIONS.md) — administrator-controlled WebUI extension injection
**Deploying & operating**
- [`docs/docker.md`](docs/docker.md) — Docker compose setup, common failures, and bind-mount migration
- [`docs/supervisor.md`](docs/supervisor.md) — launchd, systemd, supervisord, runit, and s6 process-supervisor setup
- [`docs/wsl-autostart.md`](docs/wsl-autostart.md) — WSL2 auto-start at Windows login
- [`docs/onboarding-agent-checklist.md`](docs/onboarding-agent-checklist.md) — safety rules and pass/fail checks for assistant-led install/reinstall support
**Contributing & design**
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution style, PR expectations, and local verification
- [`ARCHITECTURE.md`](ARCHITECTURE.md) — system design, all API endpoints, implementation notes
- [`TESTING.md`](TESTING.md) — manual browser test plan and automated coverage reference
- [`DESIGN.md`](DESIGN.md) — design tokens and the calm-console direction
- [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md) — UI/UX principles sourced from the design docs and visual inventories
- [`docs/CONTRACTS.md`](docs/CONTRACTS.md) — project contract/RFC/design index for contributors and agents
- [`docs/rfcs/README.md`](docs/rfcs/README.md) — RFC index for larger architecture and durability proposals
**Release history & plan**
- [`CHANGELOG.md`](CHANGELOG.md) — release notes per version
- [`ROADMAP.md`](ROADMAP.md) — feature roadmap and sprint history
- [`SPRINTS.md`](SPRINTS.md) — forward sprint plan with CLI + Claude parity targets
- [`CONTRIBUTORS.md`](CONTRIBUTORS.md) — the full community credit roll
## Contributors
Hermes WebUI is built with help from the open-source community. Every PR — whether merged directly, absorbed into a batch release, or salvaged from a larger proposal — shapes the project, and we're grateful to everyone who has taken the time to contribute.
**137 contributors have shipped code that landed in a release tag** as of v0.51.58. The full credit roll lives in [`CONTRIBUTORS.md`](CONTRIBUTORS.md). The highlights:
Over **137 contributors** have shipped code that landed in a release tag. The full,
continuously-updated credit roll — including everyone with one or two PRs and the
special-thanks roll for design and architectural work — lives in
[`CONTRIBUTORS.md`](CONTRIBUTORS.md). A snapshot of the most prolific contributors:
### Top contributors (by PR count, including absorbed/batch-released work)
ROADMAP.md
+1 -1
View File
@@ -2,7 +2,7 @@
> Web companion to the Hermes Agent CLI. Same workflows, browser-native.
>
> Last updated: v0.51.31 (May 9, 2026) — 5028 tests collected — Release H 12-PR contributor batch (image-mode fix + race fixes + composer drafts + locale parity + custom-provider dedup + TTL config + heartbeat polish)
> Last updated: v0.51.192 (May 31, 2026) — ~7,150 tests collected. Recent themes: forward-looking ruff lint gate (#3273), Windows upgrade state-stranding hotfix (#2905), per-model context_length default-only guard (#3256), gateway-configured banner + tooltip i18n, and an ongoing concentric PR-triage cadence.
> Test source: `pytest tests/ --collect-only -q`
> Per-version detail: see [CHANGELOG.md](./CHANGELOG.md)
TESTING.md
+4 -4
View File
@@ -1,14 +1,14 @@
# Hermes Web UI: Browser Testing Plan
> This document is for manual browser testing by you or by a Claude browser agent.
> It covers user-facing features of the UI through v0.50.21 and later releases.
> It covers user-facing features of the UI across current releases.
> Each section is written as a step-by-step test procedure with expected outcomes.
> A browser agent (e.g. Claude with Chrome access) can execute this plan directly.
>
> Prerequisites: SSH tunnel is active on port 8787. Open http://localhost:8787 in browser.
> Server health check: curl http://127.0.0.1:8787/health should return {"status":"ok"}.
>
> Automated coverage: 5303 tests collected via `pytest tests/ --collect-only -q`. Tests run on every PR via GitHub Actions on Python 3.11, 3.12, and 3.13. The suite covers the bootstrap/static wizard, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, CSS regression coverage for thinking/tool card animation, streaming session persistence, mobile layout breakpoints, locale parity across 11 languages, and hundreds of issue/PR-pinned regression tests.
> Automated coverage: ~7,150 tests collected via `pytest tests/ --collect-only -q`. Tests run on every PR via GitHub Actions on Python 3.11, 3.12, and 3.13 (3 parallel shards each), alongside a ruff lint gate, a headless browser smoke test, and a Docker smoke test. The suite covers the bootstrap/static wizard, real provider config persistence (`config.yaml` + `.env`), the `/api/onboarding/*` backend, the onboarding skip/existing-config guard, CSS regression coverage for thinking/tool card animation, streaming session persistence, mobile layout breakpoints, locale parity across 11 languages, and hundreds of issue/PR-pinned regression tests.
> Run: `pytest tests/ -v --timeout=60`
>
> Local regression focus: verify that a previously closed workspace panel stays visually closed from first paint through boot completion on desktop refresh; there should be no brief open-then-close flash.
@@ -1925,8 +1925,8 @@ Bridged CLI sessions:
---
*Last updated: v0.51.54, May 13, 2026*
*Total automated tests collected: 5303*
*Last updated: v0.51.192, May 31, 2026*
*Total automated tests collected: ~7,150 (run `pytest tests/ --collect-only -q` for the exact current count)*
*Regression gate: tests/test_regressions.py*
*Run: pytest tests/ -v --timeout=60*
*Source: <repo>/*