rainysy/hermes-workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hermes-workspace/FEATURES-INVENTORY.md
Aurora release bot 7fe6f4a4bb fix(branding): restore Hermes naming across GitHub surfaces
2026-05-01 10:55:01 -04:00

740 lines
31 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Hermes Workspace — Comprehensive Features Inventory
> **Version:** 2.0.0 | **Stack:** React 19 + TanStack Start/Router + Vite 7 + Tailwind CSS 4 + Zustand + xterm.js + Monaco Editor
> **Description:** Desktop workspace for Hermes Agent — chat, orchestration, and multi-agent coding pipelines
---
## Table of Contents
1. [Frontend Screens & Features](#1-frontend-screens--features)
2. [Backend API Endpoints](#2-backend-api-endpoints)
3. [UI Components Library](#3-ui-components-library)
4. [Configuration & Settings](#4-configuration--settings)
5. [Server-Side Architecture](#5-server-side-architecture)
6. [Integrations & Provider Support](#6-integrations--provider-support)
7. [UX Features & Interactions](#7-ux-features--interactions)
8. [Security Features](#8-security-features)
9. [Mobile & PWA Features](#9-mobile--pwa-features)
10. [Deployment Options](#10-deployment-options)
---
## 1. Frontend Screens & Features
### 1.1 Chat Screen (`/chat`, `/chat/$sessionKey`)
- **Real-time SSE streaming** with tool call rendering
- **Multi-session management** — create, rename, delete, fork sessions
- **Dual chat backend modes:**
- **Enhanced Claude** — full session API with persistent history via Hermes Agent gateway
- **Portable** — OpenAI-compatible `/v1/chat/completions` (works with Ollama, LM Studio, vLLM, etc.)
- **Chat sidebar** — session list with search, pin, rename, delete dialogs
- **Message rendering:**
- Markdown with GFM support (`react-markdown` + `remark-gfm` + `remark-breaks`)
- Syntax highlighting via Shiki
- Tool call pill rendering with expandable details
- Thinking/reasoning content display
- Message timestamps
- Message actions bar (copy, etc.)
- **Chat composer** — multi-line input with:
- Slash command menu (`/new`, `/clear`, `/model`, `/save`, `/skills`, `/skin`, `/help`)
- File attachment support (images via base64, multimodal content)
- Voice input (Web Speech API)
- Context meter showing token usage percentage
- **Session management features:**
- Auto-generated session titles
- Session forking
- Session search across history
- Pinned sessions
- Session tombstones for deleted session cleanup
- **Inspector panel** — sidebar showing session activity, memory, and skills
- **Research card** — embedded research display
- **Connection status messaging** — real-time gateway connectivity indicators
- **Scroll-to-bottom button** for long conversations
- **Chat empty state** — onboarding content when no messages exist
- **Provider selection dialog** — model/provider chooser inline in chat
- **Smooth streaming text** — progressive text reveal for streaming responses
- **Context alert system** — warnings when approaching token limits
### 1.2 Dashboard Screen (`/dashboard`)
- Overview dashboard for workspace metrics
- Dashboard overflow panel for expanded views
### 1.3 Files Screen (`/files`)
- **Full workspace file browser** with directory tree navigation
- **File preview dialog** — inline file viewing
- **Monaco Editor integration** — full code editing
- **File operations:** create, read, write, rename, delete, mkdir
- **File upload** — multipart form upload support
- **Image preview** — base64 rendering for image files
- **Glob pattern support** — filter files by pattern
- **Path traversal prevention** — sandboxed to workspace root
- **Ignored directories:** `node_modules`, `.git`, `.next`, `.turbo`, `.cache`, `__pycache__`, `.venv`, `dist`
- **Max depth/entries limits** — configurable tree depth (default 3), max 20K entries
### 1.4 Terminal Screen (`/terminal`)
- **Full PTY terminal** via Python pty-helper
- **xterm.js** with addons: fit, search, web-links
- **256-color support** (TERM=xterm-256color, COLORTERM=truecolor)
- **Persistent shell sessions** — create, input, resize, close
- **SSE-based terminal streaming** — real-time output
- **Keepalive pings** every 8 seconds
- **Terminal workspace** component with debug panel
- **Mobile terminal input** — adapted for touch devices
- **Platform-aware default shell:** zsh (macOS), bash (Linux), PowerShell (Windows)
### 1.5 Memory Browser Screen (`/memory`)
- **Browse agent memory files** in `~/.hermes/` (MEMORY.md, memory/, memories/)
- **Search across memory entries** — text search with line-level results (max 200 matches)
- **Markdown preview** with live editing via MemoryEditor
- **Memory file list** — sorted with MEMORY.md first, daily files by date
- **Memory components:** MemoryFileList, MemorySearch, MemoryEditor, MemoryPreview
### 1.6 Skills Browser Screen (`/skills`)
- **Browse 2,000+ skills** from the Claude skill registry
- **Tabbed view:** Installed, Marketplace, Featured
- **Skill categories:** All, Web & Frontend, Coding Agents, Git & GitHub, DevOps & Cloud, Browser & Automation, Image & Video, Search & Research, AI & LLMs, Productivity, Marketing & Sales, Communication, Data & Analytics, Finance & Crypto
- **Search and filter** — by name, description, author, tags, triggers
- **Sort options:** by name, by category
- **Featured skills** curation with groups (Most Popular, New This Week, Developer Tools, Productivity)
- **Security risk display** — safe/low/medium/high levels with flags and scores
- **Workspace skills screen** — per-session skill management
### 1.7 Jobs Screen (`/jobs`)
- **Scheduled job management** — cron-style agent automation
- **Create job dialog** — schedule, prompt, name, delivery, skills, repeat config
- **Edit job dialog** — modify existing jobs
- **Job operations:** create, update, delete, pause, resume, trigger
- **Job output viewer** — view execution results
- **Job state tracking** — enabled/disabled, next/last run, success status
### 1.8 Settings Screens (`/settings`, `/settings/providers`)
- **Settings dialog** — centralized configuration panel
- **Providers screen** — manage AI provider connections
- **Provider wizard** — guided setup for new providers
---
## 2. Backend API Endpoints
### 2.1 Chat & Messaging
| Endpoint | Method | Description |
| -------------------- | ------ | -------------------------------------------------------------------------------- |
| `/api/send-stream` | POST | Main streaming chat endpoint — routes to enhanced Claude or portable OpenAI mode |
| `/api/send` | POST | Non-streaming chat send |
| `/api/sessions/send` | POST | Session-specific send |
| `/api/chat-events` | GET | SSE chat event stream |
| `/api/events` | GET | Global SSE event bus (keepalive, real-time updates) |
| `/api/history` | GET | Chat history retrieval |
### 2.2 Sessions
| Endpoint | Method | Description |
| -------------------------------------- | ------ | ------------------------------------- |
| `/api/sessions` | GET | List all sessions (paginated, max 50) |
| `/api/sessions` | POST | Create new session |
| `/api/sessions` | PATCH | Update session (rename) |
| `/api/sessions` | DELETE | Delete session |
| `/api/sessions/$sessionKey/status` | GET | Session status |
| `/api/sessions/$sessionKey/active-run` | GET | Active run for session |
| `/api/session-status` | GET | Session connection status |
### 2.3 Files
| Endpoint | Method | Description |
| ---------------------------- | ------ | ------------------------------------------- |
| `/api/files?action=list` | GET | List directory tree with depth/entry limits |
| `/api/files?action=read` | GET | Read file content (text or base64 image) |
| `/api/files?action=download` | GET | Download file with Content-Disposition |
| `/api/files` | POST | Write/upload/mkdir/rename/delete files |
| `/api/paths` | GET | Path resolution and workspace info |
### 2.4 Memory
| Endpoint | Method | Description |
| -------------------- | ------ | -------------------------------- |
| `/api/memory` | GET | Get memory from Hermes Agent gateway |
| `/api/memory/list` | GET | List local memory markdown files |
| `/api/memory/read` | GET | Read specific memory file |
| `/api/memory/search` | GET | Search across memory files |
| `/api/memory/write` | POST | Write/update memory file |
### 2.5 Skills
| Endpoint | Method | Description |
| ------------- | ------ | ----------------------------------------- |
| `/api/skills` | GET | List skills (paginated, filtered, sorted) |
| `/api/skills` | POST | Skill installation (currently disabled) |
### 2.6 Models & Config
| Endpoint | Method | Description |
| -------------------- | ------ | -------------------------------------------- |
| `/api/models` | GET | List available models (gateway + auth store) |
| `/api/claude-config` | GET | Read Hermes config.yaml and .env |
| `/api/claude-config` | PATCH | Update config.yaml and .env |
| `/api/context-usage` | GET | Token/context usage for a session |
### 2.7 Jobs
| Endpoint | Method | Description |
| ------------------------- | --------------------- | ---------------------------------------------- |
| `/api/claude-jobs` | GET | List all jobs |
| `/api/claude-jobs` | POST | Create new job |
| `/api/claude-jobs/$jobId` | GET/POST/PATCH/DELETE | Job CRUD and actions (pause/resume/run/output) |
### 2.8 Terminal
| Endpoint | Method | Description |
| ---------------------- | ------ | ---------------------------------------- |
| `/api/terminal-stream` | POST | Create PTY session and stream SSE output |
| `/api/terminal-input` | POST | Send input to terminal session |
| `/api/terminal-resize` | POST | Resize terminal dimensions |
| `/api/terminal-close` | POST | Close terminal session |
### 2.9 Auth & Infrastructure
| Endpoint | Method | Description |
| ------------------------ | ------ | --------------------------------------------- |
| `/api/auth` | POST | Password authentication (rate-limited: 5/min) |
| `/api/auth-check` | GET | Check authentication status |
| `/api/ping` | GET | Server ping/health |
| `/api/connection-status` | GET | Gateway connection status with capabilities |
| `/api/gateway-status` | GET | Detailed gateway capabilities |
| `/api/start-agent` | POST | Auto-start Claude agent process |
| `/api/start-claude` | POST | Start Hermes Agent gateway |
| `/api/workspace` | GET | Workspace auto-detection |
### 2.10 OAuth
| Endpoint | Method | Description |
| ------------------------ | ------ | ------------------------------- |
| `/api/oauth/device-code` | POST | Device code flow (Nous Portal) |
| `/api/oauth/poll-token` | POST | Poll for OAuth token completion |
---
## 3. UI Components Library
### 3.1 Core UI Primitives (`src/components/ui/`)
- **alert-dialog** — confirmation dialogs
- **autocomplete** — filterable autocomplete input
- **braille-spinner** — loading indicator with braille animation
- **button** — button variants (class-variance-authority)
- **collapsible** — expandable/collapsible sections
- **command** — command palette UI (cmdk-style)
- **dialog** — modal dialogs
- **input** — text input fields
- **menu** — dropdown menus
- **preview-card** — content preview cards
- **scroll-area** — custom scrollable areas
- **switch** — toggle switches
- **tabs** — tabbed interfaces
- **three-dots-spinner** — loading animation
- **toast** — notification toasts
- **tooltip** — hover tooltips
### 3.2 Prompt Kit (`src/components/prompt-kit/`)
- **chat-container** — main chat layout wrapper
- **message** — individual message rendering
- **markdown** — rich markdown rendering
- **code-block** — syntax-highlighted code with copy
- **prompt-input** — chat input component
- **tool** — tool call display
- **tool-indicator** — tool execution status
- **thinking** — thinking/reasoning block
- **thinking-indicator** — animated thinking state
- **typing-indicator** — typing animation
- **text-shimmer** — text loading shimmer effect
- **scroll-button** — scroll-to-bottom control
### 3.3 Feature Components
- **workspace-shell** — main app layout shell
- **chat-panel** — persistent side chat panel
- **chat-panel-toggle** — show/hide chat panel
- **command-palette** — global `⌘K` command palette
- **slash-command-menu** — `/` command autocomplete in chat
- **attachment-button** — file attachment trigger
- **attachment-preview** — attached file preview
- **export-menu** — export chat as Markdown/JSON/Text
- **context-meter** — token usage visualization
- **mode-selector** — preset mode selection
- **save-mode-dialog** / **apply-mode-dialog** / **rename-mode-dialog** / **manage-modes-modal** — full mode management UI
- **model-suggestion-toast** — smart model recommendations
- **keyboard-shortcuts-modal** — keyboard shortcut reference
- **global-shortcut-listener** — system-wide keyboard shortcuts
- **terminal-shortcut-listener** — terminal-specific shortcuts
- **connection-overlay** — full-screen connection status
- **connection-startup-screen** — initial loading/connection screen
- **backend-unavailable-state** — offline fallback UI
- **claude-health-banner** — gateway health indicator
- **claude-reconnect-banner** — reconnection prompt
- **error-boundary** — React error boundary
- **error-toast** — error notification
- **loading-indicator** — generic loading state
- **logo-loader** — branded loading animation
- **status-indicator** — colored status dots
- **empty-state** — empty content placeholder
- **theme-toggle** — light/dark theme switcher
### 3.4 Navigation & Layout
- **mobile-tab-bar** — bottom navigation for mobile
- **mobile-hamburger-menu** — hamburger menu for mobile
- **mobile-sessions-panel** — mobile session browser
- **mobile-page-header** — mobile header bar
- **mobile-prompt** — MobileSetupModal, MobilePromptTrigger
### 3.5 Specialized Components
- **memory-viewer/** — MemoryFileList, MemorySearch, MemoryEditor, MemoryPreview
- **file-explorer/** — file-explorer-sidebar, file-preview-dialog
- **terminal/** — terminal-panel, terminal-workspace, debug-panel, mobile-terminal-input
- **inspector/** — inspector-panel, activity-store
- **usage-meter/** — usage-meter, usage-meter-compact, usage-details-modal, context-alert-modal
- **search/** — search-modal, search-input, search-results, search-result-item, quick-actions
- **settings-dialog/** — settings-dialog
- **onboarding/** — claude-onboarding, onboarding-wizard, onboarding-tour, tour-steps, setup-step-content, provider-select-step
- **agent-chat/** — AgentChatModal, AgentChatHeader, AgentChatInput, AgentChatMessages
- **avatars/** — user-avatar, assistant-avatar
- **auth/** — login-screen
### 3.6 Provider & Model Components
- **provider-logo** — provider brand logos
- **provider-model-icon** — model-specific icons
- **agent-avatar** — AI agent avatar
- **agent-card** — agent info card
---
## 4. Configuration & Settings
### 4.1 User Settings (persisted via Zustand + localStorage)
| Setting | Type | Default | Description |
| ------------------------- | ------------------------------- | -------- | --------------------------- |
| `claudeUrl` | string | `''` | Hermes Agent API URL |
| `claudeToken` | string | `''` | Bearer token |
| `theme` | `system\|light\|dark` | `system` | Color mode |
| `accentColor` | `orange\|purple\|blue\|green` | `blue` | Accent color |
| `editorFontSize` | number | `13` | Monaco editor font size |
| `editorWordWrap` | boolean | `true` | Editor word wrap |
| `editorMinimap` | boolean | `false` | Editor minimap |
| `notificationsEnabled` | boolean | `true` | Sound/notifications |
| `usageThreshold` | number | `80` | Context usage warning % |
| `smartSuggestionsEnabled` | boolean | `false` | Smart model suggestions |
| `preferredBudgetModel` | string | `''` | Preferred cheap model |
| `preferredPremiumModel` | string | `''` | Preferred premium model |
| `onlySuggestCheaper` | boolean | `false` | Only suggest cheaper models |
| `showSystemMetricsFooter` | boolean | `false` | System metrics display |
| `mobileChatNavMode` | `dock\|integrated\|scroll-hide` | `dock` | Mobile nav behavior |
### 4.2 Theme System — 8 Themes
| Theme | Description | Mode |
| --------------------- | ------------------------------- | ----- |
| Claude Official | Navy and indigo flagship | Dark |
| Claude Official Light | Soft indigo light palette | Light |
| Claude Classic | Bronze accents on dark charcoal | Dark |
| Classic Light | Warm parchment with bronze | Light |
| Slate | Cool blue developer theme | Dark |
| Slate Light | GitHub-light with blue accents | Light |
| Mono | Clean monochrome grayscale | Dark |
| Mono Light | Bright monochrome grayscale | Light |
### 4.3 Workspace State (Zustand, persisted)
- Sidebar collapsed/expanded
- File explorer collapsed/expanded
- Chat focus mode
- Active sub-page route
- Chat panel open/closed + session key
- Mobile keyboard state
### 4.4 Modes System
- **Custom presets** — save/load named configurations
- Each mode stores: name, preferred model, smart suggestions toggle, budget/premium model prefs
- Drift detection — alerts when settings diverge from applied mode
### 4.5 Environment Variables
| Variable | Description |
| ---------------------- | -------------------------------------------------- |
| `HERMES_API_URL` | Backend API URL (default: `http://127.0.0.1:8642`) |
| `CLAUDE_PASSWORD` | Optional password protection for web UI |
| `CLAUDE_WORKSPACE_DIR` | Workspace root directory (default: `~/.hermes`) |
| `HERMES_AGENT_PATH` | Path to hermes-agent directory |
| `CLAUDE_DEFAULT_MODEL` | Default model override |
| `CLAUDE_ALLOWED_HOSTS` | Allowed hosts (default: `.ts.net`) |
| `ANTHROPIC_API_KEY` | Anthropic API key passthrough (optional) |
| `OPENAI_API_KEY` | OpenAI API key passthrough (optional) |
| `OPENROUTER_API_KEY` | OpenRouter API key passthrough (optional) |
| `GOOGLE_API_KEY` | Google Gemini API key passthrough (optional) |
| `HERMES_API_TOKEN` | Auth token for gateway API_SERVER_KEY |
| `BEARER_TOKEN` | Bearer token for backend auth |
| `PORT` | Server port (default: 3002 dev, 3000 prod) |
### 4.6 Claude Config Management
- **Read/write `~/.hermes/config.yaml`** — YAML config via web UI
- **Read/write `~/.hermes/.env`** — environment variables
- **Provider status** with masked API keys
- **Auth store integration** — reads from `~/.hermes/auth-profiles.json` and `~/.openclaw/agents/main/agent/auth-profiles.json`
---
## 5. Server-Side Architecture
### 5.1 Gateway Capability Probing
- **Two-tier capability model:**
- **Core:** health, chatCompletions, models, streaming
- **Enhanced:** sessions, skills, memory, config, jobs
- **Three chat modes:**
- `enhanced-claude` — full Claude session API
- `portable` — OpenAI-compatible /v1/chat/completions
- `disconnected` — no usable backend
- **Auto-detection** with port fallback (8642 → 8643)
- **Probe TTL** — 30 second cache, periodic refresh
- **Feature gates** — graceful degradation per capability
### 5.2 Chat Event Bus
- Server-side event bus for real-time updates
- SSE broadcasting to all connected clients
- Chat events: chunk, done, error, thinking, tool calls
### 5.3 Run Store (Persistence)
- Persisted run state at `~/.hermes/webui-mvp/runs/`
- Run lifecycle: accepted → active → handoff → stalled → complete → error
- Tool call tracking with phase management
- Lifecycle event logging (max 40 per run)
- Run timeout: 15 minutes
### 5.4 Terminal Sessions
- Python PTY helper (`pty-helper.py`) — real PTY without native node-pty addon
- Session management: create, input, resize (SIGWINCH), close (SIGTERM → SIGKILL)
- Event emitter pattern with early buffer for pre-listener output
### 5.5 Memory Browser (Server)
- Filesystem-based memory browsing in `~/.hermes/`
- File filters: MEMORY.md, memory/_, memories/_
- Markdown-only restriction
- Path traversal prevention
- Sort: MEMORY.md first, daily files by date descending, then by modification time
### 5.6 OpenAI-Compatible API Client
- Streaming parser for `/v1/chat/completions` SSE
- Support for reasoning/thinking content (DeepSeek, QwQ, etc.)
- Automatic default model detection from `/v1/models`
- Multimodal support (image_url content parts)
### 5.7 Hermes Agent Auto-Start
- Auto-detects sibling `hermes-agent/` directory
- Resolves Python virtualenv (`.venv`, `venv`, system `python3`)
- Spawns uvicorn with health polling (15 attempts, 1s interval)
- Reads `~/.hermes/.env` for agent configuration
### 5.8 Workspace Daemon (Optional)
- Separate workspace daemon process on port 3099
- Auto-restart with exponential backoff (max 20 retries)
- Provides workspace-level APIs (checkpoints, agents, etc.)
---
## 6. Integrations & Provider Support
### 6.1 AI Providers (Provider Catalog)
| Provider | Auth Types | Description |
| ---------- | ------------------ | ----------------------------------- |
| Anthropic | API Key, CLI Token | Claude models — Haiku, Sonnet, Opus |
| OpenAI | API Key | GPT and reasoning models |
| Google | API Key, OAuth | Gemini models |
| OpenRouter | API Key | Unified multi-provider access |
| MiniMax | API Key | Foundation models |
| Ollama | Local (no auth) | Local models |
| Custom | API Key | Any OpenAI-compatible server |
### 6.2 Known Gateway Providers (Claude Config)
- Nous Portal (OAuth device code flow)
- OpenAI Codex (OAuth)
- Anthropic (API key)
- OpenRouter (API key)
- Z.AI / GLM (API key)
- Kimi / Moonshot (API key)
- MiniMax / MiniMax CN (API key)
- Ollama (local, no auth)
- Custom OpenAI-compatible
### 6.3 Well-Known Models
- **Anthropic:** Claude Sonnet 4, Claude Opus 4
- **OpenAI:** GPT-4o
- **xAI:** Grok 3
- **Context window database:** Claude 4 (1M), Claude 3.x (200K), GPT-4o (128K), Gemini 2.x (1M), Qwen (32K–131K), Llama 3 (8K–128K), Mistral (32K–128K), DeepSeek (64K–128K)
### 6.4 OAuth Integration
- **Device code flow** for Nous Portal
- Token polling mechanism
- Auth profile storage in `~/.hermes/auth-profiles.json`
### 6.5 Workspace Agents
- Multi-agent directory with capabilities tracking
- Agent properties: model, provider, status (online/away/offline), avatar, system prompt
- Agent capabilities: repo write, shell commands, git operations, browser, network
- Agent stats: runs/tokens/cost today, success rate, avg response time
### 6.6 Workspace Checkpoints
- Code review checkpoint system
- Review actions: approve, approve-and-commit, approve-and-pr, approve-and-merge, reject, revise
- Diff viewing with file-level additions/deletions
- Verification checks: TypeScript (tsc), tests, lint, e2e
- Run event timeline
---
## 7. UX Features & Interactions
### 7.1 Sound Notification System
Web Audio API synthesized sounds (no audio files):
- **Agent Spawned** — ascending C5→E5 chime
- **Agent Complete** — satisfying G5 ding
- **Agent Failed** — low C3→A2 error tone
- **Chat Notification** — soft E5 ping
- **Chat Complete** — gentle E5→C5 descend
- **Alert** — attention-grab A4→E5→A4
- **Thinking** — subtle C6 tick
- Configurable volume (0–1) and enable/disable
### 7.2 Keyboard Shortcuts
- **⌘K** — Command palette
- **Global shortcuts** via `global-shortcut-listener`
- **Terminal shortcuts** via `terminal-shortcut-listener`
- **Session shortcuts** — navigate between sessions
- **Keyboard shortcuts modal** — discoverable reference
### 7.3 Voice Input
- Web Speech API integration
- Languages: configurable (default: en-US)
- States: idle, listening, processing, error
- Interim (partial) results support
- Toggle on/off
### 7.4 Haptic Feedback
- `navigator.vibrate(8)` for mobile tap feedback
### 7.5 Search
- **Global search modal** with quick actions
- **Search input** with keyboard navigation
- **Search results** with highlighted matches
- **Session search** across all chat history
### 7.6 Onboarding
- **Onboarding wizard** — first-run setup flow
- **Onboarding tour** — interactive guided tour (react-joyride)
- **Setup steps** — provider selection, connection verification
- **Tour steps** — feature highlights
### 7.7 Export
- Export conversations as Markdown, JSON, or Plain Text
### 7.8 Auto-Generated Session Titles
- Automatic title generation from conversation content
### 7.9 Pinned Sessions & Models
- Pin frequently used sessions for quick access
- Pin preferred models
### 7.10 Smart Model Suggestions
- Automatic model recommendations based on task
- Budget vs premium model preferences
- Model suggestion toast notifications
---
## 8. Security Features
### 8.1 Authentication
- Optional password protection via `CLAUDE_PASSWORD` env var
- Timing-safe password comparison
- Cryptographic session tokens (32 bytes hex)
- HTTP-only, SameSite=Strict cookies (30-day expiry)
- Rate-limited login: 5 attempts/minute per IP
- 1-second delay on failed auth (brute force prevention)
### 8.2 Authorization
- Auth middleware on all API routes
- Local request detection (127.0.0.1, ::1, Tailscale 100.x, LAN 192.168.x, 10.x)
- `requireLocalOrAuth` for sensitive operations (file delete, terminal)
### 8.3 Input Validation
- CSRF protection via `Content-Type: application/json` requirement
- Path traversal prevention on file and memory routes
- Zod schema validation on auth endpoints
- Input sanitization on all user inputs
### 8.4 Rate Limiting
- Sliding window rate limiter (in-memory, no external deps)
- Per-endpoint limits: auth (5/min), files (30/min), terminal (10/min)
- Auto-cleanup every 5 minutes
- 429 Too Many Requests responses
### 8.5 Error Handling
- Safe error messages in production (hides internals)
- Error boundaries in React
- Graceful degradation on gateway unavailability
---
## 9. Mobile & PWA Features
### 9.1 Progressive Web App
- Full PWA with install prompts
- iOS Safari "Add to Home Screen" support
- Android Chrome install support
- Desktop Chrome/Edge install support
### 9.2 Mobile-Specific Components
- Mobile tab bar (bottom navigation)
- Mobile hamburger menu
- Mobile sessions panel
- Mobile page header
- Mobile terminal input
- Mobile setup modal & prompt trigger
- Mobile keyboard handling & inset tracking
- Swipe navigation
### 9.3 Mobile Chat Nav Modes
- **Dock** — iMessage-style (no nav in chat)
- **Integrated** — chat input in nav pill
- **Scroll-hide** — nav shows on scroll up
### 9.4 Tailscale Integration
- First-class support for Tailscale remote access
- Default allowed hosts include `.ts.net`
- End-to-end encrypted mobile access
---
## 10. Deployment Options
### 10.1 Local Development
```bash
pnpm dev # Vite dev server with HMR on port 3002
```
### 10.2 Production Build
```bash
pnpm build && pnpm start # Node.js server on port 3000
```
### 10.3 Stable Mode
```bash
pnpm start:stable # Background process via scripts/start-stable.sh
pnpm stop:stable # Stop via scripts/stop-stable.sh
```
### 10.4 Docker Compose
- **hermes-agent** container — Python FastAPI gateway on port 8642
- **hermes-workspace** container — Node.js web UI on port 3000
- Health checks with retries
- Environment file passthrough
### 10.5 Auto-Start Features
- Claude agent auto-start from sibling directory
- Workspace daemon auto-start with crash recovery
- Port fallback detection (8642 → 8643)
---
## File/Directory Statistics
| Category | Count |
| ------------------ | ----- |
| Total source files | ~287 |
| API route files | ~35 |
| React components | ~100+ |
| Custom hooks | ~25 |
| Server modules | ~12 |
| Library utilities | ~20 |
| Store files | 3 |
| Screen files | 8 |
---
## Technology Stack
| Layer | Technology |
| ------------- | ------------------------------- |
| Framework | TanStack Start (React 19 + SSR) |
| Routing | TanStack Router (file-based) |
| Build | Vite 7 |
| Styling | Tailwind CSS 4 |
| State | Zustand 5 (persisted) |
| Data Fetching | TanStack React Query 5 |
| Terminal | xterm.js 5 + Python PTY |
| Editor | Monaco Editor |
| Markdown | react-markdown + Shiki |
| Charts | Recharts 3 |
| Animation | Motion (Framer Motion) |
| Validation | Zod |
| Icons | Hugeicons + Lobehub Icons |
| Tour | react-joyride |
| WebSocket | ws library |
| Config | YAML parser |
| Testing | Vitest + Testing Library |
---
_Generated from codebase analysis of `/Users/aurora/hermes-workspace/`_
Reference in New Issue View Git Blame Copy Permalink