Crash Recovery Flow

After a crash — identify what's broken → find which file owns it → apply the fix

After a crash — what's broken? identify the symptom → find the owning file → apply fix Chat history missing after restart sessions empty Owner ~/.hermes/sessions.db Fix restart agent → reload if DB corrupted: restore sessions.db.bak.* Auth tokens broken logged out / 401 browser sessions invalid Owner workspace-sessions.json Fix rm workspace-sessions.json file recreated on next authenticated request URL overrides lost custom gateway / dashboard URL reverted to default Owner workspace-overrides.json Fix usually auto-restored to reset: rm overrides.json falls back to HERMES_API_URL Theme / prefs gone theme reset to default localStorage cleared Owner browser localStorage Fix reselect theme in Settings → Appearance key: claude-theme One session broken errors / stuck loading only that session Owner sessions.db (row) Fix delete session from sidebar context menu create new session LAST RESORT — Full reset (when nothing else works) 1. stop agent + UI • 2. backup ~/.hermes/ • 3. rm workspace-sessions.json workspace-overrides.json • 4. if DB corrupted: rename sessions.db + kanban.db • 5. restart agent → UI File ownership map — what each file owns ~/.hermes/sessions.db chat history, message threads ~/.hermes/response_store.db streaming response cache ~/.hermes/kanban.db tasks + boards (kanban plugin) ~/.hermes/workspace-sessions.json browser login tokens (safe to delete) ~/.hermes/workspace-overrides.json custom gateway / dashboard URL overrides ~/.hermes/config.yaml provider config, model.default ~/.hermes/.env API keys (plain text) browser localStorage claude-theme, UI preferences ~/.hermes/kanban.db.bak.* timestamped DB backups (auto-created) What survives a crash UI server crash: all data safe (agent still running) Agent crash: chat history in sessions.db, recoverable Browser tab crash: zero data loss (nothing stored there) Machine reboot: all ~/.hermes/ files survive localStorage cleared: theme + prefs lost (non-critical) Always backup ~/.hermes/ before a full reset cp -r ~/.hermes/ ~/.hermes-backup-$(date +%Y%m%d) Legend Symptom File owner Fix Last resort / data risk

File ownership at a glance

  • • Chat history → sessions.db
  • • Browser login sessions → workspace-sessions.json
  • • Gateway/dashboard URL overrides → workspace-overrides.json
  • • Theme + UI prefs → browser localStorage (claude-theme key)

Safe files to delete

  • • workspace-sessions.json — forces re-login, no chat data lost
  • • workspace-overrides.json — resets to HERMES_API_URL default
  • • Browser localStorage — resets theme and UI prefs only
  • • All recreated automatically on next startup

Risky files (backup first)

  • • sessions.db — deleting loses all chat history
  • • kanban.db — deleting loses all tasks and boards
  • • config.yaml — deleting requires provider reconfiguration
  • • .env — deleting requires re-entering all API keys

Hermes Switch UI • crash recovery flow • symptom → file owner → fix → full reset as last resort