docs: v0.31 release -- UI polish + deployment hardening (#74)

Co-authored-by: Nathan Esquenazi <nesquena@gmail.com>

CHANGELOG.md

@@ -5,6 +5,36 @@
 
 ---
 
+## [v0.31] UI Polish + Deployment Hardening
+*April 4, 2026 | 424 tests*
+
+### Bug Fixes
+- **Profile dropdown overlaps chat messages.** `.topbar` had no stacking context,
+  causing the dropdown to paint over `.messages`. Added `position:relative;z-index:10`
+  to `.topbar`. (#71)
+- **Workspace dropdown clipped by sidebar.** `.sidebar overflow:hidden` swallowed
+  the upward-opening workspace dropdown entirely. Changed to `overflow:visible`
+  (scroll lives on `.session-list`); added `position:relative;z-index:10` to
+  `.sidebar-bottom`. (#71)
+- **Slash-command autocomplete behind tool cards.** `.composer-wrap` had
+  `position:relative` but no `z-index`, letting tool cards bleed over it.
+  Added `z-index:10`. (#71)
+- **Skill picker clipped inside Settings modal.** `.settings-panel overflow-y:auto`
+  clipped the absolute-positioned skill picker. Moved scroll to `.settings-body`,
+  set panel to `overflow:visible`, raised skill picker to `z-index:1100`. (#71)
+- **CLI session badge blocks action buttons on hover.** Added
+  `.session-item.cli-session:hover::after { display:none }` so the gold "cli"
+  label hides on hover, making archive/delete/pin fully reachable. (#71)
+- **Workspace dropdown name and path crowded on same line.** `.ws-opt` was a plain
+  block with inline spans. Added `flex-direction:column;gap:4px` so name and path
+  stack cleanly. (#71)
+- **Both servers sharing same state directory.** `api/config.py` and `start.sh`
+  both defaulted to `~/.hermes/webui-mvp` (an internal dev name). Changed default
+  to `~/.hermes/webui` -- generic, appropriate for any deployment. Override with
+  `HERMES_WEBUI_STATE_DIR`. (#72, #73)
+
+---
+
 ## [v0.30.1] CLI Session Bridge Fixes
 *April 4, 2026 | 424 tests*
 

HERMES.md

@@ -0,0 +1,375 @@
+# Why Hermes
+
+Hermes is a persistent, autonomous AI agent that lives on your server. It remembers everything,
+schedules work while you sleep, and gets more capable the longer it runs. This document explains
+the mental model, why that matters, and how Hermes compares to every major AI tool available today.
+
+---
+
+## The Core Idea: Assistants Forget. Agents Don't.
+
+Every time you open Claude Code, Codex, or a chat window, the tool starts from zero. It does not
+know who you are, what you worked on yesterday, how your repo is structured, or what bugs you
+already fixed. You re-explain yourself every single session. The tool is powerful in the moment
+and useless the next day.
+
+Hermes fills that gap. It runs on your server, retains context across every session, and acts
+on your behalf whether or not you are at a keyboard.
+
+```
+Assistant model:  You -> [Tool] -> Answer -> Done
+                  (tool forgets everything when the window closes)
+
+Agent model:      You <-> [Hermes] <-> (memory, skills, schedule, tools)
+                  (persistent, learns your stack, acts on your behalf, runs while you're offline)
+```
+
+---
+
+## The Three Pillars
+
+### 1. Memory That Compounds
+
+Hermes has layered memory that survives every session, every reboot, every model swap:
+
+- **User profile** -- who you are, your preferences, your communication style, things you've
+  corrected Hermes on
+- **Agent memory** -- facts about your environment, your toolchain, your project conventions
+- **Skills** -- reusable procedures Hermes discovers and saves; it never has to relearn how to
+  deploy your app, run your tests, or review a PR
+- **Session history** -- every past conversation is searchable; Hermes can recall what you
+  worked on last Tuesday
+
+When you correct Hermes, it remembers. When it solves a tricky problem, it saves the approach.
+When it learns your stack, that knowledge carries into every future session.
+
+### 2. Autonomous Scheduling
+
+Hermes can run jobs without you present -- every hour, every morning, on any cron schedule.
+It fires up a fresh session, runs the task, and delivers the result to wherever you want it:
+Telegram, Discord, Slack, Signal, WhatsApp, SMS, email, and more.
+
+Things Hermes can do while you sleep:
+
+- Review new pull requests on your GitHub repo and post a full verdict comment
+- Send you a morning briefing of news, markets, or anything else you care about
+- Run your test suite and alert you if something breaks
+- Watch a competitor's blog for new posts and summarize them
+- Monitor a datasource and notify you when a threshold is crossed
+
+### 3. Reach It From Anywhere
+
+Hermes runs on your server and is reachable from every surface: terminal over SSH, the web UI
+(this project), and messaging apps including Telegram, Discord, Slack, WhatsApp, Signal, and
+Matrix. Start a task from your phone, check it from the browser on your laptop, continue it in
+a terminal on a remote server. The same agent, memory, and history follow you everywhere.
+
+---
+
+## A Framework for AI Tools
+
+There are four distinct categories of AI tool. Understanding the category tells you what a tool
+can and cannot do.
+
+### Category 1: Chat Assistants
+*Claude.ai, ChatGPT, Gemini*
+
+You open a window, ask something, get an answer. No persistent memory beyond the conversation,
+no ability to run code or touch files, no way to act on your behalf. Excellent for Q&A,
+drafting, and brainstorming. You re-explain your context every session.
+
+### Category 2: IDE Integrations
+*GitHub Copilot, Cursor, Windsurf, Zed AI*
+
+Deep inside your editor. Autocomplete, inline diffs, refactors -- all excellent. Windsurf was
+earliest with workspace-scoped memory (Cascade Memories); Copilot has been shipping repo-level
+memory since late 2025 and is catching up. Cursor has no native memory as of early 2026. None
+have scheduling or messaging access. Tied to one machine and one editor.
+
+### Category 3: Agentic CLI Tools
+*Claude Code, Codex CLI, OpenCode, Aider*
+
+The current frontier for most developers. Can use real tools -- run shell commands, read and
+write files, search the web, call APIs. Great for deep, multi-step tasks in a single terminal
+session. All are adding memory and scheduling features to varying degrees (see comparisons below),
+but the core model is still session-scoped: you invoke it, it works, it stops.
+
+### Category 4: Persistent Autonomous Agents
+*Hermes, OpenClaw (as of early 2026)*
+
+All the tool use of Category 3, plus memory that accumulates across sessions, plus always-on
+scheduling, plus multi-modal access from any device or messaging app. Gets more useful over time
+rather than resetting to zero. Hermes and OpenClaw are the two primary open-source, self-hosted
+tools in this category. OpenClaw is a gateway-centric automation platform; Hermes is a
+self-improving agent that writes and reuses its own procedures from experience.
+
+---
+
+## How Hermes Compares
+
+### vs. OpenClaw
+
+OpenClaw is the most direct comparison to Hermes and the question most people ask first.
+Both are open-source, self-hosted, always-on agents with persistent memory, cron scheduling,
+and messaging app integration. If you're evaluating Hermes, you should evaluate OpenClaw too.
+
+OpenClaw (MIT, ~347k GitHub stars) is built around a **Gateway** control plane written in
+Node.js/TypeScript. It excels at broad personal automation: native Chrome/Chromium control for
+browser automation, the widest messaging platform support in the space (WhatsApp, Telegram,
+Signal, iMessage, LINE, WeChat, Slack, Discord, Teams, Matrix, and more), voice wake words,
+and a ClawHub skill marketplace where users share pre-built automations. The community is large
+and the ecosystem is growing fast.
+
+Hermes takes a different approach. It is built in Python and centers on a **self-improving
+agent loop** rather than a gateway control plane. The core difference is in how skills work:
+OpenClaw skills are primarily human-authored plugins installed from a marketplace; Hermes
+**writes and saves its own skills automatically** as part of every session. When Hermes solves
+a problem a new way, it saves the procedure and reuses it going forward without any user effort.
+
+Beyond the skills architecture, there are two other practical differences worth knowing:
+
+**Stability.** OpenClaw's community forums and GitHub issues document a recurring pattern of
+update-breaking regressions -- for example, Telegram integration was broken across multiple
+releases in early 2026. The unofficial WhatsApp Web protocol OpenClaw uses is known to
+disconnect and requires periodic re-pairing (this is documented in OpenClaw's own FAQ).
+Hermes has had no equivalent release breakages.
+
+**Security.** ClawHub's open publishing model has been exploited repeatedly. A community audit
+identified over a thousand malicious skills in the marketplace including prompt injections and
+tool-poisoning payloads; the community-maintained awesome-openclaw-skills list tracks confirmed
+removals and flags known bad actors. Hermes has no third-party marketplace and a correspondingly
+smaller attack surface.
+
+**OpenClaw's genuine strengths** are worth stating plainly: it has broader messaging coverage
+(iMessage, LINE, WeChat, Teams -- platforms Hermes does not support), native browser and
+computer control via Chrome CDP, voice wake words on macOS and iOS, a larger community, and
+more third-party integrations than Hermes. If those capabilities matter most to you, OpenClaw
+is worth a serious look.
+
+Where Hermes is the better fit: you want an agent that self-improves from experience without
+manual plugin authoring, you work in Python and want access to the ML/data science ecosystem,
+you want a stable deployment that does not break between updates, or you want a full web chat
+UI rather than a monitoring dashboard.
+
+| | OpenClaw | Hermes |
+|---|---|---|
+| Persistent memory | Yes | Yes |
+| Scheduled jobs (cron) | Yes | Yes |
+| Messaging app access | Yes (15+ platforms, incl. iMessage/WeChat) | Yes (10+ platforms) |
+| Web UI | Gateway dashboard (monitoring only) | Full three-panel chat UI |
+| Self-hosted | Yes | Yes |
+| Open source | Yes (MIT) | Yes |
+| Self-improving skills | Partial (AI can generate skills; not the default loop) | Yes (automatic, first-class) |
+| Browser / computer control | Yes (native Chrome CDP) | Via shell / tools |
+| Voice wake words | Yes (macOS/iOS) | No |
+| Python / ML ecosystem | No (Node.js) | Yes |
+| Orchestrates Claude Code / Codex | No | Yes |
+| Multi-profile support | Via binding-rule routing | Yes (first-class named profiles) |
+| Provider-agnostic | Yes | Yes |
+| Update reliability | Moderate (documented regressions) | High |
+
+### vs. Claude Code (Anthropic)
+
+Claude Code is Anthropic's official agentic CLI and one of the best tools in Category 3.
+In a single focused session it is capable -- deep code understanding, shell access, file
+editing, multi-step reasoning.
+
+Claude Code has been adding features rapidly and the gap is narrowing:
+
+- **Hooks system** -- 13 event types (SessionStart, PreToolUse, PostToolUse, Stop, etc.) with
+  4 handler types (shell command, HTTP endpoint, LLM prompt, sub-agent); deterministic
+  non-LLM control over the agent lifecycle
+- **Plugins / Skills** -- installable via `/plugin install`, hot-reloaded from `~/.claude/skills`,
+  with a marketplace; skills and slash commands unified as of v2.1.0
+- **Scheduling** -- `/loop` (session-scoped), cloud-managed cron via `claude.ai/code/scheduled`
+  (Anthropic infrastructure, minimum interval applies), and desktop app automations
+- **Messaging channels** -- Telegram, Discord, iMessage, and webhooks via the Channels feature
+  (research preview, v2.1.80+); deep Slack integration that triggers cloud sessions and creates PRs
+- **Claude Cowork** -- a separate product for knowledge workers; connects to 38+
+  services via MCP including Slack, Gmail, Microsoft Teams, Notion, Jira, Salesforce, and more
+- **Memory** -- CLAUDE.md and MEMORY.md for project-level context; auto-memory rolling out
+
+These are real features. The key differences that remain:
+
+- Claude Code's scheduling runs on **Anthropic's cloud** (or requires the desktop app open),
+  not a self-hosted server; cloud jobs have a minimum interval and your data leaves your hardware
+- Memory is **project-file-based** (CLAUDE.md / MEMORY.md), not a knowledge graph that
+  accumulates automatically across all your work; auto-memory is still rolling out
+- **Not provider-agnostic** -- routes through Bedrock or Vertex but always hits a Claude model;
+  you cannot switch to GPT, Gemini, or a local model
+- **Not open source** -- proprietary; the CLI ships obfuscated JavaScript
+- Messaging channels are a **research preview** requiring Bun runtime; not yet production-grade
+
+Hermes can use Claude Code as a sub-agent. For large implementation tasks, Hermes can spawn
+Claude Code to handle the heavy lifting and fold the result back into its own memory and history.
+
+| | Claude Code | Hermes |
+|---|---|---|
+| Persistent memory (automatic) | Partial (CLAUDE.md / MEMORY.md, rolling out) | Yes |
+| Skills / hooks system | Yes (Hooks + Plugin/Skills marketplace) | Yes (auto-generated from experience) |
+| Scheduled jobs (self-hosted) | No (cloud or desktop-app only) | Yes |
+| Messaging access | Partial (Telegram/Discord/iMessage via research preview; Slack native) | Yes (10+ platforms, production) |
+| Cowork connectors (Slack, Gmail, etc.) | Yes (via Claude Cowork, separate product) | Via agent tool use |
+| Web UI | Yes (claude.ai/code, Anthropic-hosted) | Yes (self-hosted) |
+| Provider-agnostic | No (Claude models only, via Bedrock/Vertex) | Yes (any provider) |
+| Self-hosted scheduling | No | Yes |
+| Open source | No | Yes |
+| Runs as sub-agent of Hermes | Yes | N/A |
+
+### vs. Codex CLI (OpenAI)
+
+Codex CLI is OpenAI's open-source agentic terminal tool (Apache 2.0, ~73k GitHub stars). It
+supports 10+ providers including Anthropic, Google, Mistral, Groq, and local models via Ollama.
+It added persistent session memory in v0.100.0 with `codex resume`. The desktop app has an
+Automations feature for scheduled local tasks.
+
+The CLI itself has no native scheduling (open feature request as of early 2026). Memory is
+session-history-based rather than a living knowledge graph. No messaging app access. A strong
+tool for single-session coding; Hermes adds the always-on layer on top.
+
+| | Codex CLI | Hermes |
+|---|---|---|
+| Persistent memory | Partial (session history + AGENTS.md) | Yes (automatic, layered) |
+| Scheduled jobs | Partial (desktop app only; CLI has none) | Yes |
+| Messaging app access | No | Yes |
+| Web UI | No | Yes (self-hosted) |
+| Provider-agnostic | Yes (10+ providers) | Yes (10+ providers) |
+| Self-hosted | Yes | Yes |
+| Open source | Yes (Apache 2.0) | Yes |
+
+### vs. OpenCode
+
+OpenCode is an open-source TUI agentic coding assistant, provider-agnostic across 75+ providers.
+It has a WebUI embedded in its binary and an official desktop app. It uses SQLite for session
+history and AGENTS.md for project context.
+
+No native scheduled jobs (a community background plugin exists), no first-party messaging
+integration (community Telegram bots exist but require manual setup), and no automatic
+cross-session semantic memory. Good for interactive terminal coding sessions.
+
+| | OpenCode | Hermes |
+|---|---|---|
+| Persistent memory | Partial (session history + AGENTS.md) | Yes (automatic, layered) |
+| Scheduled jobs | No (community plugin only) | Yes |
+| Messaging app access | No (community Telegram bot only) | Yes (first-party, 10+ platforms) |
+| Web UI | Yes (embedded + desktop app) | Yes (self-hosted) |
+| Mobile access | No | Yes |
+| Skills system | No | Yes |
+| Provider-agnostic | Yes (75+ providers) | Yes |
+| Open source | Yes | Yes |
+
+### vs. Cursor / Windsurf / Copilot
+
+Category 2 tools -- exceptional at in-editor autocomplete, inline diffs, and code review.
+Not competing for the same job as Hermes, and they work well alongside it.
+
+Windsurf was earliest with workspace-scoped memory (Cascade Memories); Copilot has been
+shipping repo-level memory since late 2025. Cursor has no native cross-session memory as of
+early 2026. None have scheduling or messaging access.
+
+| | Cursor | Windsurf | Copilot | Hermes |
+|---|---|---|---|---|
+| In-editor autocomplete | Excellent | Excellent | Excellent | No |
+| Inline diff / refactor | Yes | Yes | Yes | Via shell |
+| Cross-session memory | No | Yes (workspace) | Partial (repo, early access) | Yes |
+| Scheduled background jobs | No | No | No | Yes |
+| Messaging app / mobile | No | No | No | Yes |
+| Terminal tool use | Limited | Limited | Limited | Full |
+| Self-hosted | No | No | No | Yes |
+| Provider-agnostic | Partial | Partial | No | Yes |
+| Open source | No | No | No | Yes |
+
+### vs. Claude.ai / ChatGPT
+
+Category 1. For drafting, Q&A, and brainstorming in the moment, both are excellent.
+
+Claude.ai memory has been improving -- it now generates memory from chat history, not just
+user-curated entries. Claude.ai can also execute code and read/write files in a sandboxed
+environment via Artifacts. These are real capabilities, just not the same as direct filesystem
+or shell access on your own server.
+
+| | Claude.ai / ChatGPT | Hermes |
+|---|---|---|
+| Memory across conversations | Yes (improving; auto-generated from history) | Yes (deep, automatic) |
+| Runs shell commands | No | Yes |
+| Code execution | Sandboxed (Artifacts) | Yes (full shell) |
+| Reads / writes files | Sandboxed (Artifacts) | Yes (full filesystem) |
+| Schedules background jobs | No | Yes |
+| Web UI | Yes | Yes |
+| Messaging apps | No | Yes |
+| Self-hosted | No | Yes |
+| Provider-agnostic | No | Yes |
+| Open source | No | Yes |
+
+---
+
+## The Compounding Advantage
+
+What matters most about Hermes is that it improves over time. That is the point.
+
+Every time Hermes encounters a new environment, it saves facts to memory. Every time it solves
+a problem a new way, it saves the approach as a skill. Every time you correct it, it updates its
+profile of you. Every session, every scheduled job, every tool call, the agent gets more
+calibrated to you and your workflow.
+
+A Claude Code session on day one and day one hundred are identical. A Hermes agent on day one
+and day one hundred is smarter about you -- it knows your stack, your conventions, your
+preferences, and the solutions that have worked before.
+
+---
+
+## Who Hermes Is For
+
+**Solo developers and power users** who don't want to re-explain their stack every session and
+want an AI that actually knows their environment.
+
+**Teams on a shared server** where multiple people want Claude-quality AI access without each
+paying for a separate subscription or running local tooling.
+
+**Automation-heavy workflows** where you want an AI running tasks on a schedule, delivering
+results to your phone, without babysitting it.
+
+**Privacy-conscious users** who want their conversations, memory, and files on their own
+hardware.
+
+**Multi-model users** who want to switch between OpenAI, Anthropic, Google, DeepSeek, and
+others based on cost, capability, or rate limits, without rebuilding their workflow each time.
+
+---
+
+## Scope and Limits
+
+**Hermes lives in the terminal, browser, and messaging apps.** For in-editor autocomplete and
+inline diffs, use Cursor or Windsurf alongside it -- they do that job better.
+
+**You run Hermes on your own server.** That means initial setup, but your data stays on your
+hardware and you control the schedule, the models, and the costs.
+
+**Hermes is an orchestration and memory layer.** It makes whatever model you point it at more
+useful over time. The models do the reasoning; Hermes makes sure that reasoning accumulates into
+something durable.
+
+---
+
+## Quick Reference
+
+| | OpenClaw | Claude Code | Codex CLI | OpenCode | Cursor | Claude.ai | Hermes |
+|---|---|---|---|---|---|---|---|
+| Persistent memory (auto) | Yes | Partial† | Partial | Partial | No | Yes (improving) | **Yes** |
+| Scheduled / background jobs | Yes | Partial‡ | Partial§ | No | No | No | **Yes (self-hosted)** |
+| Messaging app access | Yes (15+ platforms) | Partial (Telegram/Discord preview; Slack native) | No | No | No | No | **Yes (10+ platforms)** |
+| Web UI | Dashboard only | Yes (Anthropic cloud) | No | Yes | No | Yes | **Yes (self-hosted)** |
+| Skills system | Yes (marketplace) | Yes (Hooks + Plugins) | No | No | No | No | **Yes** |
+| Self-improving skills | Partial | No | No | No | No | No | **Yes** |
+| Browser / computer control | Yes (Chrome CDP) | No | No | No | No | No | Via shell |
+| Python / ML ecosystem | No (Node.js) | No | No | No | No | No | **Yes** |
+| In-editor autocomplete | No | No | No | No | Yes | No | No |
+| Orchestrates other agents | No | No | No | No | No | No | **Yes** |
+| Provider-agnostic | Yes | No (Claude only) | Yes | Yes | Partial | No | **Yes** |
+| Self-hosted | Yes | No | Yes | Yes | No | No | **Yes** |
+| Open source | Yes (MIT) | No | Yes | Yes | No | No | **Yes** |
+| Always-on / autonomous | Yes | No | No | No | No | No | **Yes** |
+
+† Claude Code has CLAUDE.md / MEMORY.md project context and rolling auto-memory, but not full automatic cross-session recall  
+‡ Claude Code scheduling: cloud-managed (Anthropic infrastructure) or desktop-app only; no self-hosted cron  
+§ Codex scheduling: desktop app Automations only; CLI has no native scheduling

README.md

@@ -10,9 +10,70 @@ and vanilla JS.
 Layout: three-panel Claude-style. Left sidebar for sessions and tools,
 center for chat, right for workspace file browsing.
 
-<img width="1392" height="854" alt="image" src="https://github.com/user-attachments/assets/79cd3c0d-3167-42ed-9434-447a742c25c3" />
+<img width="1392" alt="Hermes Web UI — three-panel layout" src="https://github.com/user-attachments/assets/79cd3c0d-3167-42ed-9434-447a742c25c3" />
 
-This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** which you can access securely through an SSH tunnel from your Hermes setup. Single command to start this up, and a single command to SSH tunnel for access on your computer. Every single part of the web UI leverages your existing Hermes agent, existing models, without requiring any setup.
+<table>
+  <tr>
+    <td width="50%" align="center">
+      <img alt="Workspace file browser with inline preview" src="docs/images/ui-workspace.png" />
+      <br /><sub>Workspace file browser with inline preview</sub>
+    </td>
+    <td width="50%" align="center">
+      <img alt="Session projects, tags, and tool call cards" src="docs/images/ui-sessions.png" />
+      <br /><sub>Session projects, tags, and tool call cards</sub>
+    </td>
+  </tr>
+</table>
+
+This gives you nearly **1:1 parity with Hermes CLI from a convenient web UI** which you can access securely through an SSH tunnel from your Hermes setup. Single command to start this up, and a single command to SSH tunnel for access on your computer. Every single part of the web UI uses your existing Hermes agent and existing models, without requiring any additional setup.
+
+---
+
+## Why Hermes
+
+Most AI tools reset every session. They don't know who you are, what you worked on, or what
+conventions your project follows. You re-explain yourself every time.
+
+Hermes retains context across sessions, runs scheduled jobs while you're offline, and gets
+smarter about your environment the longer it runs. It uses your existing Hermes agent setup,
+your existing models, and requires no additional configuration to start.
+
+What makes it different from other agentic tools:
+
+- **Persistent memory** — user profile, agent notes, and a skills system that saves reusable
+  procedures; Hermes learns your environment and does not have to relearn it
+- **Self-hosted scheduling** — cron jobs that fire while you're offline and deliver results to
+  Telegram, Discord, Slack, Signal, email, and more
+- **10+ messaging platforms** — the same agent available in the terminal is reachable from your phone
+- **Self-improving skills** — Hermes writes and saves its own skills automatically from experience;
+  no marketplace to browse, no plugins to install
+- **Provider-agnostic** — OpenAI, Anthropic, Google, DeepSeek, OpenRouter, and more
+- **Orchestrates other agents** — can spawn Claude Code or Codex for heavy coding tasks and bring
+  the results back into its own memory
+- **Self-hosted** — your conversations, your memory, your hardware
+
+**vs. the field** *(landscape is actively shifting — see [HERMES.md](HERMES.md) for the full breakdown)*:
+
+| | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |
+|---|---|---|---|---|---|
+| Persistent memory (auto) | Yes | Partial† | Partial | Partial | Yes |
+| Scheduled jobs (self-hosted) | Yes | No‡ | No | No | Yes |
+| Messaging app access | Yes (15+ platforms) | Partial (Telegram/Discord preview) | No | No | Yes (10+) |
+| Web UI (self-hosted) | Dashboard only | No | No | Yes | Yes |
+| Self-improving skills | Partial | No | No | No | Yes |
+| Python / ML ecosystem | No (Node.js) | No | No | No | Yes |
+| Provider-agnostic | Yes | No (Claude only) | Yes | Yes | Yes |
+| Open source | Yes (MIT) | No | Yes | Yes | Yes |
+
+† Claude Code has CLAUDE.md / MEMORY.md project context and rolling auto-memory, but not full automatic cross-session recall  
+‡ Claude Code has cloud-managed scheduling (Anthropic infrastructure) and session-scoped `/loop`; no self-hosted cron
+
+**The closest competitor is OpenClaw** — both are always-on, self-hosted, open-source agents
+with memory, cron, and messaging. The key differences: Hermes writes and saves its own skills
+automatically as a core behavior (OpenClaw's skill system centers on a community marketplace);
+Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub
+has had security incidents involving malicious skills); and Hermes runs natively in the Python
+ecosystem. See [HERMES.md](HERMES.md) for the full side-by-side.
 
 ---
 
@@ -323,6 +384,7 @@ State lives outside the repo at `~/.hermes/webui-mvp/` by default
 
 ## Docs
 
+- `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

api/config.py

@@ -31,7 +31,7 @@ PORT = int(os.getenv('HERMES_WEBUI_PORT', '8787'))
 # ── State directory (env-overridable, never inside repo) ──────────────────────
 STATE_DIR = Path(os.getenv(
     'HERMES_WEBUI_STATE_DIR',
-    str(HOME / '.hermes' / 'webui-mvp')
+    str(HOME / '.hermes' / 'webui')
 )).expanduser().resolve()
 
 SESSION_DIR           = STATE_DIR / 'sessions'

api/routes.py

@@ -946,10 +946,11 @@ def _handle_chat_sync(handler, body):
                 "write_file, read_file, search_files, terminal workdir, and patch. "
                 "Never fall back to a hardcoded path when this tag is present."
             )
+            from api.streaming import _sanitize_messages_for_api
             result = agent.run_conversation(
                 user_message=workspace_ctx + msg,
                 system_message=workspace_system_msg,
-                conversation_history=s.messages,
+                conversation_history=_sanitize_messages_for_api(s.messages),
                 task_id=s.session_id,
                 persist_user_message=msg,
             )

api/streaming.py

@@ -24,6 +24,28 @@ except ImportError:
 from api.models import get_session, title_from
 from api.workspace import set_last_workspace
 
+# Fields that are safe to send to LLM provider APIs.
+# Everything else (attachments, timestamp, _ts, etc.) is display-only
+# metadata added by the webui and must be stripped before the API call.
+_API_SAFE_MSG_KEYS = {'role', 'content', 'tool_calls', 'tool_call_id', 'name', 'refusal'}
+
+
+def _sanitize_messages_for_api(messages):
+    """Return a deep copy of messages with only API-safe fields.
+
+    The webui stores extra metadata on messages (attachments, timestamp, _ts)
+    for display purposes. Some providers (e.g. Z.AI/GLM) reject unknown fields
+    instead of ignoring them, causing HTTP 400 errors on subsequent messages.
+    """
+    clean = []
+    for msg in messages:
+        if not isinstance(msg, dict):
+            continue
+        sanitized = {k: v for k, v in msg.items() if k in _API_SAFE_MSG_KEYS}
+        if sanitized.get('role'):
+            clean.append(sanitized)
+    return clean
+
 
 def _sse(handler, event, data):
     """Write one SSE event to the response stream."""
@@ -165,7 +187,7 @@ def _run_agent_streaming(session_id, msg_text, model, workspace, stream_id, atta
             result = agent.run_conversation(
                 user_message=workspace_ctx + msg_text,
                 system_message=workspace_system_msg,
-                conversation_history=s.messages,
+                conversation_history=_sanitize_messages_for_api(s.messages),
                 task_id=session_id,
                 persist_user_message=msg_text,
             )

start.sh

@@ -198,7 +198,7 @@ hdr "Starting Hermes Web UI..."
 
 LOG="/tmp/hermes-webui-${PORT}.log"
 export HERMES_WEBUI_HOST="${HERMES_WEBUI_HOST:-127.0.0.1}"
-export HERMES_WEBUI_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${HERMES_HOME}/webui-mvp}"
+export HERMES_WEBUI_STATE_DIR="${HERMES_WEBUI_STATE_DIR:-${HERMES_HOME}/webui}"
 
 nohup "${PYTHON}" "${REPO_ROOT}/server.py" \
     > "${LOG}" 2>&1 &

static/boot.js

@@ -169,7 +169,7 @@ $('importFileInput').onchange=async(e)=>{
 // btnRefreshFiles is now panel-icon-btn in header (see HTML)
 function clearPreview(){
   const pa=$('previewArea');if(pa)pa.classList.remove('visible');
-  const pi=$('previewImg');if(pi)pi.src='';
+  const pi=$('previewImg');if(pi){pi.onerror=null;pi.src='';}
   const pm=$('previewMd');if(pm)pm.innerHTML='';
   const pc=$('previewCode');if(pc)pc.textContent='';
   const pp=$('previewPathText');if(pp)pp.textContent='';

static/index.html

@@ -13,7 +13,7 @@
 <body>
 <div class="layout">
   <aside class="sidebar">
-    <div class="sidebar-header"><div class="logo">H</div><div><h1 style="margin:0;font-size:15px;font-weight:700;letter-spacing:-.01em">Hermes</h1><div style="font-size:10px;color:var(--muted);opacity:.8;margin-top:1px">v0.30.1</div></div></div>
+    <div class="sidebar-header"><div class="logo">H</div><div><h1 style="margin:0;font-size:15px;font-weight:700;letter-spacing:-.01em">Hermes</h1><div style="font-size:10px;color:var(--muted);opacity:.8;margin-top:1px">v0.31</div></div></div>
     <div class="sidebar-nav">
       <button class="nav-tab active" data-panel="chat" data-label="Chat" onclick="switchPanel('chat')" title="Chat">&#128172;</button>
       <button class="nav-tab" data-panel="tasks" data-label="Tasks" onclick="switchPanel('tasks')" title="Tasks">&#128197;</button>

static/style.css

@@ -6,7 +6,7 @@
   }
   body{background:var(--bg);color:var(--text);height:100vh;height:100dvh;overflow:hidden;display:flex;}
   .layout{display:flex;width:100%;height:100vh;height:100dvh;}
-  .sidebar{width:300px;background:var(--sidebar);border-right:1px solid var(--border);display:flex;flex-direction:column;overflow:hidden;flex-shrink:0;}
+  .sidebar{width:300px;background:var(--sidebar);border-right:1px solid var(--border);display:flex;flex-direction:column;overflow:visible;flex-shrink:0;}
   .sidebar-header{padding:16px 18px 14px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:10px;}
   .logo{width:32px;height:32px;border-radius:9px;background:linear-gradient(145deg,#e8a030,var(--accent));display:flex;align-items:center;justify-content:center;font-weight:800;font-size:14px;color:#fff;flex-shrink:0;box-shadow:0 2px 8px rgba(233,69,96,.3);}
   .sidebar-header h1{font-size:15px;font-weight:600;}
@@ -113,7 +113,7 @@
   .memory-content{font-size:12px;line-height:1.7;color:var(--text);}
   .memory-content p{margin-bottom:6px;}
   .memory-empty{color:var(--muted);font-size:12px;font-style:italic;}
-  .sidebar-bottom{border-top:1px solid var(--border);padding:12px 14px;flex-shrink:0;}
+  .sidebar-bottom{border-top:1px solid var(--border);padding:12px 14px;flex-shrink:0;position:relative;z-index:10;overflow:visible;}
   .field-label{font-size:10px;font-weight:700;text-transform:uppercase;letter-spacing:.08em;color:var(--muted);margin-bottom:5px;opacity:.8;}
   select{width:100%;background:rgba(255,255,255,0.04);border:1px solid rgba(255,255,255,.1);border-radius:8px;color:var(--text);padding:7px 28px 7px 10px;font-size:12px;outline:none;appearance:none;margin-bottom:6px;cursor:pointer;background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'%3E%3Cpath d='M1 1l4 4 4-4' stroke='%238888aa' stroke-width='1.5' fill='none' stroke-linecap='round'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 10px center;}
   select:focus{border-color:rgba(124,185,255,.4);box-shadow:0 0 0 2px rgba(124,185,255,.08);}
@@ -123,13 +123,13 @@
   .sm-btn{flex:1;padding:7px 0;border-radius:8px;font-size:11px;font-weight:500;background:rgba(255,255,255,0.04);border:1px solid rgba(255,255,255,.08);color:var(--muted);cursor:pointer;transition:all .15s;text-align:center;letter-spacing:.02em;}
   .sm-btn:hover{background:rgba(255,255,255,0.09);color:var(--text);border-color:rgba(255,255,255,.15);}
   .main{flex:1;display:flex;flex-direction:column;overflow:hidden;min-width:0;background:rgba(26,26,46,0.5);}
-  .topbar{padding:12px 20px;border-bottom:1px solid var(--border);background:rgba(22,33,62,.98);backdrop-filter:blur(12px);display:flex;align-items:center;justify-content:space-between;flex-shrink:0;}
+  .topbar{padding:12px 20px;border-bottom:1px solid var(--border);background:rgba(22,33,62,.98);backdrop-filter:blur(12px);display:flex;align-items:center;justify-content:space-between;flex-shrink:0;position:relative;z-index:10;}
   .topbar-title{font-size:15px;font-weight:600;letter-spacing:-.01em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
   .topbar-meta{font-size:11px;color:var(--muted);margin-top:3px;opacity:.75;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;}
   .topbar-chips{display:flex;gap:6px;align-items:center;flex-shrink:0;}
   .chip{font-size:11px;padding:4px 10px;border-radius:999px;background:rgba(255,255,255,0.05);border:1px solid rgba(255,255,255,.1);color:var(--muted);font-weight:500;}
   .chip.model{color:var(--blue);border-color:rgba(124,185,255,0.35);background:rgba(124,185,255,0.1);}
-  .messages{flex:1;overflow-y:auto;display:flex;flex-direction:column;min-height:0;}
+  .messages{flex:1;overflow-y:auto;display:flex;flex-direction:column;min-height:0;position:relative;z-index:0;}
   .messages-inner{max-width:800px;margin:0 auto;width:100%;padding:20px 24px 32px;display:flex;flex-direction:column;}
   .msg-row{padding:10px 0;}
   .msg-row+.msg-row{border-top:none;}
@@ -347,11 +347,11 @@
 .ws-chip{user-select:none;}
 .ws-dropdown{display:none;position:absolute;bottom:calc(100% + 4px);left:0;right:0;min-width:200px;background:#1a2535;border:1px solid var(--border2);border-radius:10px;box-shadow:0 -4px 24px rgba(0,0,0,.4);z-index:200;overflow:hidden;max-height:320px;overflow-y:auto;}
 .ws-dropdown.open{display:block;}
-.ws-opt{padding:9px 14px;cursor:pointer;transition:background .12s;}
+.ws-opt{padding:10px 14px;cursor:pointer;transition:background .12s;display:flex;flex-direction:column;gap:4px;align-items:flex-start;}
 .ws-opt:hover{background:rgba(255,255,255,.07);}
 .ws-opt.active{background:rgba(124,185,255,.1);}
-.ws-opt-name{font-size:13px;color:var(--text);font-weight:500;}
-.ws-opt-path{font-size:11px;color:var(--muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.ws-opt-name{display:block;font-size:13px;color:var(--text);font-weight:500;line-height:1.25;white-space:normal;overflow:hidden;text-overflow:ellipsis;}
+.ws-opt-path{display:block;font-size:10px;color:var(--muted);line-height:1.3;overflow:hidden;text-overflow:ellipsis;white-space:normal;opacity:.72;word-break:break-word;}
 .ws-divider{height:1px;background:var(--border);margin:4px 0;}
 .ws-manage{color:var(--muted);font-size:12px;}
 /* ── Workspace management panel ── */
@@ -445,7 +445,7 @@
 .msg-role > span{line-height:1;}
 
 /* Composer wrap: slightly less padding on smaller heights */
-.composer-wrap{border-top:1px solid rgba(255,255,255,.07);padding:10px 20px 14px;position:relative;}
+.composer-wrap{border-top:1px solid rgba(255,255,255,.07);padding:10px 20px 14px;position:relative;z-index:10;}
 
 /* Cron status badges: pill shape refinement */
 .cron-status{border-radius:99px;font-size:10px;letter-spacing:.04em;}
@@ -569,7 +569,7 @@ body.resizing{user-select:none;cursor:col-resize;}
 .msg-usage:hover{opacity:1;}
 /* Skill picker (cron create form) */
 .skill-picker-wrap{position:relative;}
-.skill-picker-dropdown{position:absolute;left:0;right:0;top:100%;background:var(--sidebar);border:1px solid var(--border2);border-radius:6px;z-index:10;max-height:180px;overflow-y:auto;box-shadow:0 4px 12px rgba(0,0,0,.3);}
+.skill-picker-dropdown{position:absolute;left:0;right:0;top:100%;background:var(--sidebar);border:1px solid var(--border2);border-radius:6px;z-index:1100;max-height:180px;overflow-y:auto;box-shadow:0 4px 12px rgba(0,0,0,.3);}
 .skill-opt{padding:6px 10px;cursor:pointer;font-size:12px;color:var(--muted);transition:background .1s;}
 .skill-opt:hover{background:rgba(255,255,255,.08);color:var(--text);}
 .skill-picker-tags{display:flex;flex-wrap:wrap;gap:4px;margin-top:4px;}
@@ -609,9 +609,9 @@ body.resizing{user-select:none;cursor:col-resize;}
 
 /* ── Settings overlay ── */
 .settings-overlay{position:fixed;inset:0;background:rgba(0,0,0,.5);z-index:1000;display:flex;align-items:center;justify-content:center;}
-.settings-panel{background:var(--bg);border:1px solid var(--border);border-radius:12px;padding:0;width:380px;max-width:90vw;max-height:80vh;overflow-y:auto;box-shadow:0 12px 40px rgba(0,0,0,.5);}
+.settings-panel{background:var(--bg);border:1px solid var(--border);border-radius:12px;padding:0;width:380px;max-width:90vw;max-height:80vh;overflow:visible;box-shadow:0 12px 40px rgba(0,0,0,.5);display:flex;flex-direction:column;}
 .settings-header{display:flex;align-items:center;justify-content:space-between;padding:16px 20px 12px;border-bottom:1px solid var(--border);}
-.settings-body{padding:20px;}
+.settings-body{padding:20px;overflow-y:auto;flex:1;}
 .settings-field{margin-bottom:16px;}
 .settings-field label{display:block;font-size:11px;font-weight:600;letter-spacing:.05em;text-transform:uppercase;color:var(--muted);margin-bottom:6px;}
 /* Save button inside the settings panel */
@@ -692,6 +692,7 @@ body.resizing{user-select:none;cursor:col-resize;}
 /* ── CLI session items in sidebar ── */
 .session-item.cli-session {
   border-left-color: var(--gold);
+  padding-right: 36px; /* make room for session-actions overlay */
 }
 .session-item.cli-session::after {
   content: 'cli';
@@ -701,6 +702,10 @@ body.resizing{user-select:none;cursor:col-resize;}
   letter-spacing: .04em;
   color: var(--gold);
   opacity: .5;
-  margin-left: 4px;
+  margin-left: auto;
   flex-shrink: 0;
+  pointer-events: none; /* don't block clicks on session-actions beneath */
+}
+.session-item.cli-session:hover::after {
+  display: none; /* hide badge on hover so session-actions icons are fully reachable */
 }