DasPoschi/hermes-webui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: freshen ROADMAP + ARCHITECTURE content + README notable-contrib counts

Browse Source 
- ROADMAP.md: 8-themes -> 11-skins in status snapshot; replace stale per-file
  LOC architecture table with role descriptions + CI gate list (ruff/shard/
  browser/docker); note LOC drifts.
- ARCHITECTURE.md: refresh File Inventory — drop chronically-stale per-file LOC,
  add missing modules (state_sync.py, updates.py, i18n/login/icons/sw.js,
  pyproject.toml, ctl.sh, CONTRIBUTORS.md), refresh test count to ~7,150.
- README.md: update the 8 'Notable contributions' blurb headers (PR counts +
  release ranges) to match the regenerated tally.
This commit is contained in:
nesquena-hermes
2026-06-01 02:16:57 +00:00
parent f14efc4368
commit 9d1b7b1d52
3 changed files with 58 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
ARCHITECTURE.md
View File

@@ -45,51 +45,63 @@ actions. The topbar remains focused on conversation context and the workspace/fi
## 2. File Inventory ## 2. File Inventory
<repo>/ <repo>/
server.py Thin routing shell + HTTP Handler + auth middleware. ~446 lines. server.py Thin routing shell + HTTP Handler + auth middleware.
Delegates all route handling to api/routes.py. Delegates all route handling to api/routes.py.
bootstrap.py One-shot launcher: optional agent install, deps, health wait, browser open. bootstrap.py One-shot launcher: optional agent install, deps, health wait, browser open.
start.sh Thin wrapper around bootstrap.py for shell-based startup. start.sh Thin wrapper around bootstrap.py for shell-based startup.
Dockerfile python:3.12-slim container image (~89 lines) ctl.sh Daemon lifecycle wrapper (start/stop/restart/status/logs) for homelab installs.
docker-compose.yml Compose config with named volume and optional auth (~57 lines) pyproject.toml Tooling config (ruff lint gate). NOT a packaged distribution.
Dockerfile python:3.12-slim container image
docker-compose.yml Compose config with named volume and optional auth
.dockerignore Excludes .git, tests/, .env* from Docker builds .dockerignore Excludes .git, tests/, .env* from Docker builds
api/ api/
__init__.py Package marker __init__.py Package marker
auth.py Optional password authentication, signed cookies (~366 lines) auth.py Optional password authentication, signed cookies, passkeys/WebAuthn
config.py Discovery, globals, model detection, reloadable config (~4139 lines) config.py Discovery, globals, model detection, reloadable config
helpers.py HTTP helpers: j(), bad(), require(), safe_resolve(), security headers (~302 lines) helpers.py HTTP helpers: j(), bad(), require(), safe_resolve(), security headers
models.py Session model + CRUD, per-session profile tracking (~1927 lines) models.py Session model + CRUD, per-session profile tracking, CLI/state.db bridge
profiles.py Profile state management, hermes_cli wrapper (~1056 lines) profiles.py Profile state management, hermes_cli wrapper
onboarding.py First-run onboarding status, real provider config writes, OAuth linking, and readiness detection (~1002 lines) onboarding.py First-run onboarding status, real provider config writes, OAuth linking, readiness detection
routes.py All GET + POST route handlers (~9772 lines) routes.py All GET + POST route handlers (if/elif dispatch, no decorators)
startup.py Startup helpers: auto_install_agent_deps() (~128 lines) startup.py Startup helpers: auto_install_agent_deps()
streaming.py SSE engine, run_agent, cancel, HERMES_HOME save/restore (~4420 lines) state_sync.py /insights sync — message_count to the agent's state.db
upload.py Multipart parser, file upload handler (~284 lines) streaming.py SSE engine, run_agent, cancel, compression, HERMES_HOME save/restore
workspace.py File ops: list_dir, read_file_content, workspace helpers (~810 lines) updates.py Self-update check and release notes
upload.py Multipart parser, file upload handler
workspace.py File ops: list_dir, read_file_content, git detection, workspace helpers
static/ static/
index.html HTML template (~1323 lines) index.html HTML template
style.css All CSS incl. mobile responsive (~3767 lines) style.css All CSS incl. mobile responsive, themes + skins, KaTeX
ui.js DOM helpers, renderMd, tool cards, model dropdown, file tree (~7216 lines) ui.js DOM helpers, renderMd, tool cards, context indicator, file tree
workspace.js File preview, file ops, loadDir, clearPreview (~369 lines) workspace.js File preview, file ops, git badge, central api() fetch wrapper
sessions.js Session CRUD, list rendering, search, SVG icons, dropdown actions (~3517 lines) sessions.js Session CRUD, list rendering, collapsible groups, search, SSE sync
messages.js send(), SSE event handlers, approval, transcript (~2301 lines) messages.js send(), SSE event handlers, approval/clarify, transcript, recovery
panels.js Cron, skills, memory, workspace, profiles, todo, settings (~6480 lines) panels.js Cron, skills, memory, profiles, todo, settings (Control Center)
commands.js Slash command registry, parser, autocomplete dropdown (~1302 lines) commands.js Slash command registry, parser, autocomplete dropdown
onboarding.js First-run wizard overlay, provider setup flow, and settings/workspace orchestration. boot.js Event wiring, mobile nav, voice input, theme/skin boot, bfcache handler
boot.js Event wiring, mobile sidebar/workspace nav, voice input, boot IIFE (~1607 lines) onboarding.js First-run wizard overlay, provider setup flow
i18n.js Localization catalog (en, es, de, zh, zh-Hant, ru, …)
login.js Login page + open-redirect guard
icons.js Lucide icon path registry
sw.js Service worker: offline shell cache, version-pinned assets
tests/ tests/
conftest.py Isolated test server/state fixtures (~644 lines) conftest.py Isolated test server/state fixtures
488 test files 5303 tests collected via pytest ~700 test files ~7,150 tests collected via pytest (run `pytest --collect-only -q` for exact)
test_regressions.py Permanent regression gate (~976 lines) test_regressions.py Permanent regression gate
CONTRIBUTING.md Contributor workflow and PR expectations. CONTRIBUTING.md Contributor workflow and PR expectations.
ROADMAP.md Feature and product roadmap document. ROADMAP.md Feature and product roadmap document.
SPRINTS.md Forward sprint plan with CLI + Claude parity targets. SPRINTS.md Forward sprint plan with CLI + Claude parity targets.
ARCHITECTURE.md THIS FILE. ARCHITECTURE.md THIS FILE.
TESTING.md Manual browser test plan and automated coverage reference. TESTING.md Manual browser test plan and automated coverage reference.
CHANGELOG.md Release notes per sprint. CHANGELOG.md Release notes per version.
BUGS.md Bug backlog and fixed items tracker. CONTRIBUTORS.md Community credit roll (regenerated via the maintainer workspace script).
requirements.txt Python dependencies. requirements.txt Python dependencies.
.env.example Sample environment variable overrides. .env.example Sample environment variable overrides.
> Per-file line counts intentionally omitted — they drift every release. Use
> `git ls-files | xargs wc -l` (or your editor) for current sizes; the role of
> each file above is the durable part.
State directory (runtime data, separate from source): State directory (runtime data, separate from source):
~/.hermes/webui/ ~/.hermes/webui/

18
README.md
View File

@@ -736,25 +736,25 @@ See [`CONTRIBUTORS.md`](CONTRIBUTORS.md) for the full ranked list of all 194 con
### Notable contributions ### Notable contributions
**[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (117 PRs, `v0.49.3` → `v0.51.58`) **[@franksong2702](https://github.com/franksong2702)** — Most prolific external contributor (148 PRs, `v0.49.3` → `v0.51.153`)
Across the longest tenure of any external contributor: the session title guard (#301), breadcrumb workspace navigation (#302), embedded workspace terminal (#1099), worktree-backed session creation (#2053), onboarding documentation (#2052), composer footer container queries, streaming-session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, manual `/compress` async start/status endpoints (#2128), worktree status surface (#2109) + guarded remove (#2156) for the lifecycle umbrella #2057, session post-render dedup (#2166), native-WebUI fast path (#2170), tail-window response trim (#2171), stale-stream guard extension (#2158), CSP report collector (#2160), and a long tail of polish across mobile/responsive, the session sidebar, and the workspace state machine. Across the longest tenure of any external contributor: the session title guard (#301), breadcrumb workspace navigation (#302), embedded workspace terminal (#1099), worktree-backed session creation (#2053), onboarding documentation (#2052), composer footer container queries, streaming-session sidebar exemption (#1327), session sidecar repair, cron output preservation (#1295), profile default workspace persistence, manual `/compress` async start/status endpoints (#2128), worktree status surface (#2109) + guarded remove (#2156) for the lifecycle umbrella #2057, session post-render dedup (#2166), native-WebUI fast path (#2170), tail-window response trim (#2171), stale-stream guard extension (#2158), CSP report collector (#2160), and a long tail of polish across mobile/responsive, the session sidebar, and the workspace state machine.
**[@Michaelyklam](https://github.com/Michaelyklam)** — Most prolific contributor of recent releases (92 PRs, `v0.50.240` → `v0.51.57`) **[@Michaelyklam](https://github.com/Michaelyklam)** — Most prolific contributor of recent releases (117 PRs, `v0.50.240` → `v0.51.139`)
Production Docker hardening (#1921, drops sudo-capable staging user), profile-scoped skills endpoints (#1903), gateway PID resolution under profile-scoped HERMES_HOME (#1901), profile-aware AIAgent cache (#1898/#1904), backslash LaTeX delimiters (#1848), Codex quota error surfacing (#1770), shell-route HTML 503 (#1836), stale Kanban client recovery (#1828), context auto-compression toast lifetime (#1988), `/goal` command (#1866), Kanban detail-view scrolling (#1916), CLI session tool metadata preservation (#1778), Traditional Chinese kanban locale backfill (#1979), v0.51.51 mobile Insights bucketing/layout (#2120/#2121), Hermes run adapter RFC (#2105 for #1925), fork-from-here absolute index (#2198 for #2184), opencode-go custom-provider overlap routing (#2204 for #1894). Production Docker hardening (#1921, drops sudo-capable staging user), profile-scoped skills endpoints (#1903), gateway PID resolution under profile-scoped HERMES_HOME (#1901), profile-aware AIAgent cache (#1898/#1904), backslash LaTeX delimiters (#1848), Codex quota error surfacing (#1770), shell-route HTML 503 (#1836), stale Kanban client recovery (#1828), context auto-compression toast lifetime (#1988), `/goal` command (#1866), Kanban detail-view scrolling (#1916), CLI session tool metadata preservation (#1778), Traditional Chinese kanban locale backfill (#1979), v0.51.51 mobile Insights bucketing/layout (#2120/#2121), Hermes run adapter RFC (#2105 for #1925), fork-from-here absolute index (#2198 for #2184), opencode-go custom-provider overlap routing (#2204 for #1894).
**[@bergeouss](https://github.com/bergeouss)** — Provider management UI + Docker hardening (62 PRs, `v0.48.0` → `v0.51.46`) **[@bergeouss](https://github.com/bergeouss)** — Provider management UI + Docker hardening (70 PRs, `v0.48.0` → `v0.51.46`)
Provider management UI for adding/editing custom providers from Settings, OAuth provider status detection (#1552), two-container Docker setup, profile isolation hardening (per-profile `.env` secrets), the bulk of what users see when they touch Settings → Providers, Reveal-in-Finder context menu (#1551), gateway status card (#1552), auto-assign session to active project filter (#1550), "What's new?" link in update banner (#1549), OpenRouter free-tier live fetch (#1548), credential pool 401 self-heal (#1553), inline provider chip + group model count in model picker (#1644). Provider management UI for adding/editing custom providers from Settings, OAuth provider status detection (#1552), two-container Docker setup, profile isolation hardening (per-profile `.env` secrets), the bulk of what users see when they touch Settings → Providers, Reveal-in-Finder context menu (#1551), gateway status card (#1552), auto-assign session to active project filter (#1550), "What's new?" link in update banner (#1549), OpenRouter free-tier live fetch (#1548), credential pool 401 self-heal (#1553), inline provider chip + group model count in model picker (#1644).
**[@ai-ag2026](https://github.com/ai-ag2026)** — Session recovery + audit infrastructure (55 PRs, `v0.50.279` → `v0.51.47`) **[@ai-ag2026](https://github.com/ai-ag2026)** — Session recovery + audit infrastructure (67 PRs, `v0.50.279` → `v0.51.190`)
Autonomous-AI contributor (Hermes Agent-driven) focused on durability: `state.db`-backed sidecar reconciliation (#2041), orphan `.json.bak` recovery on startup (#2035), read-only session recovery audit endpoints (#2036, #2040), active run lifecycle in `/health` (#2039), crash-safe turn-journal RFC at `docs/rfcs/turn-journal.md` (#2042), append-only turn-journal helper (#2059), lifecycle events layer (#2062), `Content-Security-Policy-Report-Only` header (#2084), per-cron toast toggle (#2100), fork-session compression lineage isolation (#2014). Autonomous-AI contributor (Hermes Agent-driven) focused on durability: `state.db`-backed sidecar reconciliation (#2041), orphan `.json.bak` recovery on startup (#2035), read-only session recovery audit endpoints (#2036, #2040), active run lifecycle in `/health` (#2039), crash-safe turn-journal RFC at `docs/rfcs/turn-journal.md` (#2042), append-only turn-journal helper (#2059), lifecycle events layer (#2062), `Content-Security-Policy-Report-Only` header (#2084), per-cron toast toggle (#2100), fork-session compression lineage isolation (#2014).
**[@dso2ng](https://github.com/dso2ng)** — Session lineage + diagnostics (23 PRs, `v0.50.227` → `v0.51.51`) **[@dso2ng](https://github.com/dso2ng)** — Session lineage + diagnostics (25 PRs, `v0.50.227` → `v0.51.153`)
`/api/session/lineage-report/<sid>` endpoint for bounded session graph diagnostics (#2012), stale Mermaid render error cleanup (#1337), `session_source="fork"` continuation-chain isolation (#2063), lazy lineage-report fetch on sidebar badge expand (#2130), and a long tail of frontend reliability fixes around session loading. `/api/session/lineage-report/<sid>` endpoint for bounded session graph diagnostics (#2012), stale Mermaid render error cleanup (#1337), `session_source="fork"` continuation-chain isolation (#2063), lazy lineage-report fetch on sidebar badge expand (#2130), and a long tail of frontend reliability fixes around session loading.
**[@jasonjcwu](https://github.com/jasonjcwu)** — Composer + transcript polish (16 PRs, `v0.50.227` → `v0.51.55`) **[@jasonjcwu](https://github.com/jasonjcwu)** — Composer + transcript polish (16 PRs, `v0.50.227` → `v0.51.132`)
Sidebar collapse via active-rail click (#2054, fuses #1884 + #1924), composer chip lightbox (#1758), title fixes for tool-heavy first turns, silent compress-status during session switch (#2185), concurrent-send loss fix (#2186), in-transcript steer message badges (#2187), and a string of frontend polish fixes. Sidebar collapse via active-rail click (#2054, fuses #1884 + #1924), composer chip lightbox (#1758), title fixes for tool-heavy first turns, silent compress-status during session switch (#2185), concurrent-send loss fix (#2186), in-transcript steer message badges (#2187), and a string of frontend polish fixes.
**[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming + UX polish (12 PRs, `v0.50.18` → `v0.51.58`) **[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming + UX polish (12 PRs, `v0.50.18` → `v0.51.66`)
Original sprint of workspace fallback resolution, live reasoning cards (#366, #367, #394–#397), then a recent burst: manual "Refresh usage" button on the Provider quota card (#2150), cancelled-turn status classification (#2151), Firefox sidebar scroll stabilization (#2200), early provisional session titles (#2202), target-aware "What's new?" update-banner links (#2207), and MCP tools overflow fix in Settings (#2210). Original sprint of workspace fallback resolution, live reasoning cards (#366, #367, #394–#397), then a recent burst: manual "Refresh usage" button on the Provider quota card (#2150), cancelled-turn status classification (#2151), Firefox sidebar scroll stabilization (#2200), early provisional session titles (#2202), target-aware "What's new?" update-banner links (#2207), and MCP tools overflow fix in Settings (#2210).
**[@aronprins](https://github.com/aronprins)** — `v0.50.0` UI overhaul (PR #242, plus 9 follow-ups) **[@aronprins](https://github.com/aronprins)** — `v0.50.0` UI overhaul (PR #242, plus 9 follow-ups)
@@ -766,10 +766,10 @@ Six consecutive, focused security PRs: session memory leak fix (expired token pr
**[@lucasrc](https://github.com/lucasrc)** — Auth-hardening trilogy (PRs #2191, #2192, #2193) **[@lucasrc](https://github.com/lucasrc)** — Auth-hardening trilogy (PRs #2191, #2192, #2193)
Three coordinated security PRs that all landed in v0.51.57: thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on Settings save, and the full 64-char HMAC-SHA256 session signature with a backwards-compatible migration bridge. The kind of cleanly-decomposed security work that's reviewable as three independent pieces. Three coordinated security PRs that all landed in v0.51.57: thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on Settings save, and the full 64-char HMAC-SHA256 session signature with a backwards-compatible migration bridge. The kind of cleanly-decomposed security work that's reviewable as three independent pieces.
**[@LumenYoung](https://github.com/LumenYoung)** — Streaming hot-path correctness (4 PRs, `v0.51.47` → `v0.51.55`) **[@LumenYoung](https://github.com/LumenYoung)** — Streaming hot-path correctness (8 PRs, `v0.51.47` → `v0.51.99`)
The original stale-stream writeback guard (#2136 — the bug class the next two releases extended), gateway-state alive-null classification (#2075), compression-banner anchor alignment (#2182), and context-progress ring auto-refresh on compression complete (#2188). Each PR opened a small surgical fix in one of the most fragile subsystems in the codebase. The original stale-stream writeback guard (#2136 — the bug class the next two releases extended), gateway-state alive-null classification (#2075), compression-banner anchor alignment (#2182), and context-progress ring auto-refresh on compression complete (#2188). Each PR opened a small surgical fix in one of the most fragile subsystems in the codebase.
**[@dobby-d-elf](https://github.com/dobby-d-elf)** — Frontend reliability + motion polish (6 PRs, `v0.51.38` → `v0.51.58`) **[@dobby-d-elf](https://github.com/dobby-d-elf)** — Frontend reliability + motion polish (15 PRs, `v0.51.38` → `v0.51.161`)
Workspace fallback on deleted directories (#2138), iPhone PWA bottom-scroll fix (#2143), the new "Activity: X tools" composer footer shimmer animation (#2203), and follow-up animation tuning (#2212). Workspace fallback on deleted directories (#2138), iPhone PWA bottom-scroll fix (#2143), the new "Activity: X tools" composer footer shimmer animation (#2203), and follow-up animation tuning (#2212).
**[@JKJameson](https://github.com/JKJameson)** — Composer + session polish (10 PRs) **[@JKJameson](https://github.com/JKJameson)** — Composer + session polish (10 PRs)

14
ROADMAP.md
View File

@@ -18,7 +18,7 @@
| **Sessions + projects + search** | ✅ CRUD, content search, projects, tags, archive, fork, import | | **Sessions + projects + search** | ✅ CRUD, content search, projects, tags, archive, fork, import |
| **Mobile + Docker + auth** | ✅ Hamburger nav, slide-overs, password auth, GHCR images | | **Mobile + Docker + auth** | ✅ Hamburger nav, slide-overs, password auth, GHCR images |
| **Auxiliary surfaces** | ✅ Workspace tree + edit, cron CRUD, skills CRUD, memory write, MCP server UI | | **Auxiliary surfaces** | ✅ Workspace tree + edit, cron CRUD, skills CRUD, memory write, MCP server UI |
| **Visual polish** | ✅ 8 themes (incl. light/system/OLED/Sienna), Mermaid, KaTeX, syntax highlighting | | **Visual polish** | ✅ Light/dark/system themes × 11 skins (default, ares, mono, slate, poseidon, sisyphus, charizard, sienna, catppuccin, nous, geist-contrast), Mermaid, KaTeX, syntax highlighting |
| **Native distribution** | ✅ macOS desktop app (universal arm64+x86_64 DMG, signed) — separate repo | | **Native distribution** | ✅ macOS desktop app (universal arm64+x86_64 DMG, signed) — separate repo |
Remaining gaps and forward work live in [Forward Work](#forward-work) below. Remaining gaps and forward work live in [Forward Work](#forward-work) below.
@@ -29,15 +29,17 @@ Remaining gaps and forward work live in [Forward Work](#forward-work) below.
| Layer | Files | Status | | Layer | Files | Status |
|---|---|---| |---|---|---|
| Python server | `server.py` (~165 lines) + `api/` modules (~20k lines) | Thin shell + auth middleware + business logic | | Python server | `server.py` + `api/` modules | Thin HTTP shell + auth middleware over the `api/` business logic (config, sessions, streaming, profiles, routes, onboarding, workspace, updates, upload) |
| HTML template | `static/index.html` (~600 lines) | Served from disk | | HTML template | `static/index.html` | Served from disk |
| CSS | `static/style.css` (~3k lines) | Themes, mobile responsive, KaTeX, table styles | | CSS | `static/style.css` | Themes + skins, mobile responsive, KaTeX, table styles |
| JavaScript | `static/{ui,sessions,messages,workspace,panels,boot,commands,icons,i18n,login,onboarding}.js` (~26k lines) | 11 modules served as static files | | JavaScript | `static/{ui,sessions,messages,workspace,panels,boot,commands,icons,i18n,login,onboarding}.js` | Vanilla-JS modules served as static files — no bundler |
| Service worker | `static/sw.js` | Offline shell cache, version-pinned assets | | Service worker | `static/sw.js` | Offline shell cache, version-pinned assets |
| Docker | `Dockerfile`, `docker-compose.yml` | `python:3.12-slim`, multi-arch (amd64+arm64), HEALTHCHECK | | Docker | `Dockerfile`, `docker-compose.yml` | `python:3.12-slim`, multi-arch (amd64+arm64), HEALTHCHECK |
| CI/CD | `.github/workflows/release.yml` | Auto-release + GHCR publish on tag push | | CI/CD | `.github/workflows/` | ruff lint + sharded pytest + browser smoke + Docker smoke on every PR; auto-release + GHCR publish on tag push |
| Test isolation | `tests/_pytest_port.py` | Per-worktree port + state-dir derivation, no collisions | | Test isolation | `tests/_pytest_port.py` | Per-worktree port + state-dir derivation, no collisions |
> Per-file line counts drift every release; see `ARCHITECTURE.md` for the current module map and `git ls-files` for exact sizes.
--- ---
## Feature parity checklist ## Feature parity checklist