# Hermes Frontend

**Status:** Active development | **Version:** 0.6.42
**Production:** `https://jqxp.org` (Cloudflare static)

---

## What Is This

Vue 3 + TypeScript + Vite chat UI for OpenClaw agents.
Part of the **Hermes project** — the plugin-based successor to the original webchat.

Connects to `hermes/backend` (Bun) via WebSocket. Supports streaming, markdown rendering,
session history, handover, token cost tracking, file tree view, multi-modal input (images, PDFs, audio),
TTS playback, and real-time MCP-driven UI (counter, action picker, confetti).

---

## Stack

- Vue 3, TypeScript, Vite, Pinia, Vue Router
- marked (markdown rendering)
- WebSocket composable (`composables/ws.ts`)
- Session history from JSONL via backend (`composables/sessionHistory.ts`)
- Agent socket protocol (`composables/useAgentSocket.ts`)

---

## Key Files

```
src/
  views/
    AgentsView.vue                  main chat view
    DevView.vue                     dev tools, counter game, action picker
    ViewerView.vue                  file browser
    HomeView.vue                    landing page
  store/chat.ts                     Pinia store — sm state, messages, queue
  composables/
    ws.ts                           WS connect/reconnect/send
    useAgentSocket.ts               maps WS events → store actions
    sessionHistory.ts               history load + prev session fetch
    useMessages.ts                  message rendering (markdown, ANSI, code)
    useAttachments.ts               file/image/audio/PDF attach + upload
    useAudioRecorder.ts             mic recording with level visualization
    useTtsPlayer.ts                 ElevenLabs TTS playback
    useTheme.ts                     theme switching (titan/eras/loop42)
    agents.ts                       agent list, selection, display names
    auth.ts                         login / token handling
  components/
    AppSidebar.vue                  permanent rail sidebar, responsive
    TtsPlayerBar.vue                fixed TTS player bar
    AssistantMessage.vue            assistant bubble + speak button
    UserMessage.vue                 user bubble + audio/image/PDF display
    HudControls.vue                 NEW / HANDOVER / STOP buttons
    WebGLBackground.vue             particle background (theme-aware)
  utils/apiBase.ts                  API base URL (dev proxy / prod absolute)
```

---

## Current Port Situation (2026-03-13)

```
Port   What                   Status
───────────────────────────────────────────────────────
8443   webchat/frontend Vite  RUNNING (tmux webchat-vite) — wrong FE for hermes-dev
8444   hermes/frontend Vite   RUNNING (separate tmux)     — correct FE for hermes-dev
3001   webchat/backend        PROD (systemd)
3002   webchat/backend dev    RUNNING (tmux webchat-be)
3003   hermes/backend dev     NOT RUNNING
```

⚠️ hermes/fe currently serves on :8444. `dev.jqxp.org` nginx points to :8443 (wrong).
To use hermes-dev properly: reach it via `hermes.dev.jqxp.org` (→ :8444) until ports are aligned.

## Dev Setup

```bash
# Terminal 1 — Frontend (hermes/fe)
cd projects/hermes/frontend
npm run dev         # Vite on :8444 (configured in vite.config.ts)

# Terminal 2 — Backend (hermes/be)
cd projects/hermes/backend
PORT=3003 node --watch server.ts
```

Vite proxies `/ws` → `ws://localhost:3003`.
RouterVM: `hermes.dev.jqxp.org` → :8444 (FE only, BE not exposed externally yet).

---

## Deploy to Production

Build here, rsync to webspace:

```bash
cd projects/hermes/frontend
npm run build
sshpass -p '*KuHTW_9E.dvvWw' rsync -avz --delete \
  -e "ssh -o StrictHostKeyChecking=no -p 22" \
  dist/ u116526981@access1007204406.webspace-data.io:~/jqxp/
```

---

## Hermes vs Webchat (Legacy)

| Feature | webchat/frontend (legacy) | hermes/frontend (this) |
|---|---|---|
| Source of truth | ❌ archived | ✅ yes |
| Backend | Node.js server.js | Bun index.ts |
| Plugin channel | ❌ | ✅ openclaw hermes channel |
| File tree / workspace | ❌ | ✅ via Hermes backend APIs |
| Room mode (multi-user) | ❌ planned | 🔜 next milestone |

---

## Planned: Room Mode

```
DIRECT MODE (current)              ROOM MODE (next)
──────────────────────────────     ──────────────────────────────────
[Titan ▼] [New] [Handover]         [🏠 support-123]  Titan
                                   [● nico]  [● tina]  participant bar
messages: no sender label          messages: sender label per bubble
agent dropdown: visible            agent dropdown: hidden (room-scoped)
```

---

## Session Key Pattern

```
CURRENT:  agent:{agent}:web:{user}           e.g. agent:titan:web:nico
TARGET:   agent:{agent}:web:direct:{user}    private
          agent:{agent}:web:room:{roomId}    shared room (with Hermes plugin)
```

---

## Version

Defined in `package.json` → displayed in nav bar via `composables/ui.ts`.
Current: **0.3.19**