webui/SPRINTS.md

# Hermes Web UI -- Forward Sprint Plan

> Current state: v0.22 | 382 tests | Daily driver ready
> This document plans the path from here to two targets:
>
> Target A: 1:1 feature parity with the Hermes CLI (everything you can do from the
>           terminal, you can do from the browser)
>
> Target B: 1:1 parity with Claude's reproducible features (the full Claude
>           browser UI experience, minus things only Anthropic can build)
>
> Sprints are ordered by impact. Each builds on the one before.
> Past sprint history lives in CHANGELOG.md.

---

## Where we are now (v0.21)

**CLI parity: ~90% complete.** Core agent loop, all tools visible, workspace
file ops with tree view, cron/skills/memory CRUD, session management, streaming,
cancel, multi-provider models, custom endpoint discovery, slash commands,
thinking/reasoning display, password auth -- all solid. Gaps are subagent
visibility, toolset control, and code execution.

**Claude parity: ~70% complete.** Chat, streaming, file browser, session
management, tool cards, syntax highlighting, model switching, projects,
settings, Mermaid diagrams, mobile layout, breadcrumb workspace nav, slash
commands, thinking display, auth -- all present. Gaps are artifacts, voice,
TTS, sharing, mobile-optimized layout.

---

## Sprint 11 -- Multi-Provider Models + Streaming Smoothness (COMPLETED)

**Theme:** Use any Hermes-supported model provider from the UI, and make
heavy agentic work feel fast and fluid.

**Why now:** Two high-impact gaps converge here. First, the model dropdown is
hardcoded to ~10 OpenRouter model strings. If Hermes is configured with direct
Anthropic, OpenAI, Google, or other API providers, the web UI can't use them.
This means users who set up Hermes with native API keys are locked out of
their own models in the browser. Second, the streaming render path rebuilds
the entire message list on every tool event, causing visible flicker during
heavy agentic work.

### Track A: Bugs
- Tool card DOM thrash: renderMessages() rebuilds all cards on each tool event.
  Switch to incremental append (append new card to existing group, no full rebuild).
- Scroll position lost on re-render during streaming (messages jump).

### Track B: Features
- **Multi-provider model support:** Query Hermes agent's configured providers
  and available models at startup via a new `GET /api/models` endpoint. The
  model dropdown populates dynamically from whatever providers the user has
  configured (OpenRouter, direct OpenAI, direct Anthropic, Google, DeepSeek,
  etc.). Group by provider. Fall back to the current hardcoded list if the
  agent query fails. This ensures the web UI can use any model the CLI can.
- **Incremental tool card streaming:** Instead of renderMessages() on each
  tool event, maintain a live card group element per turn and append/update
  cards in place. The assistant text row below the cards also updates
  incrementally (already does via assistantBody.innerHTML).
- **Smooth scroll:** Pin scroll to bottom during streaming unless user has
  manually scrolled up (read-back mode). Resume pinning when user scrolls
  back to bottom.

### Track C: Architecture
- `api/routes.py`: extract the 49 if/elif route handlers from server.py's
  Handler class into a dedicated routes module. server.py becomes a true
  ~50-line shell: imports, Handler stub that delegates to routes, main().
  Completes the server split started in Sprint 10.

**Tests:** ~15 new. Total: ~205.
**Hermes CLI parity impact:** High (model provider parity is a major CLI gap)
**Claude parity impact:** Low (streaming smoothness)

---

## Sprint 12 -- Settings Panel + Reliability + Session QoL

**Theme:** Persist your preferences, survive network blips, and organize sessions.

**Why now:** Three daily-driver friction points converge. First, default model
and workspace aren't persisted server-side -- every restart loses them. Second,
SSH tunnel hiccups during long agent runs silently kill the response with no
recovery. Third, after 50+ sessions the flat chronological list makes it hard
to keep important conversations accessible.

### Track A: Bugs
- Workspace validation on add doesn't check symlinks (shows as invalid when
  it's actually a valid symlink to a directory).

### Track B: Features
- **Settings panel:** A gear icon in the topbar opens a slide-in settings panel.
  Sections: Default Model, Default Workspace. Persisted server-side in
  `~/.hermes/webui-mvp/settings.json`. Server reads settings on startup and
  uses them as defaults. `GET /api/settings` + `POST /api/settings` endpoints.
- **SSE auto-reconnect:** When the EventSource connection drops mid-stream
  (network blip, SSH tunnel hiccup), auto-reconnect once using the same
  `stream_id`. The server-side queue holds undelivered events. If reconnect
  fails after 5s, show error banner. This is the #1 reliability gap for
  remote VPS usage.
- **Pin sessions:** A star icon on any session in the sidebar. Pinned sessions
  float to the top of the list above date groups. Persisted on the session
  JSON as `pinned: true`. Toggle on click. Simple and high quality-of-life.
- **Import session from JSON:** Drag a `.json` export file into the sidebar
  (or click an import button) to restore it as a new session. Mirrors the
  existing JSON export. Useful for moving sessions between machines.

### Track C: Architecture
- Settings schema: `settings.json` with typed fields, validated on load, with
  sane defaults. Served via `GET /api/settings`, written via `POST /api/settings`.
- SSE reconnect: server keeps `STREAMS[stream_id]` alive for 60s after
  client disconnect, allowing reconnect with the same stream_id.

**Tests:** ~15 new. Total: ~216.
**Hermes CLI parity impact:** Medium (settings persistence, reliability)
**Claude parity impact:** Medium (settings panel, pinned conversations)

---

## Sprint 13 -- Alerts, Session QoL, Polish

**Theme:** Know what Hermes is doing, and small quality-of-life wins.

**Why now:** Cron jobs run silently. Background errors surface nowhere. You have
no way to know a long-running task finished (or failed) while you were on another
tab. Meanwhile, a few small UX gaps (no session duplicate, no tab title) add up
to daily friction.

### Track A: Bugs
- Symlink workspace validation — confirmed already fixed (`.resolve()` follows
  symlinks before `is_dir()` check).

### Track B: Features
- **Cron completion alerts:** `GET /api/crons/recent?since=TIMESTAMP` endpoint.
  UI polls every 30s (only when tab is focused). Toast notification on each
  completion. Red badge count on Tasks nav tab, cleared when tab is opened.
- **Background agent error alerts:** When a streaming session errors out and
  the user is on a different session, show a persistent red banner above the
  message area: "Session X encountered an error." Click "View" to navigate,
  "Dismiss" to clear.
- **Session duplicate:** Copy icon on each session in the sidebar (visible on
  hover). Creates a new session with same workspace/model, titled "(copy)".
- **Browser tab title:** `document.title` updates to show the active session
  title (e.g. "My Task — Hermes"). Resets to "Hermes" when no session active.

**Tests:** ~10 new. Total: ~221.
**Hermes CLI parity impact:** Medium (cron visibility, error surfacing)
**Claude parity impact:** Low

---

## Sprint 14 -- Visual Polish + Workspace Ops + Session Organization (COMPLETED)

**Theme:** Polish the visual experience, close workspace file gaps, and
organize sessions properly.

### Track B: Features
- **Mermaid diagram rendering:** Code blocks tagged `mermaid` render as
  diagrams inline. Mermaid.js loaded lazily from CDN. Dark theme. Falls
  back to code block on parse error.
- **Message timestamps:** Subtle HH:MM time next to each role label. Full
  date/time on hover. User messages tagged with `_ts` on send.
- **Date grouping fix:** Session list uses `created_at` for groups instead
  of `updated_at`. Prevents sessions jumping between groups on auto-title.
- **File rename:** Double-click any filename in the workspace panel to
  rename inline (same pattern as session rename). `POST /api/file/rename`.
- **Folder create:** Folder icon button in workspace panel header.
  `POST /api/file/create-dir`. Prompt for folder name.
- **Session tags:** Add `#tag` to session titles. Tags extracted and shown
  as colored chips in the sidebar. Click a tag to filter the session list.
- **Session archive:** Archive button on each session (box icon). Archived
  sessions hidden from sidebar by default. "Show N archived" toggle at top
  of list. `POST /api/session/archive` endpoint.

**Tests:** ~12 new. Total: ~233.
**Hermes CLI parity impact:** Medium (file rename, folder create)
**Claude parity impact:** Medium (Mermaid, tags, archive)

---

## Sprint 15 -- Session Projects + Code Copy + Tool Card Toggle (COMPLETED)

**Theme:** Organize work the way you think, not just chronologically.
Plus two quick UX wins for code and agentic workflows.

**Why now:** After 100+ sessions the sidebar is a flat chronological list.
Finding sessions from 2 weeks ago, or keeping work separated by project,
requires the search box. Session projects are the single biggest remaining
organizational gap vs. Claude's project folders.

### Track A: Bugs
- None.

### Track B: Features
- **Session projects:** Named groups for organizing sessions. A project
  filter bar (subtle chips) sits between the search input and the session
  list. Each project has a name and color. Click a chip to filter sessions
  to that project; "All" shows everything. Create projects inline (+
  button), rename (double-click chip), delete (right-click). Assign
  sessions via folder icon button (hover-reveal) with a dropdown picker.
  Projects stored in `projects.json`. Session model gains `project_id`
  field (null = unassigned). Fully backward-compatible with existing
  sessions. Endpoints: `GET /api/projects`, `POST /api/projects/create`,
  `POST /api/projects/rename`, `POST /api/projects/delete`,
  `POST /api/session/move`.
- **Code block copy button:** Every code block gets a "Copy" button.
  Positioned in the language header bar (or top-right corner for plain
  code blocks). Click copies code to clipboard, shows "Copied!" for 1.5s.
- **Tool card expand/collapse:** When a message has 2+ tool cards, an
  "Expand all / Collapse all" toggle appears above the card group.
  Scoped per message group, not global.

### Track C: Architecture
- `projects.json` flat file storage for project list (same pattern as
  `workspaces.json` and `settings.json`).
- `project_id` field on Session model with backward-compatible null default.
- `_index.json` includes `project_id` for fast client-side filtering.

**Tests:** 13 new. Total: ~237.
**Hermes CLI parity impact:** Low (CLI has no session organization)
**Claude parity impact:** Very High (projects are a core Claude concept)

### Candidates for later sprints
- Artifacts + code execution (HTML/SVG preview, inline Python execution)
- Voice input via Whisper
- Subagent delegation cards (enhanced tool card rendering)

---

## Sprint 16 -- Session Sidebar Visual Polish (COMPLETED)

**Theme:** Make the session list feel high-quality and delightful.

**Why now:** The session sidebar had two visible UX bugs: titles truncated
unnecessarily because action icons reserved space even when hidden, and
the project folder icon felt "sticky" and awkward. Emoji icons rendered
inconsistently across platforms. These were the most common visual complaints.

### Track A: Bugs (from BUGS.md)
- **Session title truncation.** Action icons (pin, move, archive, dup, trash)
  were always in the DOM with `flex-shrink:0`, reserving ~30px even when
  invisible. Fix: wrapped all actions in a `.session-actions` overlay
  container with `position:absolute`. Titles now use full available width.
  Actions appear on hover with a gradient fade from the right edge.
- **Folder button feels sticky.** Replaced `.has-project` persistent blue
  button with a colored left border matching the project color. The folder
  button now only appears in the hover overlay like all other actions.

### Track B: Features
- **SVG action icons.** Replaced all emoji HTML entities (★, 📂, 📦, ⊕, 🗑)
  with monochrome SVG line icons that inherit `currentColor`. Consistent
  rendering across macOS, Linux, and Windows. Icons: pin (star), folder,
  archive (box), duplicate (overlapping squares), trash (bin with lines).
- **Pin indicator.** Small gold filled-star icon rendered inline before the
  title only when the session is actually pinned. Unpinned sessions get
  full title width with zero space reservation.
- **Project border indicator.** Sessions assigned to a project show a
  colored left border matching the project color, replacing the old
  always-visible blue folder button.
- **Hover overlay polish.** Actions container uses a gradient background
  that fades from transparent to the sidebar color, creating a smooth
  emergence effect. Overlay hides automatically during inline rename.

### Deferred to Sprint 17
- Slash commands (basic set with `commands.js` module)
- Thinking/reasoning display for extended-thinking models
- Slash command autocomplete popup

**Tests:** 74 new (test_sprint16.py: safe HTML rendering, XSS security, sidebar polish). Total: 289.
**Hermes CLI parity impact:** Low
**Claude parity impact:** Medium (sidebar polish matches Claude's quality bar)

---

## Sprint 17 -- Workspace Polish + Slash Commands + Settings (COMPLETED)

**Theme:** Workspace polish, slash commands, and composer settings.

**Why now:** Three things converge: @nothingmn filed Issue #22 requesting a
tree/accordion workspace view (breadcrumb navigation is the foundation for
that), slash commands were deferred from Sprint 16, and Issue #26 (send key
personalization) fits naturally since we are already touching the keydown
handler for slash command autocomplete.

### Track A: Workspace Breadcrumb Navigation
- **Breadcrumb path bar.** When users click into subdirectories, a breadcrumb
  bar appears showing the path (e.g. `~ / src / components`) with clickable
  segments to navigate back. Hidden at root level for a clean UI.
- **Up button.** Arrow-up button in the panel header navigates to the parent
  directory. Hidden when already at workspace root.
- **Current directory tracking.** `S.currentDir` state property tracks the
  active directory. File operations (rename, delete, new file, new folder)
  stay in the current directory instead of jumping back to root.
- **New file/folder in subdirectories.** Creating files or folders now respects
  the current directory, creating them in the viewed subdirectory.

### Track B: Slash Commands Foundation
- **commands.js module.** New 7th JS module with command registry, parser,
  autocomplete dropdown, and built-in command handlers.
- **Built-in commands:** `/help` (list commands), `/clear` (clear conversation),
  `/model <name>` (switch model with fuzzy match), `/workspace <name>` (switch
  workspace), `/new` (start new session).
- **Autocomplete dropdown.** Typing `/` in the composer shows a filtered
  dropdown. Arrow keys navigate, Tab/Enter select, Escape closes. Positioned
  above the composer using the workspace dropdown CSS pattern.
- **Transparent pass-through.** Unrecognized `/` commands pass through to the
  agent normally (not intercepted).

### Track C: Send Key Setting (Issue #26)
- **`send_key` setting.** New setting in Settings panel: "Enter" (default) or
  "Ctrl+Enter". Persisted to `settings.json`. Loaded on boot.
- **Keydown handler rewrite.** Combined handler for autocomplete navigation
  and send key preference. When `ctrl+enter` is selected, plain Enter inserts
  a newline and Ctrl/Cmd+Enter sends.

### Deferred to Sprint 18
- Thinking/reasoning display for extended-thinking models
- Voice input via Whisper
- Workspace tree/accordion view (full implementation of Issue #22)

**Tests:** 6 new (test_sprint17.py). Total: 318.
**Hermes CLI parity impact:** Low (slash commands add convenience)
**Claude parity impact:** Medium (workspace nav, slash commands match Claude UX)

---

## Sprint 18 -- Thinking Display + Workspace Tree + Preview Fix (COMPLETED)

**Theme:** Show the model's reasoning, improve workspace navigation, fix UX bug.

**Why now:** Thinking/reasoning display was deferred twice (Sprint 16 → 17 → 18).
Workspace tree view was the #1 community request (Issue #22). File preview
staying open on directory navigation was a daily-driver annoyance.

### Track A: Bugs
- **File preview auto-close.** When viewing a file in the right panel and
  navigating directories (breadcrumbs, up button, folder clicks), the preview
  stayed visible with stale content. Fix: extracted `clearPreview()` as a named
  function in boot.js and call it from `loadDir()` in workspace.js.

### Track B: Features
- **Thinking/reasoning display.** Assistant messages with structured content
  arrays containing `type:'thinking'` or `type:'reasoning'` blocks now render
  as collapsible gold-themed cards above the response text. Collapsed by
  default, click header to expand. Works with Claude extended thinking and
  o3 reasoning tokens when preserved in the message array.
- **Workspace tree view (Issue #22).** Directories expand/collapse in-place
  with toggle arrows. Single-click toggles, double-click navigates (breadcrumb
  view). Subdirectory contents fetched lazily and cached in `S._dirCache`.
  Nesting depth shown via indentation. Empty directories show "(empty)".

**Tests:** 0 new (pure CSS/DOM changes). Total: 318.
**Hermes CLI parity impact:** Low
**Claude parity impact:** High (reasoning display matches Claude's UI)

---

## Sprint 19 -- Auth + Security Hardening (COMPLETED)

**Theme:** Make this safe to leave running beyond localhost.

**Why now:** Issue #23 requested authentication. Auth is the last production
hardening feature before the app is safe to expose to a network.

### Track A: Bugs
- **No request size limit.** POST bodies were unbounded (DoS risk). Added 20MB
  cap in `read_body()`.

### Track B: Features
- **Password authentication (Issue #23).** Off by default — zero friction for
  localhost. Enable via `HERMES_WEBUI_PASSWORD` env var or Settings panel.
  Password-only (no username — single-user app). Signed HMAC HTTP-only cookie
  with 24h TTL. Minimal dark-themed login page at `/login`. API calls without
  auth return 401; page loads redirect to `/login`. Settings panel gains
  "Access Password" field and "Sign Out" button.
- **Security headers.** All responses now include `X-Content-Type-Options: nosniff`,
  `X-Frame-Options: DENY`, `Referrer-Policy: same-origin`.

### Track C: Architecture
- New `api/auth.py` module: password hashing (SHA-256 + STATE_DIR salt), signed
  session cookies, auth middleware, public path allowlist.
- Auth check in `server.py` do_GET/do_POST before routing.
- `password_hash` added to `_SETTINGS_DEFAULTS` in config.py.
- `_set_password` special field in save_settings for secure password updates.

**Tests:** 10 new. Total: 328.
**Hermes CLI parity impact:** Low (CLI has no auth concerns)
**Claude parity impact:** High (Claude is authenticated)

---

## Sprint 20 -- Voice Input + Send Button Polish (COMPLETED)

**Theme:** Input refinements — voice and visual polish.

**Why now:** Voice input was the next feature on the roadmap. The send button
UX was a low-effort high-impact polish opportunity that pairs naturally.

### Track A: Bugs
- **Send button always visible.** The old pill-shaped "Send" button was always
  visible even with an empty textarea, wasting space. Now hidden by default,
  appears only when there is content to send.

### Track B: Features
- **Voice input (Web Speech API).** Microphone button in composer. Tap to
  record, tap again to stop. Live interim transcription in textarea. Auto-stops
  after ~2s of silence. Appends to existing text. Hidden when browser doesn't
  support Web Speech API. No API keys, no server changes.
- **Send button polish.** Icon-only 34px circle with upward arrow SVG. Pop-in
  spring animation on appear. Scale hover/active for tactile feedback. Hidden
  while agent is responding.

### Track C: Architecture
- Voice input IIFE in `boot.js` with SpeechRecognition lifecycle.
- `updateSendBtn()` in `ui.js` hooked into setBusy, renderTray, autoResize.

**Tests:** 52 new (voice) + 33 new (send button). Total: 413.
**Hermes CLI parity impact:** Medium (voice not in CLI, but adds capability)
**Claude parity impact:** High (Claude has native voice mode)

---

## Sprint 21 -- Mobile Responsive (PLANNED)

**Theme:** A genuinely good mobile experience, not just responsive CSS.

### Track B: Features
- **Collapsible sidebar.** Hamburger menu replaces the always-visible sidebar.
- **Touch-friendly session list.** Tap to navigate, swipe gestures.
- **Right panel as tab.** Files panel hidden by default, accessible via tab.
- **Composer focus behavior.** Expands on focus, keyboard-aware.
- Consider a separate mobile-optimized layout rather than just media queries.

---

## Sprint 22 -- Multi-Profile Support (PLANNED, Issue #28)

**Theme:** Switch between Hermes agent profiles seamlessly.

### Track B: Features
- **Profile picker.** Sidebar or topbar dropdown to switch profiles.
- **Per-profile config.** Each profile has its own skills, memory, config.yaml.
- **Seamless switching.** No restart required.

---

## Sprint 23 -- Desktop Application (PLANNED)

**Theme:** Native desktop experience.

### Track B: Features
- **Electron or Tauri wrapper.** Native window, menu bar, notifications.
- **Auto-start option.** Launch on login.
- **Packaged distribution.** .dmg (macOS), .exe (Windows).

---

## Sprint 24 -- Extended Command Support (PLANNED)

**Theme:** Deeper slash command and skill integration.

### Track B: Features
- **Skill-aware autocomplete.** `/skill-name` triggers installed skills.
- **Command chaining.** Compose multi-step commands.
- **Agent tool exposure.** Surface agent capabilities as slash commands.

---

## Feature Parity Summary

### Hermes CLI Parity (as of Sprint 19)

| CLI Feature | Status |
|-------------|--------|
| Chat / agent loop | Done (v0.3) |
| Streaming responses | Done (v0.5) |
| Tool call visibility | Done (v0.11) |
| File ops (read/write/search/patch) | Done (v0.6) |
| Terminal commands | Done via workspace |
| Cron job management | Done (v0.9) |
| Skills management | Done (v0.9) |
| Memory read/write | Done (v0.9) |
| Session history | Done (v0.3) |
| Workspace switching | Done (v0.7) |
| Model selection | Done (v0.3) |
| Multi-provider model support | Done (Sprint 11) |
| Settings persistence | Done (Sprint 12) |
| Cron completion alerts | Done (Sprint 13) |
| Slash commands | Done (Sprint 17) |
| Thinking/reasoning display | Done (Sprint 18) |
| Auth / login | Done (Sprint 19) |
| Voice input | Sprint 20 |
| Subagent visibility | Deferred |
| Code execution (Jupyter) | Deferred |
| Toolset control | Deferred |
| Virtual scroll (perf) | Deferred |

### Claude Parity (as of Sprint 19)

| Claude Feature | Status |
|----------------|--------|
| Dark theme, 3-panel layout | Done (v0.1) |
| Streaming chat | Done (v0.5) |
| Model switching | Done (v0.3) |
| File attachments | Done (v0.6) |
| Syntax highlighting | Done (v0.10) |
| Tool use visibility | Done (v0.11) |
| Edit/regenerate messages | Done (v0.10) |
| Session management | Done (v0.6) |
| Mermaid diagrams | Done (Sprint 14) |
| Projects / folders | Done (Sprint 15) |
| Pinned/starred sessions | Done (Sprint 12) |
| Notifications | Done (Sprint 13) |
| Settings panel | Done (Sprint 12) |
| Reasoning display | Done (Sprint 18) |
| Auth / login | Done (Sprint 19) |
| Mobile layout (basic) | Done (v0.16.1) |
| Workspace tree view | Done (Sprint 18) |
| Slash commands | Done (Sprint 17) |
| Voice input | Sprint 20 |
| TTS playback | Sprint 20 |
| Artifacts (HTML/SVG preview) | Deferred |
| Code execution inline | Deferred |
| Mobile-optimized layout | Sprint 21 |
| Sharing / public URLs | Not planned (requires server infra) |
| Claude-specific features | Not replicable (Projects AI, artifacts sync) |

### What is intentionally not planned

- **Sharing / public conversation URLs:** Requires a hosted backend with access
  control and CDN. Out of scope for a personal VPS deployment.
- **Claude-specific model features:** Claude-native Projects memory, extended
  artifacts sync, Anthropic's proprietary reasoning UI. These are Anthropic
  infrastructure, not reproducible.
- **Real-time collaboration:** Multiple users in the same session simultaneously.
  Single-user assumption throughout.
- **Plugin marketplace:** Hermes skills cover this use case already.

---

*Last updated: April 3, 2026*
*Current version: v0.22 | 382 tests*
*Next sprint: Sprint 21 (Mobile Responsive)*