feat: add Hermes gateway controls

.env.example

@@ -28,6 +28,9 @@ HOST=0.0.0.0
 # Uncomment the following line if you have a custom claude cli path other than the default "claude"
 # CLAUDE_CLI_PATH=claude
 
+# Uncomment the following line if you want a custom Hermes ACP launcher
+# HERMES_CLI_PATH=hermes acp
+
 # =============================================================================
 # DATABASE CONFIGURATION
 # =============================================================================
@@ -42,4 +45,3 @@ HOST=0.0.0.0
 VITE_CONTEXT_WINDOW=160000
 CONTEXT_WINDOW=160000
 
-

docs/hermes-gateway.md

@@ -0,0 +1,45 @@
+# Hermes Gateway Controls
+
+CloudCLI can manage the Hermes Gateway process from **Settings -> Agents -> Hermes -> Gateway**.
+
+The gateway is optional. Normal CloudCLI chat and automation should continue to use `POST /api/agent` with `provider: "hermes"`. The gateway is for long-running Hermes integrations such as Telegram, Discord, WhatsApp, and other messaging surfaces configured by Hermes.
+
+## What The Gateway Tab Does
+
+- Shows whether Hermes is installed and whether the gateway is running.
+- Starts Hermes with `hermes gateway run` in the current CloudCLI server environment.
+- Stops or restarts a gateway process started by CloudCLI.
+- Opens `hermes gateway setup` in the terminal for platform configuration.
+- Shows detected Hermes profiles for visibility.
+- Shows recent logs from the gateway process managed by CloudCLI.
+
+## What It Does Not Do
+
+- It does not expose the Hermes HTTP gateway as a raw public API.
+- It does not add a new authentication model.
+- It does not replace the CloudCLI Agent API.
+- It does not create Docker containers or require Docker.
+
+## API Boundaries
+
+CloudCLI has two separate surfaces:
+
+- **CloudCLI Agent API**: `POST /api/agent`
+  Use this for programmatic CloudCLI tasks, including Hermes tasks. It supports `projectPath`, `githubUrl`, sessions, branches, and other CloudCLI workflow options.
+
+- **Hermes Gateway controls**: `/api/providers/hermes/gateway/*`
+  These are browser-authenticated UI control endpoints used by the settings page.
+
+The gateway controls intentionally stay inside the authenticated provider API. They are not a customer-facing replacement for `POST /api/agent`.
+
+## Hosted Environments
+
+In hosted or containerized environments, CloudCLI runs the gateway in foreground mode because system service managers such as systemd or launchd may not be available. This matches Hermes' recommended foreground mode for containers and similar runtimes.
+
+If Docker is not available, the Gateway tab still works for the local Hermes process. Docker is only relevant for advanced deployments where a user chooses to run Hermes separately.
+
+## References
+
+- [Hermes Agent releases](https://github.com/NousResearch/hermes-agent/releases) for current gateway and messaging platform capabilities.
+- [Hermes hooks documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks) for non-interactive gateway runs and hook approval behavior.
+- [Hermes environment variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) for Docker-image-specific gateway supervision details.

public/api-docs.html

@@ -524,7 +524,7 @@
                                         <td><code>provider</code></td>
                                         <td>string</td>
                                         <td><span class="badge badge-optional">Optional</span></td>
-                                        <td><code>claude</code>, <code>cursor</code>, or <code>codex</code> (default: <code>claude</code>)</td>
+                                        <td><code>claude</code>, <code>cursor</code>, <code>codex</code>, <code>gemini</code>, <code>opencode</code>, or <code>hermes</code> (default: <code>claude</code>)</td>
                                     </tr>
                                     <tr>
                                         <td><code>stream</code></td>
@@ -834,6 +834,7 @@ data: {"type":"done"}</code></pre>
             { id: 'gemini',   name: 'Google' },
             { id: 'cursor',   name: 'Cursor' },
             { id: 'opencode', name: 'OpenCode' },
+            { id: 'hermes',   name: 'Nous Research' },
         ];
 
         async function populateModels() {

server/claude-sdk.js

@@ -29,9 +29,14 @@ import {
 import { sessionsService } from './modules/providers/services/sessions.service.js';
 import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
 import { createCompleteMessage, createNormalizedMessage } from './shared/utils.js';
+import {
+  getPendingApprovalsForSession,
+  registerApproval,
+  resolveToolApproval,
+  unregisterApproval,
+} from './shared/tool-approval-registry.js';
 
 const activeSessions = new Map();
-const pendingToolApprovals = new Map();
 // Sessions cancelled via abort-session. The abort handler already sent the
 // terminal `complete` (aborted: true) to the client, so the run loop must not
 // emit a second one when its generator winds down.
@@ -64,7 +69,7 @@ function waitForToolApproval(requestId, options = {}) {
     let timeout;
 
     const cleanup = () => {
-      pendingToolApprovals.delete(requestId);
+      unregisterApproval(requestId);
       if (timeout) clearTimeout(timeout);
       if (signal && abortHandler) {
         signal.removeEventListener('abort', abortHandler);
@@ -96,21 +101,15 @@ function waitForToolApproval(requestId, options = {}) {
     const resolver = (decision) => {
       finalize(decision);
     };
-    // Attach metadata for getPendingApprovalsForSession lookup
-    if (metadata) {
-      Object.assign(resolver, metadata);
-    }
-    pendingToolApprovals.set(requestId, resolver);
+    registerApproval(requestId, {
+      resolver,
+      sessionId: metadata?._sessionId ?? null,
+      provider: 'claude',
+      meta: metadata ?? {},
+    });
   });
 }
 
-function resolveToolApproval(requestId, decision) {
-  const resolver = pendingToolApprovals.get(requestId);
-  if (resolver) {
-    resolver(decision);
-  }
-}
-
 // Match stored permission entries against a tool + input combo.
 // This only supports exact tool names and the Bash(command:*) shorthand
 // used by the UI; it intentionally does not implement full glob semantics,
@@ -846,28 +845,6 @@ function getActiveClaudeSDKSessions() {
   return getAllSessions();
 }
 
-/**
- * Get pending tool approvals for a specific session.
- * @param {string} sessionId - The session ID
- * @returns {Array} Array of pending permission request objects
- */
-function getPendingApprovalsForSession(sessionId) {
-  const pending = [];
-  for (const [requestId, resolver] of pendingToolApprovals.entries()) {
-    if (resolver._sessionId === sessionId) {
-      pending.push({
-        requestId,
-        toolName: resolver._toolName || 'UnknownTool',
-        input: resolver._input,
-        context: resolver._context,
-        sessionId,
-        receivedAt: resolver._receivedAt || new Date(),
-      });
-    }
-  }
-  return pending;
-}
-
 /**
  * Reconnect a session's WebSocketWriter to a new raw WebSocket.
  * Called when client reconnects (e.g. page refresh) while SDK is still running.

server/hermes-cli.js

@@ -0,0 +1,407 @@
+import crypto from 'node:crypto';
+
+import { sessionsService } from './modules/providers/services/sessions.service.js';
+import { providerAuthService } from './modules/providers/services/provider-auth.service.js';
+import { providerModelsService } from './modules/providers/services/provider-models.service.js';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';
+import { createCompleteMessage, createNormalizedMessage } from './shared/utils.js';
+import {
+  clearApprovalsForSession,
+  getPendingApprovalsForSession,
+  registerApproval,
+  resolveToolApproval,
+  unregisterApproval,
+} from './shared/tool-approval-registry.js';
+import { hermesConnectionManager } from './hermes/acp-client.js';
+
+const PROVIDER = 'hermes';
+const HERMES_CONFIGURED_MODEL = '__hermes_configured_model__';
+const activeHermesSessions = new Map();
+// Session ids whose run was aborted; the terminal `complete` is emitted by
+// handleChatAbort, so the runtime must not also emit a "completed" one.
+const abortedSessionIds = new Set();
+
+function createRequestId() {
+  if (typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return crypto.randomBytes(16).toString('hex');
+}
+
+function readSessionId(result) {
+  if (!result || typeof result !== 'object') {
+    return null;
+  }
+  return result.sessionId
+    || result.session_id
+    || result.id
+    || result.session?.id
+    || result.session?.sessionId
+    || result.session?.session_id
+    || null;
+}
+
+function readStopReason(result) {
+  if (!result || typeof result !== 'object') {
+    return null;
+  }
+  return result.stopReason || result.stop_reason || result.reason || null;
+}
+
+function buildPromptParams(sessionId, command) {
+  return {
+    sessionId,
+    prompt: [{ type: 'text', text: command }],
+  };
+}
+
+function buildSessionSetupParams(sessionId, workingDir) {
+  return {
+    ...(sessionId ? { sessionId } : {}),
+    cwd: workingDir,
+    mcpServers: [],
+  };
+}
+
+function canLoadSession(connection) {
+  return connection?.initializeResult?.agentCapabilities?.loadSession === true;
+}
+
+function findPermissionOption(options, kinds, fallbackOptionIds = []) {
+  if (!Array.isArray(options)) {
+    return null;
+  }
+
+  for (const kind of kinds) {
+    const match = options.find((option) => option?.kind === kind);
+    if (match?.optionId) {
+      return match.optionId;
+    }
+  }
+
+  for (const optionId of fallbackOptionIds) {
+    const match = options.find((option) => option?.optionId === optionId);
+    if (match?.optionId) {
+      return match.optionId;
+    }
+  }
+
+  return null;
+}
+
+function createPermissionDecision(decision, options = []) {
+  if (!decision) {
+    return { outcome: { outcome: 'cancelled' } };
+  }
+
+  if (decision.cancelled) {
+    return { outcome: { outcome: 'cancelled' } };
+  }
+
+  if (decision.allow) {
+    const optionId = decision.rememberEntry
+      ? findPermissionOption(options, ['allow_always', 'allow_session'], ['allow_always', 'allow_session'])
+      : findPermissionOption(options, ['allow_once'], ['allow_once']);
+
+    if (!optionId) {
+      return { outcome: { outcome: 'cancelled' } };
+    }
+
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId,
+      },
+    };
+  }
+
+  const denyOptionId = findPermissionOption(options, ['reject_once', 'deny', 'reject_always'], ['deny', 'reject_once', 'reject_always']);
+  if (denyOptionId) {
+    return {
+      outcome: {
+        outcome: 'selected',
+        optionId: denyOptionId,
+      },
+    };
+  }
+
+  return {
+    outcome: { outcome: 'cancelled' },
+  };
+}
+
+async function waitForPermission(ws, params, capturedSessionId, sessionSummary) {
+  const requestId = createRequestId();
+  const toolCall = params?.toolCall || params?.tool_call || {};
+  const toolName = params?.toolName
+    || params?.tool_name
+    || params?.name
+    || params?.tool?.name
+    || toolCall.title
+    || 'HermesTool';
+  const input = params?.input
+    ?? params?.arguments
+    ?? params?.toolInput
+    ?? params?.tool_input
+    ?? toolCall.rawInput
+    ?? toolCall.raw_input
+    ?? toolCall;
+
+  ws.send(createNormalizedMessage({
+    kind: 'permission_request',
+    requestId,
+    toolName,
+    input,
+    sessionId: capturedSessionId,
+    provider: PROVIDER,
+  }));
+
+  return new Promise((resolve) => {
+    registerApproval(requestId, {
+      sessionId: capturedSessionId,
+      provider: PROVIDER,
+      meta: {
+        toolName,
+        input,
+        context: params,
+        sessionName: sessionSummary,
+        receivedAt: new Date(),
+      },
+      resolver: (decision) => {
+        unregisterApproval(requestId);
+        resolve(createPermissionDecision(decision, params?.options));
+      },
+    });
+  });
+}
+
+async function spawnHermes(command, options = {}, ws) {
+  const { sessionId, projectPath, cwd, model, sessionSummary } = options;
+  const workingDir = cwd || projectPath || process.cwd();
+  const requestedModel = model === HERMES_CONFIGURED_MODEL ? undefined : model;
+  let capturedSessionId = sessionId || null;
+  let sessionCreatedSent = false;
+  let completeSent = false;
+  let activeKey = capturedSessionId || `pending-${createRequestId()}`;
+
+  const notifyTerminalState = ({ error = null, stopReason = 'completed' } = {}) => {
+    const finalSessionId = capturedSessionId || sessionId || activeKey;
+    if (!error) {
+      notifyRunStopped({
+        userId: ws?.userId || null,
+        provider: PROVIDER,
+        sessionId: finalSessionId,
+        sessionName: sessionSummary,
+        stopReason,
+      });
+      return;
+    }
+
+    notifyRunFailed({
+      userId: ws?.userId || null,
+      provider: PROVIDER,
+      sessionId: finalSessionId,
+      sessionName: sessionSummary,
+      error,
+    });
+  };
+
+  const registerSession = (nextSessionId, connection) => {
+    if (!nextSessionId || capturedSessionId === nextSessionId) {
+      return;
+    }
+
+    if (activeHermesSessions.has(activeKey)) {
+      activeHermesSessions.delete(activeKey);
+    }
+    activeKey = nextSessionId;
+    capturedSessionId = nextSessionId;
+    activeHermesSessions.set(activeKey, {
+      connection,
+      sessionId: capturedSessionId,
+      status: 'active',
+      aborted: false,
+      ws,
+      sessionSummary,
+    });
+
+    if (ws.setSessionId && typeof ws.setSessionId === 'function') {
+      ws.setSessionId(capturedSessionId);
+    }
+
+    if (!sessionId && !sessionCreatedSent) {
+      sessionCreatedSent = true;
+      ws.send(createNormalizedMessage({
+        kind: 'session_created',
+        newSessionId: capturedSessionId,
+        sessionId: capturedSessionId,
+        provider: PROVIDER,
+      }));
+    }
+  };
+
+  try {
+    await providerModelsService.resolveResumeModel(PROVIDER, sessionId, requestedModel);
+    const connection = await hermesConnectionManager.getConnection(workingDir);
+    activeHermesSessions.set(activeKey, {
+      connection,
+      sessionId: capturedSessionId,
+      status: 'active',
+      aborted: false,
+      ws,
+      sessionSummary,
+    });
+
+    const unregisterPermissionHandler = connection.registerRequestHandler('session/request_permission', (params) => {
+      const permissionSessionId = params?.sessionId || params?.session_id || null;
+      const active = permissionSessionId
+        ? activeHermesSessions.get(permissionSessionId)
+        : activeHermesSessions.get(activeKey);
+      if (!active) {
+        return { outcome: { outcome: 'cancelled' } };
+      }
+
+      return waitForPermission(
+        active.ws,
+        params,
+        active.sessionId || permissionSessionId || capturedSessionId,
+        active.sessionSummary || sessionSummary,
+      );
+    });
+
+    const updateHandler = (params) => {
+      const updateSessionId = params?.sessionId || params?.session_id || null;
+      if (capturedSessionId && updateSessionId && updateSessionId !== capturedSessionId) {
+        return;
+      }
+
+      registerSession(updateSessionId, connection);
+      const normalized = sessionsService.normalizeMessage(PROVIDER, params, capturedSessionId || updateSessionId || null);
+      for (const msg of normalized) {
+        ws.send(msg);
+      }
+    };
+
+    connection.on('session/update', updateHandler);
+
+    try {
+      let sessionResult;
+      if (sessionId && canLoadSession(connection)) {
+        try {
+          sessionResult = await connection.request('session/load', buildSessionSetupParams(sessionId, workingDir));
+        } catch {
+          sessionResult = { sessionId };
+        }
+      } else {
+        sessionResult = await connection.request('session/new', buildSessionSetupParams(null, workingDir));
+      }
+
+      registerSession(readSessionId(sessionResult) || sessionId, connection);
+      if (!capturedSessionId) {
+        throw new Error('Hermes ACP did not return a session id.');
+      }
+      const promptResult = await connection.request('session/prompt', buildPromptParams(capturedSessionId, command));
+      const finalSessionId = capturedSessionId || readSessionId(promptResult) || sessionId || activeKey;
+      const stopReason = readStopReason(promptResult) || 'completed';
+      const active = activeHermesSessions.get(finalSessionId) || activeHermesSessions.get(activeKey);
+
+      if (promptResult?.usage || promptResult?.tokenUsage || promptResult?.token_usage) {
+        ws.send(createNormalizedMessage({
+          kind: 'status',
+          text: 'token_budget',
+          tokenBudget: promptResult.usage || promptResult.tokenUsage || promptResult.token_usage,
+          sessionId: finalSessionId,
+          provider: PROVIDER,
+        }));
+      }
+
+      const abortedById = abortedSessionIds.delete(finalSessionId);
+      const abortedByKey = abortedSessionIds.delete(activeKey);
+      const wasAborted = Boolean(active?.aborted || abortedById || abortedByKey);
+
+      if (!completeSent && !wasAborted) {
+        completeSent = true;
+        ws.send(createCompleteMessage({ provider: PROVIDER, sessionId: finalSessionId, exitCode: 0 }));
+      }
+      activeHermesSessions.delete(finalSessionId);
+      activeHermesSessions.delete(activeKey);
+      clearApprovalsForSession(finalSessionId);
+      notifyTerminalState({ stopReason: wasAborted ? 'aborted' : stopReason });
+    } finally {
+      connection.off('session/update', updateHandler);
+      unregisterPermissionHandler();
+    }
+  } catch (error) {
+    const finalSessionId = capturedSessionId || sessionId || activeKey;
+    const abortedById = abortedSessionIds.delete(finalSessionId);
+    const abortedByKey = abortedSessionIds.delete(activeKey);
+    activeHermesSessions.delete(finalSessionId);
+    activeHermesSessions.delete(activeKey);
+    clearApprovalsForSession(finalSessionId);
+
+    // A cancelled session/prompt rejects here; its aborted terminal `complete`
+    // is sent by handleChatAbort, so don't surface the cancellation as an error.
+    if (abortedById || abortedByKey) {
+      return;
+    }
+
+    const installed = await providerAuthService.isProviderInstalled(PROVIDER);
+    const errorContent = !installed
+      ? 'Hermes ACP is not installed. Install Hermes and ensure hermes-acp is on PATH.'
+      : error instanceof Error ? error.message : String(error);
+
+    ws.send(createNormalizedMessage({
+      kind: 'error',
+      content: errorContent,
+      sessionId: finalSessionId,
+      provider: PROVIDER,
+    }));
+    if (!completeSent) {
+      completeSent = true;
+      ws.send(createCompleteMessage({ provider: PROVIDER, sessionId: finalSessionId, exitCode: 1 }));
+    }
+    notifyTerminalState({ error });
+    throw error;
+  }
+}
+
+async function abortHermesSession(providerSessionId) {
+  const active = activeHermesSessions.get(providerSessionId);
+  if (!active) {
+    return false;
+  }
+
+  active.aborted = true;
+  active.status = 'aborted';
+  abortedSessionIds.add(providerSessionId);
+  if (active.sessionId) {
+    abortedSessionIds.add(active.sessionId);
+  }
+  for (const approval of getPendingApprovalsForSession(active.sessionId || providerSessionId)) {
+    resolveToolApproval(approval.requestId, { cancelled: true });
+  }
+
+  try {
+    active.connection.notify('session/cancel', { sessionId: active.sessionId || providerSessionId });
+  } catch {
+    // If Hermes already finished, the caller still sees the run as aborted.
+  }
+  activeHermesSessions.delete(providerSessionId);
+  return true;
+}
+
+function isHermesSessionActive(sessionId) {
+  return activeHermesSessions.has(sessionId);
+}
+
+function getActiveHermesSessions() {
+  return Array.from(activeHermesSessions.keys());
+}
+
+export {
+  spawnHermes,
+  abortHermesSession,
+  isHermesSessionActive,
+  getActiveHermesSessions,
+  createPermissionDecision,
+};

server/hermes/acp-client.js

@@ -0,0 +1,287 @@
+import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
+
+import crossSpawn from 'cross-spawn';
+
+const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
+
+class AcpClient extends EventEmitter {
+  constructor({ command = process.env.HERMES_CLI_PATH || 'hermes acp', cwd = process.cwd(), env = process.env } = {}) {
+    super();
+    const commandParts = command.trim().split(/\s+/);
+    this.command = commandParts.shift() || 'hermes';
+    this.args = commandParts;
+    this.cwd = cwd;
+    this.env = env;
+    this.process = null;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.buffer = '';
+    this.requestHandlers = new Map();
+    this.initialized = false;
+    this.initializeResult = null;
+  }
+
+  start() {
+    if (this.process) {
+      return;
+    }
+
+    this.process = spawnFunction(this.command, this.args, {
+      cwd: this.cwd,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...this.env },
+    });
+
+    this.process.stdout.on('data', (chunk) => this.handleData(chunk));
+    this.process.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      if (text.trim()) {
+        this.emit('stderr', text);
+      }
+    });
+    this.process.on('error', (error) => this.rejectAll(error));
+    this.process.on('close', (code, signal) => {
+      this.rejectAll(new Error(`hermes-acp exited with code ${code ?? 'null'}${signal ? ` signal ${signal}` : ''}`));
+      this.emit('close', { code, signal });
+      this.process = null;
+      this.initialized = false;
+    });
+  }
+
+  async initialize() {
+    if (this.initialized) {
+      return;
+    }
+
+    this.start();
+    this.initializeResult = await this.request('initialize', {
+      protocolVersion: 1,
+      clientCapabilities: {
+        fs: {
+          readTextFile: false,
+          writeTextFile: false,
+        },
+        terminal: false,
+      },
+      clientInfo: {
+        name: 'CloudCLI',
+        title: 'CloudCLI',
+        version: '1.0.0',
+      },
+    });
+    this.initialized = true;
+    this.notify('initialized', {});
+  }
+
+  onRequest(method, handler) {
+    this.requestHandlers.set(method, handler);
+  }
+
+  registerRequestHandler(method, handler) {
+    const handlers = this.requestHandlers.get(method) || new Set();
+    handlers.add(handler);
+    this.requestHandlers.set(method, handlers);
+    return () => {
+      handlers.delete(handler);
+      if (handlers.size === 0) {
+        this.requestHandlers.delete(method);
+      }
+    };
+  }
+
+  request(method, params) {
+    this.start();
+    const id = this.nextId;
+    this.nextId += 1;
+
+    const payload = { jsonrpc: '2.0', id, method, params };
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject, method, params });
+      this.writeMessage(payload);
+    });
+  }
+
+  notify(method, params) {
+    this.start();
+    this.writeMessage({ jsonrpc: '2.0', method, params });
+  }
+
+  writeMessage(payload) {
+    if (!this.process || !this.process.stdin || this.process.stdin.destroyed) {
+      throw new Error('hermes-acp process is not running');
+    }
+    const line = `${JSON.stringify(payload)}\n`;
+    this.process.stdin.write(line);
+  }
+
+  handleData(chunk) {
+    this.buffer += chunk.toString();
+
+    while (this.buffer.length > 0) {
+      if (this.buffer.startsWith('Content-Length:')) {
+        const headerEnd = this.buffer.indexOf('\r\n\r\n');
+        if (headerEnd === -1) {
+          return;
+        }
+        const header = this.buffer.slice(0, headerEnd);
+        const match = header.match(/Content-Length:\s*(\d+)/i);
+        if (!match) {
+          this.buffer = this.buffer.slice(headerEnd + 4);
+          continue;
+        }
+        const length = Number(match[1]);
+        const messageStart = headerEnd + 4;
+        if (this.buffer.length < messageStart + length) {
+          return;
+        }
+        const raw = this.buffer.slice(messageStart, messageStart + length);
+        this.buffer = this.buffer.slice(messageStart + length);
+        this.dispatchRaw(raw);
+        continue;
+      }
+
+      const newlineIndex = this.buffer.indexOf('\n');
+      if (newlineIndex === -1) {
+        return;
+      }
+      const raw = this.buffer.slice(0, newlineIndex).trim();
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+      if (raw) {
+        this.dispatchRaw(raw);
+      }
+    }
+  }
+
+  dispatchRaw(raw) {
+    let message;
+    try {
+      message = JSON.parse(raw);
+    } catch (error) {
+      this.emit('error', error);
+      return;
+    }
+
+    void this.dispatchMessage(message);
+  }
+
+  async dispatchMessage(message) {
+    if (Object.prototype.hasOwnProperty.call(message, 'id') && (message.result !== undefined || message.error !== undefined)) {
+      const pending = this.pending.get(message.id);
+      if (!pending) {
+        return;
+      }
+      this.pending.delete(message.id);
+      if (message.error) {
+        const messageText = message.error.message || JSON.stringify(message.error);
+        const error = new Error(`ACP ${pending.method} failed: ${messageText}`);
+        error.code = message.error.code;
+        error.data = message.error.data;
+        error.method = pending.method;
+        error.params = pending.params;
+        pending.reject(error);
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(message, 'id') && message.method) {
+      const handler = this.requestHandlers.get(message.method);
+      if (!handler) {
+        this.writeMessage({
+          jsonrpc: '2.0',
+          id: message.id,
+          error: { code: -32601, message: `No handler for ${message.method}` },
+        });
+        return;
+      }
+
+      try {
+        const result = handler instanceof Set
+          ? await this.dispatchRequestHandlers(handler, message.params)
+          : await handler(message.params);
+        this.writeMessage({ jsonrpc: '2.0', id: message.id, result });
+      } catch (error) {
+        this.writeMessage({
+          jsonrpc: '2.0',
+          id: message.id,
+          error: { code: -32000, message: error instanceof Error ? error.message : String(error) },
+        });
+      }
+      return;
+    }
+
+    if (message.method) {
+      this.emit(message.method, message.params);
+      this.emit('notification', { method: message.method, params: message.params });
+    }
+  }
+
+  rejectAll(error) {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  async dispatchRequestHandlers(handlers, params) {
+    let fallbackResult = null;
+    let sawHandler = false;
+    for (const handler of Array.from(handlers).reverse()) {
+      sawHandler = true;
+      const result = await handler(params);
+      const outcome = result?.outcome?.outcome;
+      if (outcome !== 'cancelled') {
+        return result;
+      }
+      fallbackResult = result;
+    }
+    if (sawHandler && fallbackResult) {
+      return fallbackResult;
+    }
+    return { outcome: { outcome: 'cancelled' } };
+  }
+
+  close() {
+    if (!this.process) {
+      return;
+    }
+    this.process.kill('SIGTERM');
+  }
+}
+
+class HermesConnectionManager {
+  constructor() {
+    this.connections = new Map();
+  }
+
+  async getConnection(cwd) {
+    const key = cwd || process.cwd();
+    let connection = this.connections.get(key);
+    if (!connection) {
+      connection = new AcpClient({ cwd: key });
+      connection.on('close', () => {
+        this.connections.delete(key);
+      });
+      this.connections.set(key, connection);
+    }
+    await connection.initialize();
+    return connection;
+  }
+
+  closeAll() {
+    for (const connection of this.connections.values()) {
+      connection.close();
+    }
+    this.connections.clear();
+  }
+}
+
+const hermesConnectionManager = new HermesConnectionManager();
+
+export {
+  AcpClient,
+  HermesConnectionManager,
+  hermesConnectionManager,
+};

server/index.js

@@ -41,6 +41,10 @@ import {
     spawnOpenCode,
     abortOpenCodeSession,
 } from './opencode-cli.js';
+import {
+    spawnHermes,
+    abortHermesSession,
+} from './hermes-cli.js';
 import sessionManager from './sessionManager.js';
 import {
     stripAnsiSequences,
@@ -118,6 +122,7 @@ const wss = createWebSocketServer(server, {
             codex: queryCodex,
             gemini: spawnGemini,
             opencode: spawnOpenCode,
+            hermes: spawnHermes,
         },
         abortFns: {
             claude: abortClaudeSDKSession,
@@ -125,6 +130,7 @@ const wss = createWebSocketServer(server, {
             codex: abortCodexSession,
             gemini: abortGeminiSession,
             opencode: abortOpenCodeSession,
+            hermes: abortHermesSession,
         },
         resolveToolApproval,
         getPendingApprovalsForSession,

server/modules/providers/list/hermes/hermes-auth.provider.ts

@@ -0,0 +1,135 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import spawn from 'cross-spawn';
+
+import type { IProviderAuth } from '@/shared/interfaces.js';
+import type { ProviderAuthStatus } from '@/shared/types.js';
+import { readObjectRecord, readOptionalString } from '@/shared/utils.js';
+
+export class HermesProviderAuth implements IProviderAuth {
+  private checkInstalled(): boolean {
+    const cliPath = process.env.HERMES_CLI_PATH || 'hermes acp';
+    const [command, ...args] = cliPath.trim().split(/\s+/);
+    try {
+      const result = spawn.sync(command || 'hermes', [...args, '--version'], { stdio: 'ignore', timeout: 5000 });
+      return result.error ? false : result.status === 0 || result.status === null;
+    } catch {
+      return false;
+    }
+  }
+
+  async getStatus(): Promise<ProviderAuthStatus> {
+    const installed = this.checkInstalled();
+    if (!installed) {
+      return {
+        provider: 'hermes',
+        installed: false,
+        authenticated: false,
+        email: null,
+        method: null,
+        error: 'Hermes is not installed',
+      };
+    }
+
+    const credentials = await this.checkCredentials();
+    return {
+      provider: 'hermes',
+      installed,
+      authenticated: credentials.authenticated,
+      email: credentials.email,
+      method: credentials.method ?? 'managed_by_hermes',
+      error: undefined,
+    };
+  }
+
+  private async checkCredentials(): Promise<{ authenticated: boolean; email: string | null; method: string | null }> {
+    if (this.hasKnownProviderEnv(process.env)) {
+      return { authenticated: true, email: 'API Key Auth', method: 'env' };
+    }
+
+    const hermesHome = path.join(os.homedir(), '.hermes');
+    try {
+      const authJson = readObjectRecord(JSON.parse(await readFile(path.join(hermesHome, 'auth.json'), 'utf8')));
+      if (
+        readOptionalString(authJson?.apiKey)
+        || readOptionalString(authJson?.api_key)
+        || readOptionalString(authJson?.token)
+        || readOptionalString(authJson?.access_token)
+        || readOptionalString(authJson?.refresh_token)
+      ) {
+        return {
+          authenticated: true,
+          email: readOptionalString(authJson?.email) ?? 'Hermes Auth',
+          method: 'credentials_file',
+        };
+      }
+    } catch {
+      // Fall through to dotenv check.
+    }
+
+    try {
+      const envContent = await readFile(path.join(hermesHome, '.env'), 'utf8');
+      if (this.hasKnownProviderEnv(this.parseEnvFile(envContent))) {
+        return { authenticated: true, email: 'API Key Auth', method: 'env_file' };
+      }
+    } catch {
+      // Fall through.
+    }
+
+    try {
+      const configContent = await readFile(path.join(hermesHome, 'config.yaml'), 'utf8');
+      if (/^\s*api_key\s*:\s*["']?[^"'#\s]+/m.test(configContent)) {
+        return { authenticated: true, email: 'Hermes Config', method: 'config_file' };
+      }
+    } catch {
+      // Fall through.
+    }
+
+    return { authenticated: false, email: null, method: null };
+  }
+
+  private parseEnvFile(content: string): Record<string, string> {
+    const parsed: Record<string, string> = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) {
+        continue;
+      }
+      const separatorIndex = line.indexOf('=');
+      if (separatorIndex <= 0) {
+        continue;
+      }
+      const key = line.slice(0, separatorIndex).trim();
+      const value = line.slice(separatorIndex + 1).trim().replace(/^['"]|['"]$/g, '');
+      if (key && value) {
+        parsed[key] = value;
+      }
+    }
+    return parsed;
+  }
+
+  private hasKnownProviderEnv(env: Record<string, string | undefined>): boolean {
+    const keys = [
+      'HERMES_API_KEY',
+      'NOUS_API_KEY',
+      'OPENROUTER_API_KEY',
+      'OPENAI_API_KEY',
+      'ANTHROPIC_API_KEY',
+      'GOOGLE_API_KEY',
+      'GEMINI_API_KEY',
+      'GLM_API_KEY',
+      'KIMI_API_KEY',
+      'MINIMAX_API_KEY',
+      'MINIMAX_CN_API_KEY',
+      'HF_TOKEN',
+      'NVIDIA_API_KEY',
+      'ARCEEAI_API_KEY',
+      'OLLAMA_API_KEY',
+      'KILOCODE_API_KEY',
+      'GITHUB_TOKEN',
+    ];
+    return keys.some((key) => Boolean(env[key]?.trim()));
+  }
+}

server/modules/providers/list/hermes/hermes-mcp.provider.ts

@@ -0,0 +1,296 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { McpProvider } from '@/modules/providers/shared/mcp/mcp.provider.js';
+import type { McpScope, ProviderMcpServer, UpsertProviderMcpServerInput } from '@/shared/types.js';
+import {
+  AppError,
+  readObjectRecord,
+  readOptionalString,
+  readStringArray,
+  readStringRecord,
+} from '@/shared/utils.js';
+
+const yamlScalar = (value: unknown): string => {
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (value === null) {
+    return 'null';
+  }
+  return JSON.stringify(String(value));
+};
+
+const parseYamlScalar = (value: string): unknown => {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return '';
+  }
+  if (trimmed === 'null') {
+    return null;
+  }
+  if (trimmed === 'true') {
+    return true;
+  }
+  if (trimmed === 'false') {
+    return false;
+  }
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith('\'') && trimmed.endsWith('\''))) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed.slice(1, -1);
+    }
+  }
+  if (
+    (trimmed.startsWith('[') && trimmed.endsWith(']'))
+    || (trimmed.startsWith('{') && trimmed.endsWith('}'))
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      return trimmed;
+    }
+  }
+  return trimmed.replace(/\s+#.*$/, '').trim();
+};
+
+const getIndent = (line: string): number => line.match(/^\s*/)?.[0].length ?? 0;
+
+const parseYamlArray = (
+  lines: string[],
+  startIndex: number,
+  indent: number,
+): { value: unknown[]; nextIndex: number } => {
+  const value: unknown[] = [];
+  let index = startIndex;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (!line.trim()) {
+      index += 1;
+      continue;
+    }
+    if (getIndent(line) !== indent || !line.trimStart().startsWith('- ')) {
+      break;
+    }
+    value.push(parseYamlScalar(line.trimStart().slice(2)));
+    index += 1;
+  }
+  return { value, nextIndex: index };
+};
+
+const parseYamlMap = (
+  lines: string[],
+  startIndex: number,
+  indent: number,
+): { value: Record<string, unknown>; nextIndex: number } => {
+  const value: Record<string, unknown> = {};
+  let index = startIndex;
+  while (index < lines.length) {
+    const line = lines[index];
+    if (!line.trim()) {
+      index += 1;
+      continue;
+    }
+    const currentIndent = getIndent(line);
+    if (currentIndent < indent) {
+      break;
+    }
+    if (currentIndent > indent) {
+      index += 1;
+      continue;
+    }
+    const match = line.slice(indent).match(/^([^:#]+):(?:\s*(.*))?$/);
+    if (!match) {
+      index += 1;
+      continue;
+    }
+
+    const key = match[1].trim();
+    const raw = match[2]?.trim() ?? '';
+    if (raw) {
+      value[key] = parseYamlScalar(raw);
+      index += 1;
+      continue;
+    }
+
+    const nextLine = lines[index + 1];
+    if (nextLine && getIndent(nextLine) > indent && nextLine.trimStart().startsWith('- ')) {
+      const parsed = parseYamlArray(lines, index + 1, getIndent(nextLine));
+      value[key] = parsed.value;
+      index = parsed.nextIndex;
+      continue;
+    }
+
+    const parsed = parseYamlMap(lines, index + 1, indent + 2);
+    value[key] = parsed.value;
+    index = parsed.nextIndex;
+  }
+  return { value, nextIndex: index };
+};
+
+const readYamlConfig = async (filePath: string): Promise<string> => {
+  try {
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return '';
+    }
+    throw error;
+  }
+};
+
+const readMcpServers = async (filePath: string): Promise<Record<string, unknown>> => {
+  const content = await readYamlConfig(filePath);
+  const lines = content.split(/\r?\n/);
+  const sectionIndex = lines.findIndex((line) => /^mcp_servers\s*:\s*$/.test(line));
+  if (sectionIndex === -1) {
+    return {};
+  }
+  const parsed = parseYamlMap(lines, sectionIndex + 1, 2);
+  return readObjectRecord(parsed.value) ?? {};
+};
+
+const serializeYamlMap = (value: Record<string, unknown>, indent = 0): string[] => {
+  const lines: string[] = [];
+  for (const [key, rawValue] of Object.entries(value)) {
+    if (rawValue === undefined) {
+      continue;
+    }
+    const prefix = `${' '.repeat(indent)}${key}:`;
+    if (Array.isArray(rawValue)) {
+      lines.push(prefix);
+      for (const item of rawValue) {
+        lines.push(`${' '.repeat(indent + 2)}- ${yamlScalar(item)}`);
+      }
+      continue;
+    }
+    const nested = readObjectRecord(rawValue);
+    if (nested) {
+      lines.push(prefix);
+      lines.push(...serializeYamlMap(nested, indent + 2));
+      continue;
+    }
+    lines.push(`${prefix} ${yamlScalar(rawValue)}`);
+  }
+  return lines;
+};
+
+const replaceMcpServersSection = (content: string, servers: Record<string, unknown>): string => {
+  const lines = content.split(/\r?\n/);
+  const sectionIndex = lines.findIndex((line) => /^mcp_servers\s*:\s*$/.test(line));
+  const serialized = ['mcp_servers:', ...serializeYamlMap(servers, 2)];
+
+  if (sectionIndex === -1) {
+    const prefix = content.trimEnd();
+    return `${prefix ? `${prefix}\n\n` : ''}${serialized.join('\n')}\n`;
+  }
+
+  let endIndex = sectionIndex + 1;
+  while (endIndex < lines.length) {
+    const line = lines[endIndex];
+    if (line.trim() && getIndent(line) === 0) {
+      break;
+    }
+    endIndex += 1;
+  }
+
+  lines.splice(sectionIndex, endIndex - sectionIndex, ...serialized);
+  return `${lines.join('\n').trimEnd()}\n`;
+};
+
+const writeMcpServers = async (filePath: string, servers: Record<string, unknown>): Promise<void> => {
+  const content = await readYamlConfig(filePath);
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, replaceMcpServersSection(content, servers), 'utf8');
+};
+
+export class HermesMcpProvider extends McpProvider {
+  constructor() {
+    super('hermes', ['user', 'project'], ['stdio', 'http']);
+  }
+
+  protected async readScopedServers(scope: McpScope, workspacePath: string): Promise<Record<string, unknown>> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.hermes', 'config.yaml')
+      : path.join(workspacePath, '.hermes', 'config.yaml');
+    return readMcpServers(filePath);
+  }
+
+  protected async writeScopedServers(
+    scope: McpScope,
+    workspacePath: string,
+    servers: Record<string, unknown>,
+  ): Promise<void> {
+    const filePath = scope === 'user'
+      ? path.join(os.homedir(), '.hermes', 'config.yaml')
+      : path.join(workspacePath, '.hermes', 'config.yaml');
+    await writeMcpServers(filePath, servers);
+  }
+
+  protected buildServerConfig(input: UpsertProviderMcpServerInput): Record<string, unknown> {
+    if (input.transport === 'stdio') {
+      if (!input.command?.trim()) {
+        throw new AppError('command is required for stdio MCP servers.', {
+          code: 'MCP_COMMAND_REQUIRED',
+          statusCode: 400,
+        });
+      }
+
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        env: input.env ?? {},
+        cwd: input.cwd,
+      };
+    }
+
+    if (!input.url?.trim()) {
+      throw new AppError('url is required for http/sse MCP servers.', {
+        code: 'MCP_URL_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    return {
+      type: input.transport,
+      url: input.url,
+      headers: input.headers ?? {},
+    };
+  }
+
+  protected normalizeServerConfig(scope: McpScope, name: string, rawConfig: unknown): ProviderMcpServer | null {
+    const config = readObjectRecord(rawConfig);
+    if (!config) {
+      return null;
+    }
+
+    if (typeof config.command === 'string') {
+      return {
+        provider: 'hermes',
+        name,
+        scope,
+        transport: 'stdio',
+        command: config.command,
+        args: readStringArray(config.args),
+        env: readStringRecord(config.env),
+        cwd: readOptionalString(config.cwd),
+      };
+    }
+
+    if (typeof config.url === 'string') {
+      return {
+        provider: 'hermes',
+        name,
+        scope,
+        transport: 'http',
+        url: config.url,
+        headers: readStringRecord(config.headers),
+      };
+    }
+
+    return null;
+  }
+}

server/modules/providers/list/hermes/hermes-models.provider.ts

@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { IProviderModels } from '@/shared/interfaces.js';
+import type {
+  ProviderChangeActiveModelInput,
+  ProviderCurrentActiveModel,
+  ProviderModelsDefinition,
+  ProviderSessionActiveModelChange,
+} from '@/shared/types.js';
+import { readOptionalString } from '@/shared/utils.js';
+
+export const HERMES_CONFIGURED_MODEL = '__hermes_configured_model__';
+
+export const HERMES_FALLBACK_MODELS: ProviderModelsDefinition = {
+  OPTIONS: [
+    {
+      value: HERMES_CONFIGURED_MODEL,
+      label: 'Use Hermes default',
+      description: 'Uses the provider and model selected in Hermes.',
+    },
+  ],
+  DEFAULT: HERMES_CONFIGURED_MODEL,
+};
+
+const HERMES_CONFIG_PATH = path.join(os.homedir(), '.hermes', 'config.yaml');
+
+function escapeRegex(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function stripScalar(raw: string): string | null {
+  let value = raw.trim();
+  // Drop an unquoted trailing comment.
+  if (!value.startsWith('"') && !value.startsWith("'")) {
+    const comment = value.search(/\s#/);
+    if (comment >= 0) {
+      value = value.slice(0, comment).trim();
+    }
+  }
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    value = value.slice(1, -1);
+  }
+  return value.trim() || null;
+}
+
+const indentOf = (line: string): number => line.length - line.replace(/^\s+/, '').length;
+
+// Minimal, indentation-aware reader for the flat `key: value` and one-level
+// nested (`section:`\n`  key: value`) shapes used by ~/.hermes/config.yaml.
+// Avoids the fragile single-regex lookahead that could terminate a section
+// early and silently miss the configured model.
+export function readYamlPath(content: string, pathParts: string[]): string | null {
+  const lines = content.split(/\r?\n/);
+
+  if (pathParts.length === 1) {
+    const re = new RegExp(`^\\s*${escapeRegex(pathParts[0])}\\s*:\\s*(.*)$`);
+    for (const line of lines) {
+      if (!line.trim() || line.trim().startsWith('#')) continue;
+      const match = line.match(re);
+      if (match) return stripScalar(match[1]);
+    }
+    return null;
+  }
+
+  const [section, key] = pathParts;
+  const sectionRe = new RegExp(`^(\\s*)${escapeRegex(section)}\\s*:\\s*$`);
+  const keyRe = new RegExp(`^\\s*${escapeRegex(key)}\\s*:\\s*(.*)$`);
+  let sectionIndent: number | null = null;
+
+  for (const line of lines) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    if (sectionIndent === null) {
+      const match = line.match(sectionRe);
+      if (match) sectionIndent = match[1].length;
+      continue;
+    }
+
+    // Left the nested block once indentation returns to the section level or less.
+    if (indentOf(line) <= sectionIndent) {
+      sectionIndent = line.match(sectionRe)?.[1].length ?? null;
+      continue;
+    }
+
+    const match = line.match(keyRe);
+    if (match) return stripScalar(match[1]);
+  }
+
+  return null;
+}
+
+export class HermesProviderModels implements IProviderModels {
+  async getSupportedModels(): Promise<ProviderModelsDefinition> {
+    const activeModel = await this.readConfiguredModel();
+    if (!activeModel) {
+      return HERMES_FALLBACK_MODELS;
+    }
+
+    return {
+      OPTIONS: [
+        {
+          value: HERMES_CONFIGURED_MODEL,
+          label: 'Use Hermes default',
+          description: `Uses the provider and model selected in Hermes. Current config: ${activeModel}`,
+        },
+      ],
+      DEFAULT: HERMES_CONFIGURED_MODEL,
+    };
+  }
+
+  async getCurrentActiveModel(): Promise<ProviderCurrentActiveModel> {
+    const configured = await this.readConfiguredModel();
+    return { model: configured ?? HERMES_CONFIGURED_MODEL };
+  }
+
+  async changeActiveModel(input: ProviderChangeActiveModelInput): Promise<ProviderSessionActiveModelChange> {
+    if (input.model === HERMES_CONFIGURED_MODEL) {
+      return {
+        provider: 'hermes',
+        sessionId: input.sessionId,
+        supported: true,
+        changed: false,
+        model: null,
+      };
+    }
+
+    return {
+      provider: 'hermes',
+      sessionId: input.sessionId,
+      supported: false,
+      changed: false,
+      model: null,
+    };
+  }
+
+  private async readConfiguredModel(): Promise<string | null> {
+    try {
+      const content = await readFile(HERMES_CONFIG_PATH, 'utf8');
+      return readOptionalString(readYamlPath(content, ['model', 'default']))
+        ?? readOptionalString(readYamlPath(content, ['model']))
+        ?? null;
+    } catch {
+      return null;
+    }
+  }
+}

server/modules/providers/list/hermes/hermes-session-synchronizer.provider.ts

@@ -0,0 +1,110 @@
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import Database from 'better-sqlite3';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import type { IProviderSessionSynchronizer } from '@/shared/interfaces.js';
+import { normalizeSessionName } from '@/shared/utils.js';
+
+type HermesSessionRow = {
+  id: string;
+  cwd: string | null;
+  title: string | null;
+  started_at: number | null;
+  ended_at: number | null;
+  message_count: number | null;
+};
+
+const HERMES_DB_PATH = path.join(os.homedir(), '.hermes', 'state.db');
+
+function unixSecondsToIso(value: number | null | undefined): string {
+  if (!value || !Number.isFinite(value)) {
+    return new Date().toISOString();
+  }
+  return new Date(value * 1000).toISOString();
+}
+
+function openHermesDatabase(): Database.Database | null {
+  if (!fsSync.existsSync(HERMES_DB_PATH)) {
+    return null;
+  }
+  return new Database(HERMES_DB_PATH, { readonly: true, fileMustExist: true });
+}
+
+export class HermesSessionSynchronizer implements IProviderSessionSynchronizer {
+  private readonly provider = 'hermes' as const;
+
+  async synchronize(since?: Date): Promise<number> {
+    const db = openHermesDatabase();
+    if (!db) {
+      return 0;
+    }
+
+    try {
+      const rows = since
+        ? db.prepare(`
+            SELECT id, cwd, title, started_at, ended_at, message_count
+            FROM sessions
+            WHERE COALESCE(ended_at, started_at) >= ?
+            ORDER BY COALESCE(ended_at, started_at) ASC
+          `).all(Math.floor(since.getTime() / 1000)) as HermesSessionRow[]
+        : db.prepare(`
+            SELECT id, cwd, title, started_at, ended_at, message_count
+            FROM sessions
+            ORDER BY COALESCE(ended_at, started_at) ASC
+          `).all() as HermesSessionRow[];
+
+      let processed = 0;
+      for (const row of rows) {
+        if (this.upsertRow(row)) {
+          processed += 1;
+        }
+      }
+      return processed;
+    } finally {
+      db.close();
+    }
+  }
+
+  async synchronizeFile(filePath: string): Promise<string | null> {
+    if (path.resolve(filePath) !== HERMES_DB_PATH) {
+      return null;
+    }
+
+    const db = openHermesDatabase();
+    if (!db) {
+      return null;
+    }
+
+    try {
+      const row = db.prepare(`
+        SELECT id, cwd, title, started_at, ended_at, message_count
+        FROM sessions
+        ORDER BY COALESCE(ended_at, started_at) DESC
+        LIMIT 1
+      `).get() as HermesSessionRow | undefined;
+      return row && this.upsertRow(row) ? row.id : null;
+    } finally {
+      db.close();
+    }
+  }
+
+  private upsertRow(row: HermesSessionRow): boolean {
+    if (!row.id || !row.cwd) {
+      return false;
+    }
+
+    sessionsDb.createSession(
+      row.id,
+      this.provider,
+      row.cwd,
+      normalizeSessionName(row.title ?? undefined, 'Untitled Hermes Session'),
+      unixSecondsToIso(row.started_at),
+      unixSecondsToIso(row.ended_at ?? row.started_at),
+      HERMES_DB_PATH,
+    );
+    return true;
+  }
+}

server/modules/providers/list/hermes/hermes-sessions.provider.ts

@@ -0,0 +1,381 @@
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import Database from 'better-sqlite3';
+
+import { sessionsDb } from '@/modules/database/index.js';
+import type { IProviderSessions } from '@/shared/interfaces.js';
+import type { AnyRecord, FetchHistoryOptions, FetchHistoryResult, NormalizedMessage } from '@/shared/types.js';
+import {
+  createNormalizedMessage,
+  generateMessageId,
+  normalizeProviderTimestamp,
+  readObjectRecord,
+  readOptionalString,
+  sliceTailPage,
+} from '@/shared/utils.js';
+
+const PROVIDER = 'hermes';
+const HERMES_DB_PATH = path.join(os.homedir(), '.hermes', 'state.db');
+
+type HermesMessageRow = {
+  id: number;
+  role: string;
+  content: string | null;
+  tool_call_id: string | null;
+  tool_calls: string | null;
+  tool_name: string | null;
+  timestamp: number;
+  reasoning: string | null;
+  reasoning_content: string | null;
+  finish_reason: string | null;
+};
+
+function formatContent(value: unknown): string {
+  if (value === undefined || value === null) {
+    return '';
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+function readUpdateType(raw: AnyRecord): string {
+  return readOptionalString(raw.type)
+    ?? readOptionalString(raw.kind)
+    ?? readOptionalString(raw.sessionUpdate)
+    ?? readOptionalString(raw.session_update)
+    ?? readOptionalString(raw.update)
+    ?? readOptionalString(raw.event)
+    ?? '';
+}
+
+function readEventSessionId(raw: AnyRecord, sessionId: string | null): string | null {
+  return readOptionalString(raw.sessionId) ?? readOptionalString(raw.session_id) ?? sessionId;
+}
+
+function readTextContent(value: unknown): string | null {
+  const direct = readOptionalString(value);
+  if (direct !== undefined) {
+    return direct;
+  }
+
+  if (Array.isArray(value)) {
+    const parts = value
+      .map((entry) => readTextContent(entry))
+      .filter((entry): entry is string => Boolean(entry?.trim()));
+    return parts.length > 0 ? parts.join('') : null;
+  }
+
+  const record = readObjectRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const nestedContent = record.content;
+  const nestedText = nestedContent === value ? null : readTextContent(nestedContent);
+
+  return readOptionalString(record.text)
+    ?? readOptionalString(record.content)
+    ?? nestedText
+    ?? readOptionalString(record.delta)
+    ?? readOptionalString(record.rawOutput)
+    ?? readOptionalString(record.raw_output)
+    ?? readOptionalString(record.output)
+    ?? null;
+}
+
+function readToolPayload(raw: AnyRecord): AnyRecord {
+  return readObjectRecord(raw.toolCall)
+    ?? readObjectRecord(raw.tool_call)
+    ?? readObjectRecord(raw.tool)
+    ?? raw;
+}
+
+function normalizeHermesEvent(rawMessage: unknown, sessionId: string | null, history = false): NormalizedMessage[] {
+  const envelope = readObjectRecord(rawMessage);
+  if (!envelope) {
+    return [];
+  }
+
+  const nestedUpdate = readObjectRecord(envelope.update);
+  const raw = nestedUpdate ? { ...nestedUpdate, sessionId: envelope.sessionId ?? envelope.session_id ?? sessionId } : envelope;
+
+  const type = readUpdateType(raw);
+  const eventSessionId = readEventSessionId(raw, sessionId);
+  const timestamp = normalizeProviderTimestamp(raw.timestamp ?? raw.time ?? raw.createdAt ?? raw.created_at);
+  const baseId = readOptionalString(raw.id) ?? readOptionalString(raw.messageId) ?? readOptionalString(raw.message_id) ?? generateMessageId(PROVIDER);
+
+  if (['agent_message_chunk', 'assistant_message_chunk', 'message_delta', 'text_delta', 'text'].includes(type)) {
+    const content = readTextContent(raw.content)
+      ?? readOptionalString(raw.text)
+      ?? readOptionalString(raw.delta)
+      ?? readTextContent(readObjectRecord(raw.message)?.content)
+      ?? '';
+    if (!content.trim()) {
+      return [];
+    }
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: history ? 'text' : 'stream_delta',
+      role: history ? 'assistant' : undefined,
+      content,
+    })];
+  }
+
+  if (['agent_message', 'assistant_message', 'message'].includes(type)) {
+    const role = readOptionalString(raw.role) === 'user' ? 'user' : 'assistant';
+    const content = readTextContent(raw.content)
+      ?? readOptionalString(raw.text)
+      ?? readTextContent(readObjectRecord(raw.message)?.content)
+      ?? '';
+    if (!content.trim()) {
+      return [];
+    }
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: history ? 'text' : role === 'assistant' ? 'stream_delta' : 'text',
+      role: history || role === 'user' ? role : undefined,
+      content,
+    })];
+  }
+
+  if (['agent_thought_chunk', 'thought_delta', 'thinking', 'reasoning'].includes(type)) {
+    const content = readTextContent(raw.content) ?? readOptionalString(raw.text) ?? readOptionalString(raw.delta) ?? '';
+    if (!content.trim()) {
+      return [];
+    }
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: 'thinking',
+      content,
+    })];
+  }
+
+  if (['tool_call', 'tool_use', 'tool_call_start'].includes(type)) {
+    const tool = readToolPayload(raw);
+    const toolId = readOptionalString(raw.toolCallId)
+      ?? readOptionalString(raw.tool_call_id)
+      ?? readOptionalString(raw.toolId)
+      ?? readOptionalString(tool.toolCallId)
+      ?? readOptionalString(tool.tool_call_id)
+      ?? readOptionalString(tool.toolId)
+      ?? readOptionalString(tool.id)
+      ?? baseId;
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: 'tool_use',
+      toolName: readOptionalString(raw.toolName)
+        ?? readOptionalString(raw.tool_name)
+        ?? readOptionalString(raw.title)
+        ?? readOptionalString(raw.name)
+        ?? readOptionalString(tool?.name)
+        ?? readOptionalString(tool?.title)
+        ?? 'Tool',
+      toolInput: raw.rawInput
+        ?? raw.raw_input
+        ?? raw.input
+        ?? raw.arguments
+        ?? raw.params
+        ?? tool?.rawInput
+        ?? tool?.raw_input
+        ?? tool?.input
+        ?? tool?.arguments
+        ?? {},
+      toolId,
+    })];
+  }
+
+  if (['tool_call_update', 'tool_result', 'tool_call_result', 'tool_call_done'].includes(type)) {
+    const tool = readToolPayload(raw);
+    const content = readTextContent(raw.content)
+      ?? readTextContent(raw.rawOutput)
+      ?? readTextContent(raw.raw_output)
+      ?? readTextContent(raw.output)
+      ?? readTextContent(raw.result)
+      ?? readTextContent(tool.rawOutput)
+      ?? readTextContent(tool.raw_output)
+      ?? readTextContent(tool.output)
+      ?? readTextContent(tool.result)
+      ?? '';
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: 'tool_result',
+      toolId: readOptionalString(raw.toolCallId)
+        ?? readOptionalString(raw.tool_call_id)
+        ?? readOptionalString(raw.toolId)
+        ?? readOptionalString(tool.toolCallId)
+        ?? readOptionalString(tool.tool_call_id)
+        ?? readOptionalString(tool.toolId)
+        ?? readOptionalString(tool.id)
+        ?? '',
+      content: content || formatContent(raw.delta ?? ''),
+      isError: Boolean(raw.error) || raw.status === 'error' || raw.status === 'failed',
+      toolUseResult: raw.result ?? raw.output ?? raw.rawOutput ?? raw.raw_output ?? tool.result ?? tool.output ?? tool.rawOutput ?? tool.raw_output,
+    })];
+  }
+
+  if (type === 'plan') {
+    const content = readOptionalString(raw.content) ?? readOptionalString(raw.text) ?? formatContent(raw.plan);
+    if (!content.trim()) {
+      return [];
+    }
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: 'status',
+      text: 'plan',
+      summary: content,
+    })];
+  }
+
+  if (type === 'error') {
+    return [createNormalizedMessage({
+      id: baseId,
+      sessionId: eventSessionId,
+      timestamp,
+      provider: PROVIDER,
+      kind: 'error',
+      content: readOptionalString(raw.error) ?? readOptionalString(raw.message) ?? 'Unknown Hermes error',
+    })];
+  }
+
+  return [];
+}
+
+function parseJsonArray(value: string | null): unknown[] {
+  if (!value) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function readHermesHistoryFromDatabase(sessionId: string): NormalizedMessage[] {
+  const normalized: NormalizedMessage[] = [];
+  if (!fsSync.existsSync(HERMES_DB_PATH)) {
+    return normalized;
+  }
+
+  const db = new Database(HERMES_DB_PATH, { readonly: true, fileMustExist: true });
+  try {
+    const rows = db.prepare(`
+      SELECT id, role, content, tool_call_id, tool_calls, tool_name, timestamp, reasoning, reasoning_content, finish_reason
+      FROM messages
+      WHERE session_id = ? AND active = 1
+      ORDER BY timestamp ASC, id ASC
+    `).all(sessionId) as HermesMessageRow[];
+
+    for (const row of rows) {
+      const timestamp = new Date(row.timestamp * 1000).toISOString();
+      const baseId = `hermes-${sessionId}-${row.id}`;
+
+      const reasoning = row.reasoning_content || row.reasoning;
+      if (reasoning?.trim()) {
+        normalized.push(createNormalizedMessage({
+          id: `${baseId}-thinking`,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'thinking',
+          content: reasoning,
+        }));
+      }
+
+      for (const toolCall of parseJsonArray(row.tool_calls)) {
+        const call = readObjectRecord(toolCall);
+        const fn = readObjectRecord(call?.function);
+        normalized.push(createNormalizedMessage({
+          id: `${baseId}-tool-${readOptionalString(call?.id) ?? normalized.length}`,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'tool_use',
+          toolName: readOptionalString(fn?.name) ?? readOptionalString(call?.name) ?? 'Tool',
+          toolInput: fn?.arguments ?? call?.arguments ?? {},
+          toolId: readOptionalString(call?.id) ?? `${baseId}-tool`,
+        }));
+      }
+
+      if (row.role === 'tool') {
+        normalized.push(createNormalizedMessage({
+          id: `${baseId}-result`,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'tool_result',
+          toolId: row.tool_call_id ?? '',
+          content: row.content ?? '',
+          isError: row.finish_reason === 'error',
+        }));
+        continue;
+      }
+
+      if (row.content?.trim()) {
+        normalized.push(createNormalizedMessage({
+          id: baseId,
+          sessionId,
+          timestamp,
+          provider: PROVIDER,
+          kind: 'text',
+          role: row.role === 'user' ? 'user' : 'assistant',
+          content: row.content,
+        }));
+      }
+    }
+  } finally {
+    db.close();
+  }
+
+  return normalized;
+}
+
+export class HermesSessionsProvider implements IProviderSessions {
+  normalizeMessage(rawMessage: unknown, sessionId: string | null): NormalizedMessage[] {
+    return normalizeHermesEvent(rawMessage, sessionId);
+  }
+
+  async fetchHistory(sessionId: string, options: FetchHistoryOptions = {}): Promise<FetchHistoryResult> {
+    const { limit = null, offset = 0 } = options;
+    const row = sessionsDb.getSessionById(sessionId) ?? sessionsDb.getSessionByProviderSessionId(sessionId);
+    const messages = readHermesHistoryFromDatabase(row?.provider_session_id ?? sessionId);
+
+    const start = Math.max(0, offset);
+    const pageLimit = limit === null ? null : Math.max(0, limit);
+    const page = sliceTailPage(messages, pageLimit, start);
+    return {
+      messages: page.page,
+      total: messages.length,
+      hasMore: page.hasMore,
+      offset: start,
+      limit: pageLimit,
+    };
+  }
+}

server/modules/providers/list/hermes/hermes-skills.provider.ts

@@ -0,0 +1,181 @@
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { SkillsProvider } from '@/modules/providers/shared/skills/skills.provider.js';
+import type {
+  ProviderSkillRegistryActionResult,
+  ProviderSkillRegistryInstallInput,
+  ProviderSkillRegistrySearchOptions,
+  ProviderSkillRegistrySearchResult,
+  ProviderSkillSource,
+} from '@/shared/types.js';
+import { AppError, addUniqueProviderSkillSource, readObjectRecord, readOptionalString } from '@/shared/utils.js';
+
+const execFileAsync = promisify(execFile);
+const HERMES_COMMAND =
+  (process.env.HERMES_COMMAND_PATH || process.env.HERMES_CLI_PATH || 'hermes').trim().split(/\s+/)[0] || 'hermes';
+const HERMES_SKILLS_TIMEOUT_MS = 45_000;
+const HERMES_SKILLS_MAX_BUFFER = 1024 * 1024 * 8;
+
+function normalizeSearchResult(value: unknown): ProviderSkillRegistrySearchResult | null {
+  const record = readObjectRecord(value);
+  if (!record) {
+    return null;
+  }
+
+  const name = readOptionalString(record.name);
+  const identifier = readOptionalString(record.identifier);
+  if (!name || !identifier) {
+    return null;
+  }
+
+  return {
+    name,
+    identifier,
+    source: readOptionalString(record.source) ?? undefined,
+    trustLevel: readOptionalString(record.trust_level) ?? readOptionalString(record.trustLevel) ?? undefined,
+    description: readOptionalString(record.description) ?? undefined,
+  };
+}
+
+export class HermesSkillsProvider extends SkillsProvider {
+  constructor() {
+    super('hermes');
+  }
+
+  async searchRegistry(
+    query: string,
+    options: ProviderSkillRegistrySearchOptions = {},
+  ): Promise<ProviderSkillRegistrySearchResult[]> {
+    const normalizedQuery = query.trim();
+    if (!normalizedQuery) {
+      return [];
+    }
+
+    const args = ['skills', 'search', normalizedQuery, '--json'];
+    const source = options.source?.trim();
+    if (source) {
+      args.push('--source', source);
+    }
+    if (options.limit && Number.isFinite(options.limit)) {
+      args.push('--limit', String(Math.max(1, Math.min(Math.floor(options.limit), 50))));
+    }
+
+    const result = await this.runHermes(args);
+    try {
+      const parsed = JSON.parse(result.stdout);
+      return Array.isArray(parsed)
+        ? parsed.map(normalizeSearchResult).filter((entry): entry is ProviderSkillRegistrySearchResult => Boolean(entry))
+        : [];
+    } catch (error) {
+      throw new AppError('Hermes returned invalid skill search JSON.', {
+        code: 'HERMES_SKILL_SEARCH_PARSE_FAILED',
+        statusCode: 502,
+        details: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async installRegistrySkill(input: ProviderSkillRegistryInstallInput): Promise<ProviderSkillRegistryActionResult> {
+    const identifier = input.identifier.trim();
+    if (!identifier) {
+      throw new AppError('identifier is required.', {
+        code: 'HERMES_SKILL_IDENTIFIER_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    const args = ['skills', 'install', identifier, '--yes'];
+    if (input.category?.trim()) {
+      args.push('--category', input.category.trim());
+    }
+    if (input.name?.trim()) {
+      args.push('--name', input.name.trim());
+    }
+    if (input.force) {
+      args.push('--force');
+    }
+
+    return this.runHermes(args);
+  }
+
+  async uninstallRegistrySkill(name: string): Promise<ProviderSkillRegistryActionResult> {
+    const normalizedName = name.trim();
+    if (!normalizedName) {
+      throw new AppError('name is required.', {
+        code: 'HERMES_SKILL_NAME_REQUIRED',
+        statusCode: 400,
+      });
+    }
+    return this.runHermes(['skills', 'uninstall', normalizedName]);
+  }
+
+  async checkRegistryUpdates(): Promise<ProviderSkillRegistryActionResult> {
+    return this.runHermes(['skills', 'check']);
+  }
+
+  async updateRegistrySkills(): Promise<ProviderSkillRegistryActionResult> {
+    return this.runHermes(['skills', 'update']);
+  }
+
+  async auditRegistrySkills(): Promise<ProviderSkillRegistryActionResult> {
+    return this.runHermes(['skills', 'audit']);
+  }
+
+  protected async getSkillSources(workspacePath: string): Promise<ProviderSkillSource[]> {
+    const sources: ProviderSkillSource[] = [];
+    const seenRootDirs = new Set<string>();
+
+    addUniqueProviderSkillSource(sources, seenRootDirs, {
+      scope: 'repo',
+      rootDir: path.join(workspacePath, '.hermes', 'skills'),
+      commandPrefix: '/',
+      recursive: true,
+    });
+    addUniqueProviderSkillSource(sources, seenRootDirs, {
+      scope: 'user',
+      rootDir: path.join(os.homedir(), '.hermes', 'skills'),
+      commandPrefix: '/',
+      recursive: true,
+    });
+
+    return sources;
+  }
+
+  protected async getGlobalSkillSource(): Promise<ProviderSkillSource> {
+    return {
+      scope: 'user',
+      rootDir: path.join(os.homedir(), '.hermes', 'skills'),
+      commandPrefix: '/',
+      recursive: true,
+    };
+  }
+
+  private async runHermes(args: string[]): Promise<ProviderSkillRegistryActionResult> {
+    try {
+      const { stdout, stderr } = await execFileAsync(HERMES_COMMAND, args, {
+        timeout: HERMES_SKILLS_TIMEOUT_MS,
+        maxBuffer: HERMES_SKILLS_MAX_BUFFER,
+        env: process.env,
+      });
+      return { ok: true, stdout, stderr };
+    } catch (error) {
+      const maybeError = error as Error & {
+        stdout?: string;
+        stderr?: string;
+        code?: number | string;
+      };
+      throw new AppError(maybeError.stderr || maybeError.message || 'Hermes skill command failed.', {
+        code: 'HERMES_SKILL_COMMAND_FAILED',
+        statusCode: 502,
+        details: {
+          exitCode: maybeError.code,
+          stdout: maybeError.stdout,
+          stderr: maybeError.stderr,
+        },
+      });
+    }
+  }
+}

server/modules/providers/list/hermes/hermes.provider.ts

@@ -0,0 +1,27 @@
+import { HermesProviderAuth } from '@/modules/providers/list/hermes/hermes-auth.provider.js';
+import { HermesMcpProvider } from '@/modules/providers/list/hermes/hermes-mcp.provider.js';
+import { HermesProviderModels } from '@/modules/providers/list/hermes/hermes-models.provider.js';
+import { HermesSessionSynchronizer } from '@/modules/providers/list/hermes/hermes-session-synchronizer.provider.js';
+import { HermesSessionsProvider } from '@/modules/providers/list/hermes/hermes-sessions.provider.js';
+import { HermesSkillsProvider } from '@/modules/providers/list/hermes/hermes-skills.provider.js';
+import { AbstractProvider } from '@/modules/providers/shared/base/abstract.provider.js';
+import type {
+  IProviderAuth,
+  IProviderModels,
+  IProviderSessionSynchronizer,
+  IProviderSkills,
+  IProviderSessions,
+} from '@/shared/interfaces.js';
+
+export class HermesProvider extends AbstractProvider {
+  readonly models: IProviderModels = new HermesProviderModels();
+  readonly mcp = new HermesMcpProvider();
+  readonly auth: IProviderAuth = new HermesProviderAuth();
+  readonly skills: IProviderSkills = new HermesSkillsProvider();
+  readonly sessions: IProviderSessions = new HermesSessionsProvider();
+  readonly sessionSynchronizer: IProviderSessionSynchronizer = new HermesSessionSynchronizer();
+
+  constructor() {
+    super('hermes');
+  }
+}

server/modules/providers/provider.registry.ts

@@ -2,6 +2,7 @@ import { ClaudeProvider } from '@/modules/providers/list/claude/claude.provider.
 import { CodexProvider } from '@/modules/providers/list/codex/codex.provider.js';
 import { CursorProvider } from '@/modules/providers/list/cursor/cursor.provider.js';
 import { GeminiProvider } from '@/modules/providers/list/gemini/gemini.provider.js';
+import { HermesProvider } from '@/modules/providers/list/hermes/hermes.provider.js';
 import { OpenCodeProvider } from '@/modules/providers/list/opencode/opencode.provider.js';
 import type { IProvider } from '@/shared/interfaces.js';
 import type { LLMProvider } from '@/shared/types.js';
@@ -13,6 +14,7 @@ const providers: Record<LLMProvider, IProvider> = {
   cursor: new CursorProvider(),
   gemini: new GeminiProvider(),
   opencode: new OpenCodeProvider(),
+  hermes: new HermesProvider(),
 };
 
 /**

server/modules/providers/provider.routes.ts

@@ -2,6 +2,7 @@ import express, { type Request, type Response } from 'express';
 
 import { providerAuthService } from '@/modules/providers/services/provider-auth.service.js';
 import { providerCapabilitiesService } from '@/modules/providers/services/provider-capabilities.service.js';
+import { hermesGatewayService } from '@/modules/providers/services/hermes-gateway.service.js';
 import { providerMcpService } from '@/modules/providers/services/mcp.service.js';
 import { providerModelsService } from '@/modules/providers/services/provider-models.service.js';
 import { providerSkillsService } from '@/modules/providers/services/skills.service.js';
@@ -279,6 +280,48 @@ const parseProviderSkillCreatePayload = (payload: unknown): ProviderSkillCreateI
   return { entries };
 };
 
+const parseSkillRegistryLimit = (value: unknown): number => {
+  const raw = readOptionalQueryString(value);
+  if (!raw) {
+    return 10;
+  }
+
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isNaN(parsed)) {
+    throw new AppError('limit must be a valid integer.', {
+      code: 'INVALID_QUERY_PARAMETER',
+      statusCode: 400,
+    });
+  }
+
+  return Math.max(1, Math.min(parsed, 50));
+};
+
+const parseSkillRegistryInstallPayload = (payload: unknown) => {
+  if (!payload || typeof payload !== 'object') {
+    throw new AppError('Request body must be an object.', {
+      code: 'INVALID_REQUEST_BODY',
+      statusCode: 400,
+    });
+  }
+
+  const body = payload as Record<string, unknown>;
+  const identifier = readOptionalQueryString(body.identifier);
+  if (!identifier) {
+    throw new AppError('identifier is required.', {
+      code: 'SKILL_IDENTIFIER_REQUIRED',
+      statusCode: 400,
+    });
+  }
+
+  return {
+    identifier,
+    category: readOptionalQueryString(body.category),
+    name: readOptionalQueryString(body.name),
+    force: body.force === true,
+  };
+};
+
 const parseProvider = (value: unknown): LLMProvider => {
   const normalized = normalizeProviderParam(value);
   if (
@@ -287,6 +330,7 @@ const parseProvider = (value: unknown): LLMProvider => {
     || normalized === 'cursor'
     || normalized === 'gemini'
     || normalized === 'opencode'
+    || normalized === 'hermes'
   ) {
     return normalized;
   }
@@ -297,6 +341,18 @@ const parseProvider = (value: unknown): LLMProvider => {
   });
 };
 
+const parseHermesProvider = (value: unknown): 'hermes' => {
+  const provider = parseProvider(value);
+  if (provider !== 'hermes') {
+    throw new AppError('Gateway controls are only available for Hermes.', {
+      code: 'HERMES_GATEWAY_UNSUPPORTED_PROVIDER',
+      statusCode: 404,
+    });
+  }
+
+  return provider;
+};
+
 const parseSessionRenameSummary = (payload: unknown): string => {
   if (!payload || typeof payload !== 'object') {
     throw new AppError('Request body must be an object.', {
@@ -441,6 +497,77 @@ router.delete(
   }),
 );
 
+router.get(
+  '/:provider/skills/registry/search',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const query = readOptionalQueryString(req.query.query);
+    if (!query) {
+      throw new AppError('query is required.', {
+        code: 'SKILL_SEARCH_QUERY_REQUIRED',
+        statusCode: 400,
+      });
+    }
+
+    const results = await providerSkillsService.searchSkillRegistry(provider, query, {
+      source: readOptionalQueryString(req.query.source),
+      limit: parseSkillRegistryLimit(req.query.limit),
+    });
+    res.json(createApiSuccessResponse({ provider, results }));
+  }),
+);
+
+router.post(
+  '/:provider/skills/registry/install',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const result = await providerSkillsService.installRegistrySkill(
+      provider,
+      parseSkillRegistryInstallPayload(req.body),
+    );
+    res.status(201).json(createApiSuccessResponse({ provider, result }));
+  }),
+);
+
+router.post(
+  '/:provider/skills/registry/check',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const result = await providerSkillsService.checkRegistryUpdates(provider);
+    res.json(createApiSuccessResponse({ provider, result }));
+  }),
+);
+
+router.post(
+  '/:provider/skills/registry/update',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const result = await providerSkillsService.updateRegistrySkills(provider);
+    res.json(createApiSuccessResponse({ provider, result }));
+  }),
+);
+
+router.post(
+  '/:provider/skills/registry/audit',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const result = await providerSkillsService.auditRegistrySkills(provider);
+    res.json(createApiSuccessResponse({ provider, result }));
+  }),
+);
+
+router.delete(
+  '/:provider/skills/registry/:name',
+  asyncHandler(async (req: Request, res: Response) => {
+    const provider = parseProvider(req.params.provider);
+    const result = await providerSkillsService.uninstallRegistrySkill(
+      provider,
+      readPathParam(req.params.name, 'name'),
+    );
+    res.json(createApiSuccessResponse({ provider, result }));
+  }),
+);
+
 // ----------------- MCP routes -----------------
 router.get(
   '/:provider/mcp/servers',
@@ -523,6 +650,51 @@ router.get(
   }),
 );
 
+// ----------------- Hermes gateway routes -----------------
+router.get(
+  '/:provider/gateway/status',
+  asyncHandler(async (req: Request, res: Response) => {
+    parseHermesProvider(req.params.provider);
+    const status = await hermesGatewayService.getStatus();
+    res.json(createApiSuccessResponse(status));
+  }),
+);
+
+router.get(
+  '/:provider/gateway/logs',
+  asyncHandler(async (req: Request, res: Response) => {
+    parseHermesProvider(req.params.provider);
+    res.json(createApiSuccessResponse({ logs: hermesGatewayService.getLogs() }));
+  }),
+);
+
+router.post(
+  '/:provider/gateway/start',
+  asyncHandler(async (req: Request, res: Response) => {
+    parseHermesProvider(req.params.provider);
+    const status = await hermesGatewayService.start();
+    res.json(createApiSuccessResponse(status));
+  }),
+);
+
+router.post(
+  '/:provider/gateway/stop',
+  asyncHandler(async (req: Request, res: Response) => {
+    parseHermesProvider(req.params.provider);
+    const status = await hermesGatewayService.stop();
+    res.json(createApiSuccessResponse(status));
+  }),
+);
+
+router.post(
+  '/:provider/gateway/restart',
+  asyncHandler(async (req: Request, res: Response) => {
+    parseHermesProvider(req.params.provider);
+    const status = await hermesGatewayService.restart();
+    res.json(createApiSuccessResponse(status));
+  }),
+);
+
 // ----------------- Session routes -----------------
 /**
  * Session gateway entry point: allocates the stable app-facing session id for

server/modules/providers/services/hermes-gateway.service.ts

@@ -0,0 +1,317 @@
+import { spawn, execFile, type ChildProcess } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { AppError } from '@/shared/utils.js';
+
+const execFileAsync = promisify(execFile);
+
+const gatewayCommandParts = (process.env.HERMES_GATEWAY_COMMAND || '').trim().split(/\s+/).filter(Boolean);
+const fallbackHermesCommand = (
+  process.env.HERMES_COMMAND_PATH
+  || process.env.HERMES_CLI_PATH
+  || 'hermes'
+).trim().split(/\s+/)[0] || 'hermes';
+const HERMES_COMMAND = gatewayCommandParts[0] || fallbackHermesCommand;
+const HERMES_BASE_ARGS = gatewayCommandParts.slice(1);
+
+const MAX_LOG_LINES = 300;
+const COMMAND_TIMEOUT_MS = 10_000;
+
+type CommandResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  error?: string;
+};
+
+export type HermesGatewayProfile = {
+  name: string;
+  current: boolean;
+  model: string | null;
+  gateway: string | null;
+  alias: string | null;
+  distribution: string | null;
+};
+
+export type HermesGatewayStatus = {
+  installed: boolean;
+  command: string;
+  version: string | null;
+  running: boolean;
+  managedByCloudCLI: boolean;
+  state: 'running' | 'stopped' | 'unknown';
+  statusOutput: string;
+  profiles: HermesGatewayProfile[];
+  logs: string[];
+  lastExit: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    at: string;
+  } | null;
+  commands: {
+    setup: string;
+    run: string;
+  };
+};
+
+const removeAnsi = (value: string): string => value.replace(/\x1B\[[0-?]*[ -/]*[@-~]/g, '');
+
+const compactOutput = (result: CommandResult): string => (
+  [result.stdout, result.stderr].filter(Boolean).join('\n').trim()
+);
+
+const parseGatewayRunning = (output: string, managedByCloudCLI: boolean): boolean => {
+  if (managedByCloudCLI) {
+    return true;
+  }
+
+  const normalized = output.toLowerCase();
+  if (/\b(not running|stopped|inactive|failed)\b/.test(normalized)) {
+    return false;
+  }
+
+  return /\b(running|active)\b/.test(normalized);
+};
+
+const parseProfiles = (output: string): HermesGatewayProfile[] => {
+  const profiles: HermesGatewayProfile[] = [];
+  for (const rawLine of removeAnsi(output).split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('Profile ') || /^[-─\s]+$/.test(line)) {
+      continue;
+    }
+
+    const current = line.startsWith('◆');
+    const cleaned = line.replace(/^[◆*]\s*/, '').trim();
+    const columns = cleaned.split(/\s{2,}/).map((column) => column.trim());
+    const [name, model, gateway, alias, distribution] = columns;
+    if (!name || name.toLowerCase() === 'profile') {
+      continue;
+    }
+
+    profiles.push({
+      name,
+      current,
+      model: model && model !== '—' ? model : null,
+      gateway: gateway && gateway !== '—' ? gateway : null,
+      alias: alias && alias !== '—' ? alias : null,
+      distribution: distribution && distribution !== '—' ? distribution : null,
+    });
+  }
+
+  return profiles;
+};
+
+class HermesGatewayService {
+  private gatewayProcess: ChildProcess | null = null;
+  private readonly logs: string[] = [];
+  private lastExit: HermesGatewayStatus['lastExit'] = null;
+
+  async getStatus(): Promise<HermesGatewayStatus> {
+    const versionResult = await this.runHermes(['--version'], { timeout: 5000 });
+    const installed = versionResult.exitCode === 0;
+    const version = installed ? compactOutput(versionResult).split(/\r?\n/)[0] || null : null;
+
+    const statusResult = installed
+      ? await this.runHermes(['gateway', 'status'], { timeout: COMMAND_TIMEOUT_MS })
+      : { stdout: '', stderr: versionResult.error || 'Hermes is not installed.', exitCode: 1 };
+    const profilesResult = installed
+      ? await this.runHermes(['profile', 'list'], { timeout: COMMAND_TIMEOUT_MS })
+      : { stdout: '', stderr: '', exitCode: 1 };
+
+    const statusOutput = compactOutput(statusResult);
+    const managedByCloudCLI = this.isManagedProcessRunning();
+    const running = parseGatewayRunning(statusOutput, managedByCloudCLI);
+
+    return {
+      installed,
+      command: this.commandPrefix().join(' '),
+      version,
+      running,
+      managedByCloudCLI,
+      state: running ? 'running' : statusOutput ? 'stopped' : 'unknown',
+      statusOutput,
+      profiles: parseProfiles(profilesResult.stdout),
+      logs: this.getLogs(),
+      lastExit: this.lastExit,
+      commands: {
+        setup: [...this.commandPrefix(), 'gateway', 'setup'].join(' '),
+        run: [...this.commandPrefix(), 'gateway', 'run'].join(' '),
+      },
+    };
+  }
+
+  async start(): Promise<HermesGatewayStatus> {
+    await this.assertInstalled();
+    if (this.isManagedProcessRunning()) {
+      return this.getStatus();
+    }
+
+    const currentStatus = await this.getStatus();
+    if (currentStatus.running) {
+      return currentStatus;
+    }
+
+    const args = [...HERMES_BASE_ARGS, 'gateway', 'run', '--accept-hooks'];
+    this.appendLog(`[cloudcli] starting Hermes gateway: ${HERMES_COMMAND} ${args.join(' ')}`);
+    this.lastExit = null;
+    const child = spawn(HERMES_COMMAND, args, {
+      env: {
+        ...process.env,
+        HERMES_ACCEPT_HOOKS: '1',
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    this.gatewayProcess = child;
+
+    child.stdout?.on('data', (chunk) => this.appendLog(String(chunk)));
+    child.stderr?.on('data', (chunk) => this.appendLog(String(chunk)));
+    child.on('error', (error) => {
+      this.appendLog(`[cloudcli] gateway process error: ${error.message}`);
+    });
+    child.on('exit', (code, signal) => {
+      this.lastExit = {
+        code,
+        signal,
+        at: new Date().toISOString(),
+      };
+      this.appendLog(`[cloudcli] gateway exited with code ${code ?? 'null'}${signal ? ` signal ${signal}` : ''}`);
+      this.gatewayProcess = null;
+    });
+
+    await new Promise((resolve) => {
+      setTimeout(resolve, 500);
+    });
+
+    if (!this.isManagedProcessRunning()) {
+      throw new AppError('Hermes gateway exited before it could start.', {
+        code: 'HERMES_GATEWAY_START_FAILED',
+        statusCode: 500,
+        details: {
+          logs: this.getLogs().slice(-20),
+          lastExit: this.lastExit,
+        },
+      });
+    }
+
+    return this.getStatus();
+  }
+
+  async stop(): Promise<HermesGatewayStatus> {
+    if (this.isManagedProcessRunning() && this.gatewayProcess) {
+      this.appendLog('[cloudcli] stopping managed Hermes gateway');
+      await this.stopManagedProcess();
+      return this.getStatus();
+    }
+
+    await this.runHermes(['gateway', 'stop'], { timeout: COMMAND_TIMEOUT_MS });
+    return this.getStatus();
+  }
+
+  async restart(): Promise<HermesGatewayStatus> {
+    if (this.isManagedProcessRunning()) {
+      await this.stopManagedProcess();
+    } else {
+      await this.runHermes(['gateway', 'stop'], { timeout: COMMAND_TIMEOUT_MS });
+    }
+
+    return this.start();
+  }
+
+  getLogs(): string[] {
+    return [...this.logs];
+  }
+
+  private async assertInstalled(): Promise<void> {
+    const result = await this.runHermes(['--version'], { timeout: 5000 });
+    if (result.exitCode !== 0) {
+      throw new AppError('Hermes is not installed or is not available on PATH.', {
+        code: 'HERMES_NOT_INSTALLED',
+        statusCode: 400,
+        details: compactOutput(result),
+      });
+    }
+  }
+
+  private isManagedProcessRunning(): boolean {
+    return Boolean(this.gatewayProcess && !this.gatewayProcess.killed && this.gatewayProcess.exitCode === null);
+  }
+
+  private async stopManagedProcess(): Promise<void> {
+    const child = this.gatewayProcess;
+    if (!child) {
+      return;
+    }
+
+    const exited = new Promise<void>((resolve) => {
+      child.once('exit', () => resolve());
+    });
+    child.kill('SIGTERM');
+
+    await Promise.race([
+      exited,
+      new Promise<void>((resolve) => {
+        setTimeout(() => {
+          if (this.gatewayProcess === child && this.isManagedProcessRunning()) {
+            this.appendLog('[cloudcli] gateway did not stop after SIGTERM; sending SIGKILL');
+            child.kill('SIGKILL');
+          }
+          resolve();
+        }, 5000);
+      }),
+    ]);
+  }
+
+  private async runHermes(args: string[], options: { timeout: number }): Promise<CommandResult> {
+    try {
+      const result = await execFileAsync(HERMES_COMMAND, [...HERMES_BASE_ARGS, ...args], {
+        timeout: options.timeout,
+        maxBuffer: 1024 * 1024,
+        env: {
+          ...process.env,
+          HERMES_ACCEPT_HOOKS: '1',
+        },
+      });
+
+      return {
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        exitCode: 0,
+      };
+    } catch (error) {
+      const execError = error as NodeJS.ErrnoException & {
+        stdout?: string;
+        stderr?: string;
+        code?: number | string | null;
+      };
+
+      return {
+        stdout: execError.stdout ?? '',
+        stderr: execError.stderr ?? '',
+        exitCode: typeof execError.code === 'number' ? execError.code : 1,
+        error: execError.message,
+      };
+    }
+  }
+
+  private appendLog(chunk: string): void {
+    const lines = removeAnsi(chunk)
+      .split(/\r?\n/)
+      .map((line) => line.trimEnd())
+      .filter(Boolean);
+    if (lines.length === 0) {
+      return;
+    }
+
+    this.logs.push(...lines.map((line) => `${new Date().toISOString()} ${line}`));
+    if (this.logs.length > MAX_LOG_LINES) {
+      this.logs.splice(0, this.logs.length - MAX_LOG_LINES);
+    }
+  }
+
+  private commandPrefix(): string[] {
+    return [HERMES_COMMAND, ...HERMES_BASE_ARGS];
+  }
+}
+
+export const hermesGatewayService = new HermesGatewayService();

server/modules/providers/services/provider-capabilities.service.ts

@@ -75,6 +75,15 @@ const PROVIDER_CAPABILITIES: Record<LLMProvider, ProviderCapabilities> = {
     supportsPermissionRequests: false,
     supportsTokenUsage: true,
   },
+  hermes: {
+    provider: 'hermes',
+    permissionModes: ['default'],
+    defaultPermissionMode: 'default',
+    supportsImages: false,
+    supportsAbort: true,
+    supportsPermissionRequests: true,
+    supportsTokenUsage: false,
+  },
 };
 
 /**

server/modules/providers/services/session-synchronizer.service.ts

@@ -23,6 +23,7 @@ export const sessionSynchronizerService = {
       cursor: 0,
       gemini: 0,
       opencode: 0,
+      hermes: 0,
     };
     const failures: string[] = [];
 

server/modules/providers/services/sessions-watcher.service.ts

@@ -39,6 +39,10 @@ const PROVIDER_WATCH_PATHS: Array<{ provider: LLMProvider; rootPath: string }> =
     provider: 'opencode',
     rootPath: path.join(os.homedir(), '.local', 'share', 'opencode'),
   },
+  {
+    provider: 'hermes',
+    rootPath: path.join(os.homedir(), '.hermes'),
+  },
 ];
 
 const WATCHER_IGNORED_PATTERNS = [
@@ -81,6 +85,10 @@ function isWatcherTargetFile(provider: LLMProvider, filePath: string): boolean {
     return path.basename(filePath) === 'opencode.db';
   }
 
+  if (provider === 'hermes') {
+    return path.basename(filePath) === 'state.db';
+  }
+
   if (provider === 'gemini') {
     return filePath.endsWith('.json') || filePath.endsWith('.jsonl');
   }

server/modules/providers/services/skills.service.ts

@@ -4,7 +4,29 @@ import type {
   ProviderSkillCreateInput,
   ProviderSkillListOptions,
   ProviderSkillRemoveInput,
+  ProviderSkillRegistryActionResult,
+  ProviderSkillRegistryInstallInput,
+  ProviderSkillRegistrySearchOptions,
+  ProviderSkillRegistrySearchResult,
 } from '@/shared/types.js';
+import { AppError } from '@/shared/utils.js';
+
+const getProviderSkills = (providerName: string) => providerRegistry.resolveProvider(providerName).skills;
+
+const requireSkillRegistryMethod = <TMethod extends keyof ReturnType<typeof getProviderSkills>>(
+  providerName: string,
+  methodName: TMethod,
+): NonNullable<ReturnType<typeof getProviderSkills>[TMethod]> => {
+  const skills = getProviderSkills(providerName);
+  const method = skills[methodName];
+  if (typeof method !== 'function') {
+    throw new AppError(`${providerName} does not support skill registry operations.`, {
+      code: 'PROVIDER_SKILL_REGISTRY_UNSUPPORTED',
+      statusCode: 400,
+    });
+  }
+  return method as NonNullable<ReturnType<typeof getProviderSkills>[TMethod]>;
+};
 
 export const providerSkillsService = {
   /**
@@ -14,8 +36,7 @@ export const providerSkillsService = {
     providerName: string,
     options?: ProviderSkillListOptions,
   ): Promise<ProviderSkill[]> {
-    const provider = providerRegistry.resolveProvider(providerName);
-    return provider.skills.listSkills(options);
+    return getProviderSkills(providerName).listSkills(options);
   },
 
   /**
@@ -25,8 +46,44 @@ export const providerSkillsService = {
     providerName: string,
     input: ProviderSkillCreateInput,
   ): Promise<ProviderSkill[]> {
-    const provider = providerRegistry.resolveProvider(providerName);
-    return provider.skills.addSkills(input);
+    return getProviderSkills(providerName).addSkills(input);
+  },
+
+  async searchSkillRegistry(
+    providerName: string,
+    query: string,
+    options?: ProviderSkillRegistrySearchOptions,
+  ): Promise<ProviderSkillRegistrySearchResult[]> {
+    const searchRegistry = requireSkillRegistryMethod(providerName, 'searchRegistry');
+    return searchRegistry.call(getProviderSkills(providerName), query, options);
+  },
+
+  async installRegistrySkill(
+    providerName: string,
+    input: ProviderSkillRegistryInstallInput,
+  ): Promise<ProviderSkillRegistryActionResult> {
+    const installRegistrySkill = requireSkillRegistryMethod(providerName, 'installRegistrySkill');
+    return installRegistrySkill.call(getProviderSkills(providerName), input);
+  },
+
+  async uninstallRegistrySkill(providerName: string, name: string): Promise<ProviderSkillRegistryActionResult> {
+    const uninstallRegistrySkill = requireSkillRegistryMethod(providerName, 'uninstallRegistrySkill');
+    return uninstallRegistrySkill.call(getProviderSkills(providerName), name);
+  },
+
+  async checkRegistryUpdates(providerName: string): Promise<ProviderSkillRegistryActionResult> {
+    const checkRegistryUpdates = requireSkillRegistryMethod(providerName, 'checkRegistryUpdates');
+    return checkRegistryUpdates.call(getProviderSkills(providerName));
+  },
+
+  async updateRegistrySkills(providerName: string): Promise<ProviderSkillRegistryActionResult> {
+    const updateRegistrySkills = requireSkillRegistryMethod(providerName, 'updateRegistrySkills');
+    return updateRegistrySkills.call(getProviderSkills(providerName));
+  },
+
+  async auditRegistrySkills(providerName: string): Promise<ProviderSkillRegistryActionResult> {
+    const auditRegistrySkills = requireSkillRegistryMethod(providerName, 'auditRegistrySkills');
+    return auditRegistrySkills.call(getProviderSkills(providerName));
   },
 
   async removeProviderSkill(

server/modules/providers/tests/mcp.test.ts

@@ -341,7 +341,7 @@ test('providerMcpService global adder writes to all providers and rejects unsupp
       workspacePath,
     });
 
-    assert.equal(globalResult.length, 5);
+    assert.equal(globalResult.length, 6);
     assert.ok(globalResult.every((entry) => entry.created === true));
 
     const claudeProject = await readJson(path.join(workspacePath, '.mcp.json'));
@@ -356,6 +356,11 @@ test('providerMcpService global adder writes to all providers and rejects unsupp
     const opencodeProject = await readJson(path.join(workspacePath, 'opencode.json'));
     assert.ok((opencodeProject.mcp as Record<string, unknown>)['global-http']);
 
+    const hermesProject = await fs.readFile(path.join(workspacePath, '.hermes', 'config.yaml'), 'utf8');
+    assert.match(hermesProject, /^mcp_servers:\n/m);
+    assert.match(hermesProject, /^\s+global-http:\n/m);
+    assert.match(hermesProject, /^\s+url: "https:\/\/global\.example\.com\/mcp"\n/m);
+
     const cursorProject = await readJson(path.join(workspacePath, '.cursor', 'mcp.json'));
     assert.ok((cursorProject.mcpServers as Record<string, unknown>)['global-http']);
 
@@ -377,4 +382,3 @@ test('providerMcpService global adder writes to all providers and rejects unsupp
     await fs.rm(tempRoot, { recursive: true, force: true });
   }
 });
-

server/modules/websocket/services/shell-websocket.service.ts

@@ -109,6 +109,12 @@ function resolveResumeSessionId(
   return resolvedSessionId;
 }
 
+function getHermesShellCommand(): string {
+  return (process.env.HERMES_COMMAND_PATH || process.env.HERMES_CLI_PATH || 'hermes')
+    .trim()
+    .split(/\s+/)[0] || 'hermes';
+}
+
 /**
  * Resolves provider command line for plain shell and agent-backed shell modes.
  */
@@ -161,6 +167,14 @@ function buildShellCommand(
     return initialCommand || 'opencode';
   }
 
+  if (provider === 'hermes') {
+    const command = initialCommand || getHermesShellCommand();
+    if (resumeSessionId) {
+      return `${command} --resume "${resumeSessionId}"`;
+    }
+    return command;
+  }
+
   const command = initialCommand || 'claude';
   if (resumeSessionId) {
     if (os.platform() === 'win32') {
@@ -481,6 +495,8 @@ export function handleShellConnection(
                   ? 'Gemini'
                   : provider === 'opencode'
                     ? 'OpenCode'
+                    : provider === 'hermes'
+                      ? 'Hermes'
                   : 'Claude';
           welcomeMsg = hasSession && resumeSessionId
             ? `\x1b[36mResuming ${providerName} session ${resumeSessionId} in: ${projectPath}\x1b[0m\r\n`

server/routes/agent.js

@@ -10,12 +10,14 @@ import { spawnCursor } from '../cursor-cli.js';
 import { queryCodex } from '../openai-codex.js';
 import { spawnGemini } from '../gemini-cli.js';
 import { spawnOpenCode } from '../opencode-cli.js';
+import { spawnHermes } from '../hermes-cli.js';
 import { Octokit } from '@octokit/rest';
 import { providerModelsService } from '../modules/providers/services/provider-models.service.js';
 import { IS_PLATFORM } from '../constants/config.js';
 import { normalizeProjectPath } from '../shared/utils.js';
 
 const router = express.Router();
+const HERMES_CONFIGURED_MODEL = '__hermes_configured_model__';
 
 /**
  * Middleware to authenticate agent API requests.
@@ -636,7 +638,7 @@ class ResponseCollector {
  *                          - Source for auto-generated branch names (if createBranch=true and no branchName)
  *                          - Fallback for PR title if no commits are made
  *
- * @param {string} provider - (Optional) AI provider to use. Options: 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode'
+ * @param {string} provider - (Optional) AI provider to use. Options: 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode' | 'hermes'
  *                           Default: 'claude'
  *
  * @param {boolean} stream - (Optional) Enable Server-Sent Events (SSE) streaming for real-time updates.
@@ -754,7 +756,7 @@ class ResponseCollector {
  * Input Validations (400 Bad Request):
  *   - Either githubUrl OR projectPath must be provided (not neither)
  *   - message must be non-empty string
- *   - provider must be 'claude', 'cursor', 'codex', 'gemini', or 'opencode'
+ *   - provider must be 'claude', 'cursor', 'codex', 'gemini', 'opencode', or 'hermes'
  *   - createBranch/createPR requires githubUrl OR projectPath (not neither)
  *   - branchName must pass Git naming rules (if provided)
  *
@@ -862,8 +864,8 @@ router.post('/', validateExternalApiKey, async (req, res) => {
     return res.status(400).json({ error: 'message is required' });
   }
 
-  if (!['claude', 'cursor', 'codex', 'gemini', 'opencode'].includes(provider)) {
-    return res.status(400).json({ error: 'provider must be "claude", "cursor", "codex", "gemini", or "opencode"' });
+  if (!['claude', 'cursor', 'codex', 'gemini', 'opencode', 'hermes'].includes(provider)) {
+    return res.status(400).json({ error: 'provider must be "claude", "cursor", "codex", "gemini", "opencode", or "hermes"' });
   }
 
   // Validate GitHub branch/PR creation requirements
@@ -996,6 +998,15 @@ router.post('/', validateExternalApiKey, async (req, res) => {
         sessionId: sessionId || null,
         model: model || opencodeModels.DEFAULT
       }, writer);
+    } else if (provider === 'hermes') {
+      console.log('Starting Hermes ACP session');
+
+      await spawnHermes(message.trim(), {
+        projectPath: finalProjectPath,
+        cwd: finalProjectPath,
+        sessionId: sessionId || null,
+        model: model === HERMES_CONFIGURED_MODEL ? undefined : model
+      }, writer);
     }
 
     // Handle GitHub branch and PR creation after successful agent completion

server/routes/commands.js

@@ -15,7 +15,7 @@ const APP_ROOT = findAppRoot(__dirname);
 
 const router = express.Router();
 
-const MODEL_PROVIDERS = ["claude", "cursor", "codex", "gemini", "opencode"];
+const MODEL_PROVIDERS = ["claude", "cursor", "codex", "gemini", "opencode", "hermes"];
 
 const MODEL_PROVIDER_LABELS = {
   claude: "Claude",
@@ -23,6 +23,7 @@ const MODEL_PROVIDER_LABELS = {
   codex: "Codex",
   gemini: "Gemini",
   opencode: "OpenCode",
+  hermes: "Hermes",
 };
 
 const readModelProvider = (value) => {

server/shared/interfaces.ts

@@ -5,6 +5,10 @@ import type {
   McpScope,
   NormalizedMessage,
   ProviderSkill,
+  ProviderSkillRegistryActionResult,
+  ProviderSkillRegistryInstallInput,
+  ProviderSkillRegistrySearchOptions,
+  ProviderSkillRegistrySearchResult,
   ProviderSkillListOptions,
   ProviderAuthStatus,
   ProviderChangeActiveModelInput,
@@ -116,6 +120,21 @@ export interface IProviderSkills {
   removeSkill(
     input: ProviderSkillRemoveInput,
   ): Promise<{ removed: boolean; provider: LLMProvider; directoryName: string }>;
+
+  searchRegistry?(
+    query: string,
+    options?: ProviderSkillRegistrySearchOptions,
+  ): Promise<ProviderSkillRegistrySearchResult[]>;
+
+  installRegistrySkill?(input: ProviderSkillRegistryInstallInput): Promise<ProviderSkillRegistryActionResult>;
+
+  uninstallRegistrySkill?(name: string): Promise<ProviderSkillRegistryActionResult>;
+
+  checkRegistryUpdates?(): Promise<ProviderSkillRegistryActionResult>;
+
+  updateRegistrySkills?(): Promise<ProviderSkillRegistryActionResult>;
+
+  auditRegistrySkills?(): Promise<ProviderSkillRegistryActionResult>;
 }
 
 // ---------------------------

server/shared/tool-approval-registry.js

@@ -0,0 +1,83 @@
+const pendingApprovals = new Map();
+const APPROVAL_MAX_AGE_MS = 30 * 60 * 1000;
+
+// Drop approvals whose run died without resolving them (WS disconnect, process
+// crash) so their captured payloads/closures don't accumulate unbounded.
+function sweepExpiredApprovals(now = Date.now()) {
+  for (const [requestId, entry] of pendingApprovals) {
+    const receivedAt = entry.receivedAt instanceof Date ? entry.receivedAt.getTime() : 0;
+    if (receivedAt && now - receivedAt > APPROVAL_MAX_AGE_MS) {
+      pendingApprovals.delete(requestId);
+    }
+  }
+}
+
+function clearApprovalsForSession(sessionId) {
+  if (!sessionId) {
+    return;
+  }
+  for (const [requestId, entry] of pendingApprovals) {
+    if (entry.sessionId === sessionId) {
+      pendingApprovals.delete(requestId);
+    }
+  }
+}
+
+function registerApproval(requestId, { resolver, sessionId = null, provider = null, meta = {} } = {}) {
+  if (!requestId || typeof resolver !== 'function') {
+    return;
+  }
+
+  sweepExpiredApprovals();
+
+  pendingApprovals.set(requestId, {
+    resolver,
+    sessionId,
+    provider,
+    meta,
+    receivedAt: meta.receivedAt || meta._receivedAt || new Date(),
+  });
+}
+
+function unregisterApproval(requestId) {
+  pendingApprovals.delete(requestId);
+}
+
+function resolveToolApproval(requestId, decision) {
+  const entry = pendingApprovals.get(requestId);
+  if (!entry) {
+    return false;
+  }
+
+  entry.resolver(decision);
+  return true;
+}
+
+function getPendingApprovalsForSession(sessionId) {
+  const pending = [];
+  for (const [requestId, entry] of pendingApprovals.entries()) {
+    if (entry.sessionId !== sessionId) {
+      continue;
+    }
+
+    pending.push({
+      requestId,
+      toolName: entry.meta.toolName || entry.meta._toolName || 'UnknownTool',
+      input: entry.meta.input ?? entry.meta._input,
+      context: entry.meta.context ?? entry.meta._context,
+      sessionId,
+      provider: entry.provider,
+      receivedAt: entry.receivedAt,
+    });
+  }
+
+  return pending;
+}
+
+export {
+  registerApproval,
+  unregisterApproval,
+  resolveToolApproval,
+  getPendingApprovalsForSession,
+  clearApprovalsForSession,
+};

server/shared/types.ts

@@ -65,7 +65,7 @@ export type AuthenticatedWebSocketRequest = IncomingMessage & {
  * Use this as the source of truth whenever a function or payload needs to identify
  * a specific LLM integration.
  */
-export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode';
+export type LLMProvider = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'hermes';
 
 /**
  * One selectable model row in a provider model catalog.
@@ -365,6 +365,32 @@ export type ProviderSkillRemoveInput = {
   directoryName: string;
 };
 
+export type ProviderSkillRegistrySearchOptions = {
+  source?: string;
+  limit?: number;
+};
+
+export type ProviderSkillRegistrySearchResult = {
+  name: string;
+  identifier: string;
+  source?: string;
+  trustLevel?: string;
+  description?: string;
+};
+
+export type ProviderSkillRegistryInstallInput = {
+  identifier: string;
+  category?: string;
+  name?: string;
+  force?: boolean;
+};
+
+export type ProviderSkillRegistryActionResult = {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+};
+
 /**
  * Normalized skill record returned by provider skill adapters.
  *

src/components/chat/hooks/useChatComposerState.ts

@@ -39,6 +39,7 @@ interface UseChatComposerStateArgs {
   codexModel: string;
   geminiModel: string;
   opencodeModel: string;
+  hermesModel: string;
   isLoading: boolean;
   canAbortSession: boolean;
   tokenBudget: Record<string, unknown> | null;
@@ -336,6 +337,8 @@ export function useChatComposerState({
                 ? geminiModel
                 : provider === 'opencode'
                   ? opencodeModel
+                  : provider === 'hermes'
+                    ? undefined
                   : claudeModel,
           tokenUsage: tokenBudget,
         };
@@ -703,6 +706,8 @@ export function useChatComposerState({
                   ? 'gemini-settings'
                   : provider === 'opencode'
                     ? 'opencode-settings'
+                    : provider === 'hermes'
+                      ? 'hermes-settings'
                   : 'claude-settings';
           const savedSettings = safeLocalStorage.getItem(settingsKey);
           if (savedSettings) {
@@ -729,6 +734,8 @@ export function useChatComposerState({
               ? geminiModel
               : provider === 'opencode'
                 ? opencodeModel
+                : provider === 'hermes'
+                  ? undefined
                 : claudeModel;
 
       // One message shape for every provider. The backend resolves the

src/components/chat/hooks/useChatProviderState.ts

@@ -15,6 +15,7 @@ const FALLBACK_DEFAULT_MODEL: Record<LLMProvider, string> = {
   codex: 'gpt-5.4',
   gemini: 'gemini-3.1-pro-preview',
   opencode: 'anthropic/claude-sonnet-4-5',
+  hermes: '__hermes_configured_model__',
 };
 
 /**
@@ -29,6 +30,7 @@ const FALLBACK_PERMISSION_MODES: Record<LLMProvider, PermissionMode[]> = {
   codex: ['default', 'acceptEdits', 'bypassPermissions'],
   gemini: ['default', 'acceptEdits', 'bypassPermissions', 'plan'],
   opencode: ['default'],
+  hermes: ['default'],
 };
 
 type ProviderCapabilities = {
@@ -93,6 +95,9 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
   const [opencodeModel, setOpenCodeModel] = useState<string>(() => {
     return localStorage.getItem('opencode-model') || FALLBACK_DEFAULT_MODEL.opencode;
   });
+  const [hermesModel, setHermesModel] = useState<string>(() => {
+    return localStorage.getItem('hermes-model') || FALLBACK_DEFAULT_MODEL.hermes;
+  });
 
   /**
    * Backend-owned capability matrix keyed by provider. Drives the permission
@@ -141,12 +146,20 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
       return;
     }
 
-    setOpenCodeModel(model);
-    localStorage.setItem('opencode-model', model);
+    if (targetProvider === 'opencode') {
+      setOpenCodeModel(model);
+      localStorage.setItem('opencode-model', model);
+      return;
+    }
+
+    if (targetProvider === 'hermes') {
+      setHermesModel(model);
+      localStorage.setItem('hermes-model', model);
+    }
   }, []);
 
   const loadProviderModels = useCallback(async (options: { bypassCache?: boolean } = {}) => {
-    const providers: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+    const providers: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode', 'hermes'];
     const requestId = providerModelsRequestIdRef.current + 1;
     providerModelsRequestIdRef.current = requestId;
     const isHardRefresh = options.bypassCache === true;
@@ -324,6 +337,19 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
     }
   }, [providerModelCatalog.opencode, opencodeModel]);
 
+  useEffect(() => {
+    const hermes = providerModelCatalog.hermes;
+    if (hermes) {
+      const next = pickStoredOrCurrent('hermes-model', hermesModel, hermes);
+      if (next !== hermesModel) {
+        setHermesModel(next);
+      }
+      if (localStorage.getItem('hermes-model') !== next) {
+        localStorage.setItem('hermes-model', next);
+      }
+    }
+  }, [providerModelCatalog.hermes, hermesModel]);
+
   useEffect(() => {
     if (!selectedSession?.id) {
       return;
@@ -391,6 +417,15 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
     model: string,
     sessionId?: string | null,
   ) => {
+    if (targetProvider === 'hermes') {
+      setStoredProviderModel(targetProvider, model);
+      return {
+        scope: 'default' as const,
+        changed: false,
+        model,
+      };
+    }
+
     const normalizedSessionId = typeof sessionId === 'string' ? sessionId.trim() : '';
     if (!normalizedSessionId) {
       setStoredProviderModel(targetProvider, model);
@@ -434,6 +469,8 @@ export function useChatProviderState({ selectedSession, selectedProject }: UseCh
     setGeminiModel,
     opencodeModel,
     setOpenCodeModel,
+    hermesModel,
+    setHermesModel,
     permissionMode,
     setPermissionMode,
     pendingPermissionRequests,

src/components/chat/view/ChatInterface.tsx

@@ -75,6 +75,8 @@ function ChatInterface({
     setGeminiModel,
     opencodeModel,
     setOpenCodeModel,
+    hermesModel,
+    setHermesModel,
     permissionMode,
     pendingPermissionRequests,
     setPendingPermissionRequests,
@@ -201,6 +203,7 @@ function ChatInterface({
     codexModel,
     geminiModel,
     opencodeModel,
+    hermesModel,
     isLoading: isProcessing,
     canAbortSession,
     tokenBudget,
@@ -293,7 +296,9 @@ function ChatInterface({
             ? t('messageTypes.gemini')
             : provider === 'opencode'
               ? t('messageTypes.opencode', { defaultValue: 'OpenCode' })
-            : t('messageTypes.claude');
+              : provider === 'hermes'
+                ? t('messageTypes.hermes', { defaultValue: 'Hermes' })
+                : t('messageTypes.claude');
 
     return (
       <div className="flex h-full items-center justify-center">
@@ -334,6 +339,8 @@ function ChatInterface({
           setGeminiModel={setGeminiModel}
           opencodeModel={opencodeModel}
           setOpenCodeModel={setOpenCodeModel}
+          hermesModel={hermesModel}
+          setHermesModel={setHermesModel}
           providerModelCatalog={providerModelCatalog}
           providerModelsLoading={providerModelsLoading}
           tasksEnabled={tasksEnabled}
@@ -425,7 +432,9 @@ function ChatInterface({
                     ? t('messageTypes.gemini')
                     : provider === 'opencode'
                       ? t('messageTypes.opencode', { defaultValue: 'OpenCode' })
-                    : t('messageTypes.claude'),
+                      : provider === 'hermes'
+                        ? t('messageTypes.hermes', { defaultValue: 'Hermes' })
+                        : t('messageTypes.claude'),
           })}
           isTextareaExpanded={isTextareaExpanded}
           sendByCtrlEnter={sendByCtrlEnter}

src/components/chat/view/subcomponents/ChatMessagesPane.tsx

@@ -39,6 +39,8 @@ interface ChatMessagesPaneProps {
   setGeminiModel: (model: string) => void;
   opencodeModel: string;
   setOpenCodeModel: (model: string) => void;
+  hermesModel: string;
+  setHermesModel: (model: string) => void;
   providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
   providerModelsLoading: boolean;
   tasksEnabled: boolean;
@@ -89,6 +91,8 @@ function ChatMessagesPane({
   setGeminiModel,
   opencodeModel,
   setOpenCodeModel,
+  hermesModel,
+  setHermesModel,
   providerModelCatalog,
   providerModelsLoading,
   tasksEnabled,
@@ -177,6 +181,8 @@ function ChatMessagesPane({
           setGeminiModel={setGeminiModel}
           opencodeModel={opencodeModel}
           setOpenCodeModel={setOpenCodeModel}
+          hermesModel={hermesModel}
+          setHermesModel={setHermesModel}
           providerModelCatalog={providerModelCatalog}
           providerModelsLoading={providerModelsLoading}
           tasksEnabled={tasksEnabled}

src/components/chat/view/subcomponents/CommandResultModal.tsx

@@ -63,6 +63,7 @@ const PROVIDER_LABELS: Record<string, string> = {
   codex: 'Codex',
   gemini: 'Gemini',
   opencode: 'OpenCode',
+  hermes: 'Hermes',
 };
 
 const FALLBACK_COMMANDS: CommandEntry[] = [

src/components/chat/view/subcomponents/MessageComponent.tsx

@@ -183,6 +183,8 @@ const MessageComponent = memo(({ message, prevMessage, createDiff, onFileOpen, a
                             ? t('messageTypes.gemini')
                             : provider === 'opencode'
                               ? t('messageTypes.opencode', { defaultValue: 'OpenCode' })
+                              : provider === 'hermes'
+                                ? t('messageTypes.hermes', { defaultValue: 'Hermes' })
                               : t('messageTypes.claude'))}
               </div>
             </div>
@@ -430,4 +432,3 @@ const MessageComponent = memo(({ message, prevMessage, createDiff, onFileOpen, a
 });
 
 export default MessageComponent;
-

src/components/chat/view/subcomponents/ProviderSelectionEmptyState.tsx

@@ -29,6 +29,7 @@ const PROVIDER_META: { id: LLMProvider; name: string }[] = [
   { id: "gemini", name: "Google" },
   { id: "cursor", name: "Cursor" },
   { id: "opencode", name: "OpenCode" },
+  { id: "hermes", name: "Hermes" },
 ];
 
 const MOD_KEY =
@@ -50,6 +51,8 @@ type ProviderSelectionEmptyStateProps = {
   setGeminiModel: (model: string) => void;
   opencodeModel: string;
   setOpenCodeModel: (model: string) => void;
+  hermesModel: string;
+  setHermesModel: (model: string) => void;
   providerModelCatalog: Partial<Record<LLMProvider, ProviderModelsDefinition>>;
   providerModelsLoading: boolean;
   tasksEnabled: boolean;
@@ -79,11 +82,13 @@ function getCurrentModel(
   co: string,
   g: string,
   o: string,
+  h: string,
 ) {
   if (p === "claude") return c;
   if (p === "codex") return co;
   if (p === "gemini") return g;
   if (p === "opencode") return o;
+  if (p === "hermes") return h;
   return cu;
 }
 
@@ -92,6 +97,7 @@ function getProviderDisplayName(p: LLMProvider) {
   if (p === "cursor") return "Cursor";
   if (p === "codex") return "Codex";
   if (p === "opencode") return "OpenCode";
+  if (p === "hermes") return "Hermes";
   return "Gemini";
 }
 
@@ -111,6 +117,8 @@ export default function ProviderSelectionEmptyState({
   setGeminiModel,
   opencodeModel,
   setOpenCodeModel,
+  hermesModel,
+  setHermesModel,
   providerModelCatalog,
   providerModelsLoading,
   tasksEnabled,
@@ -140,6 +148,7 @@ export default function ProviderSelectionEmptyState({
     codexModel,
     geminiModel,
     opencodeModel,
+    hermesModel,
   );
 
   const currentModelLabel = useMemo(() => {
@@ -164,12 +173,15 @@ export default function ProviderSelectionEmptyState({
       } else if (providerId === "opencode") {
         setOpenCodeModel(modelValue);
         localStorage.setItem("opencode-model", modelValue);
+      } else if (providerId === "hermes") {
+        setHermesModel(modelValue);
+        localStorage.setItem("hermes-model", modelValue);
       } else {
         setCursorModel(modelValue);
         localStorage.setItem("cursor-model", modelValue);
       }
     },
-    [setClaudeModel, setCursorModel, setCodexModel, setGeminiModel, setOpenCodeModel],
+    [setClaudeModel, setCursorModel, setCodexModel, setGeminiModel, setOpenCodeModel, setHermesModel],
   );
 
   const handleModelSelect = useCallback(
@@ -277,15 +289,11 @@ export default function ProviderSelectionEmptyState({
                           >
                             <div className="min-w-0 flex-1">
                               <div className="truncate">{model.label}</div>
-                              {/* 
-                              // * Temporarly commented out because the description of models from claude 
-                              // * was a bit inconsistent.  Will return it back when it becomes more consistent.
-                              */}
-                              {/* {model.description && (
+                              {model.description && (
                                 <div className="truncate text-xs text-muted-foreground">
                                   {model.description}
                                 </div>
-                              )} */}
+                              )}
                             </div>
                             {isSelected && (
                               <Check className="ml-auto h-4 w-4 shrink-0 text-primary" />
@@ -319,6 +327,10 @@ export default function ProviderSelectionEmptyState({
                   model: opencodeModel,
                   defaultValue: "Ready with OpenCode {{model}}",
                 }),
+                hermes: t("providerSelection.readyPrompt.hermes", {
+                  model: provider === "hermes" ? currentModelLabel : hermesModel,
+                  defaultValue: "Ready with Hermes {{model}}",
+                }),
               }[provider]
             }
           </p>

src/components/llm-logo-provider/HermesLogo.tsx

@@ -0,0 +1,14 @@
+type HermesLogoProps = {
+  className?: string;
+};
+
+export default function HermesLogo({ className = 'w-5 h-5' }: HermesLogoProps) {
+  return (
+    <img
+      className={`${className} block object-contain`}
+      src="/icons/hermes-agent.png"
+      alt="Hermes"
+      loading="lazy"
+    />
+  );
+}

src/components/llm-logo-provider/SessionProviderLogo.tsx

@@ -3,6 +3,7 @@ import ClaudeLogo from './ClaudeLogo';
 import CodexLogo from './CodexLogo';
 import CursorLogo from './CursorLogo';
 import GeminiLogo from './GeminiLogo';
+import HermesLogo from './HermesLogo';
 import OpenCodeLogo from './OpenCodeLogo';
 
 type SessionProviderLogoProps = {
@@ -30,5 +31,9 @@ export default function SessionProviderLogo({
     return <OpenCodeLogo className={className} />;
   }
 
+  if (provider === 'hermes') {
+    return <HermesLogo className={className} />;
+  }
+
   return <ClaudeLogo className={className} />;
 }

src/components/mcp/constants.ts

@@ -6,6 +6,7 @@ export const MCP_PROVIDER_NAMES: Record<McpProvider, string> = {
   codex: 'Codex',
   gemini: 'Gemini',
   opencode: 'OpenCode',
+  hermes: 'Hermes',
 };
 
 export const MCP_SUPPORTED_SCOPES: Record<McpProvider, McpScope[]> = {
@@ -14,6 +15,7 @@ export const MCP_SUPPORTED_SCOPES: Record<McpProvider, McpScope[]> = {
   codex: ['user', 'project'],
   gemini: ['user', 'project'],
   opencode: ['user', 'project'],
+  hermes: ['user', 'project'],
 };
 
 export const MCP_SUPPORTED_TRANSPORTS: Record<McpProvider, McpTransport[]> = {
@@ -22,6 +24,7 @@ export const MCP_SUPPORTED_TRANSPORTS: Record<McpProvider, McpTransport[]> = {
   codex: ['stdio', 'http'],
   gemini: ['stdio', 'http', 'sse'],
   opencode: ['stdio', 'http'],
+  hermes: ['stdio', 'http'],
 };
 
 export const MCP_GLOBAL_SUPPORTED_SCOPES: McpScope[] = ['user', 'project'];
@@ -34,6 +37,7 @@ export const MCP_PROVIDER_BUTTON_CLASSES: Record<McpProvider, string> = {
   codex: 'bg-gray-800 text-white hover:bg-gray-900 dark:bg-gray-700 dark:hover:bg-gray-600',
   gemini: 'bg-blue-600 text-white hover:bg-blue-700',
   opencode: 'bg-zinc-900 text-white hover:bg-zinc-800 dark:bg-zinc-700 dark:hover:bg-zinc-600',
+  hermes: 'bg-emerald-700 text-white hover:bg-emerald-800 dark:bg-emerald-600 dark:hover:bg-emerald-700',
 };
 
 export const MCP_SUPPORTS_WORKING_DIRECTORY: Record<McpProvider, boolean> = {
@@ -42,6 +46,7 @@ export const MCP_SUPPORTS_WORKING_DIRECTORY: Record<McpProvider, boolean> = {
   codex: true,
   gemini: true,
   opencode: false,
+  hermes: false,
 };
 
 export const DEFAULT_MCP_FORM: McpFormState = {

src/components/provider-auth/hooks/useProviderAuthStatus.ts

@@ -12,6 +12,7 @@ import type {
 } from '../types';
 
 type ProviderAuthStatusPayload = {
+  installed?: boolean;
   authenticated?: boolean;
   email?: string | null;
   method?: string | null;
@@ -34,6 +35,7 @@ const toProviderAuthStatus = (
   payload: ProviderAuthStatusPayload,
   fallbackError: string | null = null,
 ): ProviderAuthStatus => ({
+  installed: Boolean(payload.installed),
   authenticated: Boolean(payload.authenticated),
   email: payload.email ?? null,
   method: payload.method ?? null,
@@ -78,6 +80,7 @@ export function useProviderAuthStatus(
 
       if (!response.ok) {
         const status: ProviderAuthStatus = {
+          installed: false,
           authenticated: false,
           email: null,
           method: null,
@@ -95,6 +98,7 @@ export function useProviderAuthStatus(
     } catch (caughtError) {
       console.error(`Error checking ${provider} auth status:`, caughtError);
       const status: ProviderAuthStatus = {
+        installed: false,
         authenticated: false,
         email: null,
         method: null,

src/components/provider-auth/types.ts

@@ -1,6 +1,7 @@
 import type { LLMProvider } from '../../types/app';
 
 export type ProviderAuthStatus = {
+  installed: boolean;
   authenticated: boolean;
   email: string | null;
   method: string | null;
@@ -10,7 +11,7 @@ export type ProviderAuthStatus = {
 
 export type ProviderAuthStatusMap = Record<LLMProvider, ProviderAuthStatus>;
 
-export const CLI_PROVIDERS: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+export const CLI_PROVIDERS: LLMProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode', 'hermes'];
 
 export const PROVIDER_AUTH_STATUS_ENDPOINTS: Record<LLMProvider, string> = {
   claude: '/api/providers/claude/auth/status',
@@ -18,12 +19,14 @@ export const PROVIDER_AUTH_STATUS_ENDPOINTS: Record<LLMProvider, string> = {
   codex: '/api/providers/codex/auth/status',
   gemini: '/api/providers/gemini/auth/status',
   opencode: '/api/providers/opencode/auth/status',
+  hermes: '/api/providers/hermes/auth/status',
 };
 
 export const createInitialProviderAuthStatusMap = (loading = true): ProviderAuthStatusMap => ({
-  claude: { authenticated: false, email: null, method: null, error: null, loading },
-  cursor: { authenticated: false, email: null, method: null, error: null, loading },
-  codex: { authenticated: false, email: null, method: null, error: null, loading },
-  gemini: { authenticated: false, email: null, method: null, error: null, loading },
-  opencode: { authenticated: false, email: null, method: null, error: null, loading },
+  claude: { installed: false, authenticated: false, email: null, method: null, error: null, loading },
+  cursor: { installed: false, authenticated: false, email: null, method: null, error: null, loading },
+  codex: { installed: false, authenticated: false, email: null, method: null, error: null, loading },
+  gemini: { installed: false, authenticated: false, email: null, method: null, error: null, loading },
+  opencode: { installed: false, authenticated: false, email: null, method: null, error: null, loading },
+  hermes: { installed: false, authenticated: false, email: null, method: null, error: null, loading },
 });

src/components/provider-auth/view/ProviderLoginModal.tsx

@@ -9,6 +9,7 @@ type ProviderLoginModalProps = {
   provider?: LLMProvider;
   onComplete?: (exitCode: number) => void;
   customCommand?: string;
+  customTitle?: string;
   isAuthenticated?: boolean;
 };
 
@@ -41,6 +42,10 @@ const getProviderCommand = ({
     return 'opencode auth login';
   }
 
+  if (provider === 'hermes') {
+    return 'hermes model';
+  }
+
   return 'gemini status';
 };
 
@@ -49,6 +54,7 @@ const getProviderTitle = (provider: LLMProvider) => {
   if (provider === 'cursor') return 'Cursor CLI Login';
   if (provider === 'codex') return 'Codex CLI Login';
   if (provider === 'opencode') return 'OpenCode CLI Login';
+  if (provider === 'hermes') return 'Hermes Agent Setup';
   return 'Gemini CLI Configuration';
 };
 
@@ -58,6 +64,7 @@ export default function ProviderLoginModal({
   provider = 'claude',
   onComplete,
   customCommand,
+  customTitle,
   isAuthenticated = false,
 }: ProviderLoginModalProps) {
   if (!isOpen) {
@@ -65,7 +72,7 @@ export default function ProviderLoginModal({
   }
 
   const command = getProviderCommand({ provider, customCommand, isAuthenticated });
-  const title = getProviderTitle(provider);
+  const title = customTitle || getProviderTitle(provider);
 
   const handleComplete = (exitCode: number) => {
     onComplete?.(exitCode);

src/components/settings/constants/constants.ts

@@ -39,7 +39,7 @@ export const SETTINGS_MAIN_TABS: SettingsMainTabMeta[] = [
   { id: 'about', label: 'About', keywords: 'about version info', icon: Info },
 ];
 
-export const AGENT_PROVIDERS: AgentProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+export const AGENT_PROVIDERS: AgentProvider[] = ['claude', 'cursor', 'codex', 'gemini', 'opencode', 'hermes'];
 export const AGENT_CATEGORIES: AgentCategory[] = ['account', 'permissions', 'mcp'];
 
 export const DEFAULT_PROJECT_SORT_ORDER: ProjectSortOrder = 'name';

src/components/settings/hooks/useSettingsController.ts

@@ -164,6 +164,8 @@ export function useSettingsController({ isOpen, initialTab }: UseSettingsControl
 
   const [showLoginModal, setShowLoginModal] = useState(false);
   const [loginProvider, setLoginProvider] = useState<ActiveLoginProvider>('');
+  const [loginCommand, setLoginCommand] = useState<string | undefined>(undefined);
+  const [loginTitle, setLoginTitle] = useState<string | undefined>(undefined);
   const {
     providerAuthStatus,
     checkProviderAuthStatus,
@@ -231,8 +233,10 @@ export function useSettingsController({ isOpen, initialTab }: UseSettingsControl
     }
   }, []);
 
-  const openLoginForProvider = useCallback((provider: AgentProvider) => {
+  const openLoginForProvider = useCallback((provider: AgentProvider, customCommand?: string, customTitle?: string) => {
     setLoginProvider(provider);
+    setLoginCommand(customCommand);
+    setLoginTitle(customTitle);
     setShowLoginModal(true);
   }, []);
 
@@ -417,6 +421,8 @@ export function useSettingsController({ isOpen, initialTab }: UseSettingsControl
     showLoginModal,
     setShowLoginModal,
     loginProvider,
+    loginCommand,
+    loginTitle,
     handleLoginComplete,
   };
 }

src/components/settings/types/types.ts

@@ -5,7 +5,7 @@ import type { ProviderAuthStatus } from '../../provider-auth/types';
 
 export type SettingsMainTab = 'agents' | 'appearance' | 'git' | 'api' | 'voice' | 'tasks' | 'browser' | 'notifications' | 'plugins' | 'about';
 export type AgentProvider = LLMProvider;
-export type AgentCategory = 'account' | 'permissions' | 'mcp' | 'skills';
+export type AgentCategory = 'account' | 'permissions' | 'gateway' | 'mcp' | 'skills';
 export type ProjectSortOrder = 'name' | 'date';
 export type SaveStatus = 'success' | 'error' | null;
 export type CodexPermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions';

src/components/settings/view/Settings.tsx

@@ -58,6 +58,8 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
     showLoginModal,
     setShowLoginModal,
     loginProvider,
+    loginCommand,
+    loginTitle,
     handleLoginComplete,
   } = useSettingsController({
     isOpen,
@@ -232,6 +234,8 @@ function Settings({ isOpen, onClose, projects = [], initialTab = 'agents' }: Set
         onClose={() => setShowLoginModal(false)}
         provider={loginProvider || 'claude'}
         onComplete={handleLoginComplete}
+        customCommand={loginCommand}
+        customTitle={loginTitle}
         isAuthenticated={isAuthenticated}
       />
 

src/components/settings/view/tabs/agents-settings/AgentListItem.tsx

@@ -12,7 +12,7 @@ type AgentListItemProps = {
 
 type AgentConfig = {
   name: string;
-  color: 'blue' | 'purple' | 'gray' | 'indigo' | 'zinc';
+  color: 'blue' | 'purple' | 'gray' | 'indigo' | 'zinc' | 'emerald';
 };
 
 const agentConfig: Record<AgentProvider, AgentConfig> = {
@@ -36,6 +36,10 @@ const agentConfig: Record<AgentProvider, AgentConfig> = {
     name: 'OpenCode',
     color: 'zinc',
   },
+  hermes: {
+    name: 'Hermes',
+    color: 'emerald',
+  },
 };
 
 const colorClasses = {
@@ -54,6 +58,9 @@ const colorClasses = {
   zinc: {
     dot: 'bg-zinc-500',
   },
+  emerald: {
+    dot: 'bg-emerald-600',
+  },
 } as const;
 
 export default function AgentListItem({
@@ -65,6 +72,7 @@ export default function AgentListItem({
 }: AgentListItemProps) {
   const config = agentConfig[agentId];
   const colors = colorClasses[config.color];
+  const isReady = agentId !== 'hermes' && authStatus.authenticated;
 
   if (isMobile) {
     return (
@@ -80,7 +88,7 @@ export default function AgentListItem({
         <div className="flex items-center justify-center gap-1.5">
           <SessionProviderLogo provider={agentId} className="h-4 w-4 flex-shrink-0" />
           <span className="truncate text-xs font-medium">{config.name}</span>
-          {authStatus.authenticated && (
+          {isReady && (
             <span className={`h-1.5 w-1.5 flex-shrink-0 rounded-full ${colors.dot}`} />
           )}
         </div>
@@ -100,10 +108,10 @@ export default function AgentListItem({
     >
       <SessionProviderLogo provider={agentId} className="h-4 w-4 flex-shrink-0" />
       <span>{config.name}</span>
-      {authStatus.authenticated ? (
+      {isReady ? (
         <span className={`h-1.5 w-1.5 flex-shrink-0 rounded-full ${colors.dot}`} />
       ) : authStatus.loading ? (
-        <span className="h-1.5 w-1.5 flex-shrink-0 rounded-full bg-muted-foreground/30 animate-pulse" />
+        <span className="h-1.5 w-1.5 flex-shrink-0 animate-pulse rounded-full bg-muted-foreground/30" />
       ) : null}
     </button>
   );

src/components/settings/view/tabs/agents-settings/AgentsSettingsTab.tsx

@@ -25,33 +25,39 @@ export default function AgentsSettingsTab({
   const visibleCategories = useMemo<AgentCategory[]>(() => (
     selectedAgent === 'opencode'
       ? ['account', 'permissions', 'mcp']
-      : ['account', 'permissions', 'mcp', 'skills']
+      : selectedAgent === 'hermes'
+        ? ['account', 'gateway', 'mcp', 'skills']
+        : ['account', 'permissions', 'mcp', 'skills']
   ), [selectedAgent]);
 
   const visibleAgents = useMemo<AgentProvider[]>(() => {
-    return ['claude', 'cursor', 'codex', 'gemini', 'opencode'];
+    return ['claude', 'cursor', 'codex', 'gemini', 'opencode', 'hermes'];
   }, []);
 
   const agentContextById = useMemo<Record<AgentProvider, AgentContext>>(() => ({
     claude: {
       authStatus: providerAuthStatus.claude,
-      onLogin: () => onProviderLogin('claude'),
+      onLogin: (customCommand, customTitle) => onProviderLogin('claude', customCommand, customTitle),
     },
     cursor: {
       authStatus: providerAuthStatus.cursor,
-      onLogin: () => onProviderLogin('cursor'),
+      onLogin: (customCommand, customTitle) => onProviderLogin('cursor', customCommand, customTitle),
     },
     codex: {
       authStatus: providerAuthStatus.codex,
-      onLogin: () => onProviderLogin('codex'),
+      onLogin: (customCommand, customTitle) => onProviderLogin('codex', customCommand, customTitle),
     },
     gemini: {
       authStatus: providerAuthStatus.gemini,
-      onLogin: () => onProviderLogin('gemini'),
+      onLogin: (customCommand, customTitle) => onProviderLogin('gemini', customCommand, customTitle),
     },
     opencode: {
       authStatus: providerAuthStatus.opencode,
-      onLogin: () => onProviderLogin('opencode'),
+      onLogin: (customCommand, customTitle) => onProviderLogin('opencode', customCommand, customTitle),
+    },
+    hermes: {
+      authStatus: providerAuthStatus.hermes,
+      onLogin: (customCommand, customTitle) => onProviderLogin('hermes', customCommand, customTitle),
     },
   }), [
     onProviderLogin,
@@ -60,6 +66,7 @@ export default function AgentsSettingsTab({
     providerAuthStatus.cursor,
     providerAuthStatus.gemini,
     providerAuthStatus.opencode,
+    providerAuthStatus.hermes,
   ]);
 
   useEffect(() => {

src/components/settings/view/tabs/agents-settings/sections/AgentCategoryContentSection.tsx

@@ -5,6 +5,7 @@ import type { SkillsProject } from '../../../../../skills/types';
 import { ProviderSkills } from '../../../../../skills';
 
 import AccountContent from './content/AccountContent';
+import GatewayContent from './content/GatewayContent';
 import PermissionsContent from './content/PermissionsContent';
 
 export default function AgentCategoryContentSection({
@@ -29,6 +30,12 @@ export default function AgentCategoryContentSection({
         />
       )}
 
+      {selectedCategory === 'gateway' && selectedAgent === 'hermes' && (
+        <GatewayContent
+          onOpenSetup={agentContextById.hermes.onLogin}
+        />
+      )}
+
       {selectedCategory === 'permissions' && selectedAgent === 'claude' && (
         <PermissionsContent
           agent="claude"

src/components/settings/view/tabs/agents-settings/sections/AgentCategoryTabsSection.tsx

@@ -29,6 +29,7 @@ export default function AgentCategoryTabsSection({
           >
             {category === 'account' && t('tabs.account')}
             {category === 'permissions' && t('tabs.permissions')}
+            {category === 'gateway' && t('tabs.gateway', { defaultValue: 'Gateway' })}
             {category === 'mcp' && t('tabs.mcpServers')}
             {category === 'skills' && t('tabs.skills', {
               defaultValue: selectedAgent === 'opencode' ? 'Shared Skills' : 'Skills',

src/components/settings/view/tabs/agents-settings/sections/AgentSelectorSection.tsx

@@ -9,6 +9,7 @@ const AGENT_NAMES: Record<AgentProvider, string> = {
   codex: 'Codex',
   gemini: 'Gemini',
   opencode: 'OpenCode',
+  hermes: 'Hermes',
 };
 
 export default function AgentSelectorSection({
@@ -25,7 +26,8 @@ export default function AgentSelectorSection({
             agent === 'claude' ? 'bg-blue-500' :
             agent === 'cursor' ? 'bg-purple-500' :
             agent === 'gemini' ? 'bg-indigo-500' :
-            agent === 'opencode' ? 'bg-zinc-500' : 'bg-foreground/60';
+            agent === 'opencode' ? 'bg-zinc-500' :
+            agent === 'hermes' ? 'bg-emerald-600' : 'bg-foreground/60';
 
           return (
             <Pill

src/components/settings/view/tabs/agents-settings/sections/content/AccountContent.tsx

@@ -1,5 +1,11 @@
-import { LogIn } from 'lucide-react';
+import {
+  KeyRound,
+  Layers3,
+  LogIn,
+  type LucideIcon,
+} from 'lucide-react';
 import { useTranslation } from 'react-i18next';
+
 import { Badge, Button } from '../../../../../../../shared/view/ui';
 import SessionProviderLogo from '../../../../../../llm-logo-provider/SessionProviderLogo';
 import type { AgentProvider, AuthStatus } from '../../../../../types/types';
@@ -7,7 +13,7 @@ import type { AgentProvider, AuthStatus } from '../../../../../types/types';
 type AccountContentProps = {
   agent: AgentProvider;
   authStatus: AuthStatus;
-  onLogin: () => void;
+  onLogin: (customCommand?: string, customTitle?: string) => void;
 };
 
 type AgentVisualConfig = {
@@ -63,11 +69,49 @@ const agentConfig: Record<AgentProvider, AgentVisualConfig> = {
     subtextClass: 'text-zinc-700 dark:text-zinc-300',
     buttonClass: 'bg-zinc-900 hover:bg-zinc-800 active:bg-zinc-950 dark:bg-zinc-700 dark:hover:bg-zinc-600',
   },
+  hermes: {
+    name: 'Hermes',
+    description: 'Nous Research Hermes Agent',
+    bgClass: 'bg-emerald-50 dark:bg-emerald-900/20',
+    borderClass: 'border-emerald-200 dark:border-emerald-800',
+    textClass: 'text-emerald-950 dark:text-emerald-100',
+    subtextClass: 'text-emerald-700 dark:text-emerald-300',
+    buttonClass: 'bg-emerald-700 hover:bg-emerald-800 active:bg-emerald-900',
+  },
 };
 
+type HermesAction = {
+  label: string;
+  buttonLabel: string;
+  description: string;
+  command: string;
+  title: string;
+  icon: LucideIcon;
+};
+
+const hermesActions: HermesAction[] = [
+  {
+    label: 'Model',
+    buttonLabel: 'Configure',
+    description: 'Choose the provider and model Hermes should use.',
+    command: 'hermes model',
+    title: 'Configure Hermes Model',
+    icon: Layers3,
+  },
+  {
+    label: 'Credentials',
+    buttonLabel: 'Manage',
+    description: 'Update credential pools and API keys.',
+    command: 'hermes auth',
+    title: 'Hermes Credentials',
+    icon: KeyRound,
+  },
+];
+
 export default function AccountContent({ agent, authStatus, onLogin }: AccountContentProps) {
   const { t } = useTranslation('settings');
   const config = agentConfig[agent];
+  const isHermes = agent === 'hermes';
 
   return (
     <div className="space-y-6">
@@ -84,74 +128,121 @@ export default function AccountContent({ agent, authStatus, onLogin }: AccountCo
       </div>
 
       <div className={`${config.bgClass} border ${config.borderClass} rounded-lg p-4`}>
-        <div className="space-y-4">
-          <div className="flex items-center gap-3">
-            <div className="flex-1">
+        {isHermes ? (
+          <div className="space-y-4">
+            <div>
               <div className={`font-medium ${config.textClass}`}>
-                {t('agents.connectionStatus')}
+                {t('agents.hermes.configuration.title', { defaultValue: 'Hermes configuration' })}
               </div>
               <div className={`text-sm ${config.subtextClass}`}>
+                {t('agents.hermes.configuration.description', {
+                  defaultValue: 'Models and credentials are managed by Hermes.',
+                })}
+              </div>
+            </div>
+            <div className="overflow-hidden rounded-lg border border-border/60 bg-background/70">
+              {hermesActions.map((action, index) => {
+                const Icon = action.icon;
+                return (
+                  <div
+                    key={action.command}
+                    className={`flex flex-col gap-3 px-3 py-3 sm:flex-row sm:items-center sm:justify-between ${
+                      index > 0 ? 'border-t border-border/60' : ''
+                    }`}
+                  >
+                    <div className="flex min-w-0 items-start gap-3">
+                      <div className="mt-0.5 flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md bg-muted/60 text-muted-foreground">
+                        <Icon className="h-4 w-4" />
+                      </div>
+                      <div className="min-w-0">
+                        <div className="text-sm font-medium text-foreground">{action.label}</div>
+                        <div className="mt-0.5 text-sm text-muted-foreground">{action.description}</div>
+                      </div>
+                    </div>
+                    <Button
+                      type="button"
+                      variant={index === 0 ? 'default' : 'outline'}
+                      size="sm"
+                      className={index === 0 ? `${config.buttonClass} w-full text-white sm:w-auto` : 'w-full sm:w-auto'}
+                      onClick={() => onLogin(action.command, action.title)}
+                    >
+                      {action.buttonLabel}
+                    </Button>
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        ) : (
+          <div className="space-y-4">
+            <div className="flex items-center gap-3">
+              <div className="flex-1">
+                <div className={`font-medium ${config.textClass}`}>
+                  {t('agents.connectionStatus')}
+                </div>
+                <div className={`text-sm ${config.subtextClass}`}>
+                  {authStatus.loading ? (
+                    t('agents.authStatus.checkingAuth')
+                  ) : authStatus.authenticated ? (
+                    t('agents.authStatus.loggedInAs', {
+                      email: authStatus.email || t('agents.authStatus.authenticatedUser'),
+                    })
+                  ) : (
+                    t('agents.authStatus.notConnected')
+                  )}
+                </div>
+              </div>
+              <div>
                 {authStatus.loading ? (
-                  t('agents.authStatus.checkingAuth')
+                  <Badge variant="secondary" className="bg-muted">
+                    {t('agents.authStatus.checking')}
+                  </Badge>
                 ) : authStatus.authenticated ? (
-                  t('agents.authStatus.loggedInAs', {
-                    email: authStatus.email || t('agents.authStatus.authenticatedUser'),
-                  })
+                  <Badge variant="secondary" className="bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-300">
+                    {t('agents.authStatus.connected')}
+                  </Badge>
                 ) : (
-                  t('agents.authStatus.notConnected')
+                  <Badge variant="secondary" className="bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-300">
+                    {t('agents.authStatus.disconnected')}
+                  </Badge>
                 )}
               </div>
             </div>
-            <div>
-              {authStatus.loading ? (
-                <Badge variant="secondary" className="bg-muted">
-                  {t('agents.authStatus.checking')}
-                </Badge>
-              ) : authStatus.authenticated ? (
-                <Badge variant="secondary" className="bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-300">
-                  {t('agents.authStatus.connected')}
-                </Badge>
-              ) : (
-                <Badge variant="secondary" className="bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-300">
-                  {t('agents.authStatus.disconnected')}
-                </Badge>
-              )}
-            </div>
-          </div>
 
-          {authStatus.method !== 'api_key' && (
-            <div className="border-t border-border/50 pt-4">
-              <div className="flex items-center justify-between">
-                <div>
-                  <div className={`font-medium ${config.textClass}`}>
-                    {authStatus.authenticated ? t('agents.login.reAuthenticate') : t('agents.login.title')}
-                  </div>
-                  <div className={`text-sm ${config.subtextClass}`}>
-                    {authStatus.authenticated
-                      ? t('agents.login.reAuthDescription')
-                      : t('agents.login.description', { agent: config.name })}
+            {authStatus.method !== 'api_key' && (
+              <div className="border-t border-border/50 pt-4">
+                <div className="flex items-center justify-between">
+                  <div>
+                    <div className={`font-medium ${config.textClass}`}>
+                      {authStatus.authenticated ? t('agents.login.reAuthenticate') : t('agents.login.title')}
+                    </div>
+                    <div className={`text-sm ${config.subtextClass}`}>
+                      {authStatus.authenticated
+                        ? t('agents.login.reAuthDescription')
+                        : t('agents.login.description', { agent: config.name })}
+                    </div>
                   </div>
+                  <Button
+                    onClick={() => onLogin()}
+                    className={`${config.buttonClass} text-white`}
+                    size="sm"
+                  >
+                    <LogIn className="mr-2 h-4 w-4" />
+                    {authStatus.authenticated ? t('agents.login.reLoginButton') : t('agents.login.button')}
+                  </Button>
                 </div>
-                <Button
-                  onClick={onLogin}
-                  className={`${config.buttonClass} text-white`}
-                  size="sm"
-                >
-                  <LogIn className="mr-2 h-4 w-4" />
-                  {authStatus.authenticated ? t('agents.login.reLoginButton') : t('agents.login.button')}
-                </Button>
               </div>
-            </div>
-          )}
+            )}
 
-          {authStatus.error && (
-            <div className="border-t border-border/50 pt-4">
-              <div className="text-sm text-red-600 dark:text-red-400">
-                {t('agents.error', { error: authStatus.error })}
+            {authStatus.error && (
+              <div className="border-t border-border/50 pt-4">
+                <div className="text-sm text-red-600 dark:text-red-400">
+                  {t('agents.error', { error: authStatus.error })}
+                </div>
               </div>
-            </div>
-          )}
-        </div>
+            )}
+          </div>
+        )}
       </div>
     </div>
   );

src/components/settings/view/tabs/agents-settings/sections/content/GatewayContent.tsx

@@ -0,0 +1,314 @@
+import { useCallback, useEffect, useState } from 'react';
+import {
+  Activity,
+  Layers3,
+  Play,
+  RefreshCw,
+  RotateCcw,
+  Square,
+  Terminal,
+} from 'lucide-react';
+
+import { Badge, Button, HelpTooltip } from '../../../../../../../shared/view/ui';
+import { authenticatedFetch } from '../../../../../../../utils/api';
+import SettingsCard from '../../../../SettingsCard';
+import SettingsSection from '../../../../SettingsSection';
+
+type GatewayProfile = {
+  name: string;
+  current: boolean;
+  model: string | null;
+  gateway: string | null;
+  alias: string | null;
+  distribution: string | null;
+};
+
+type GatewayStatus = {
+  installed: boolean;
+  command: string;
+  version: string | null;
+  running: boolean;
+  managedByCloudCLI: boolean;
+  state: 'running' | 'stopped' | 'unknown';
+  statusOutput: string;
+  profiles: GatewayProfile[];
+  logs: string[];
+  lastExit: {
+    code: number | null;
+    signal: string | null;
+    at: string;
+  } | null;
+  commands: {
+    setup: string;
+    run: string;
+  };
+};
+
+type ApiSuccess<T> = {
+  success: boolean;
+  data: T;
+};
+
+type GatewayContentProps = {
+  onOpenSetup: (customCommand?: string, customTitle?: string) => void;
+};
+
+const gatewayTooltip = 'Use this when tools outside CloudCLI need to reach Hermes through messaging integrations. Normal CloudCLI chat uses the built-in agent API.';
+const setupTooltip = 'Opens Hermes setup in the terminal so you can connect Telegram, Discord, WhatsApp, or another supported platform.';
+const profilesTooltip = 'Profiles are isolated Hermes configurations. This page shows them for visibility and controls the active gateway process.';
+const logsTooltip = 'These logs come from the gateway process started by CloudCLI in this server session.';
+
+async function readGatewayResponse<T>(response: Response): Promise<T> {
+  const payload = await response.json().catch(() => null) as ApiSuccess<T> | { error?: string } | null;
+  if (!response.ok || !payload || !('success' in payload) || !payload.success) {
+    throw new Error((payload && 'error' in payload && payload.error) || 'Gateway request failed');
+  }
+
+  return payload.data;
+}
+
+export default function GatewayContent({ onOpenSetup }: GatewayContentProps) {
+  const [status, setStatus] = useState<GatewayStatus | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [action, setAction] = useState<'start' | 'stop' | 'restart' | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const refreshStatus = useCallback(async () => {
+    setError(null);
+    try {
+      const response = await authenticatedFetch('/api/providers/hermes/gateway/status');
+      const nextStatus = await readGatewayResponse<GatewayStatus>(response);
+      setStatus(nextStatus);
+    } catch (refreshError) {
+      setError(refreshError instanceof Error ? refreshError.message : 'Could not load gateway status');
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const runAction = useCallback(async (nextAction: 'start' | 'stop' | 'restart') => {
+    setAction(nextAction);
+    setError(null);
+    try {
+      const response = await authenticatedFetch(`/api/providers/hermes/gateway/${nextAction}`, {
+        method: 'POST',
+      });
+      const nextStatus = await readGatewayResponse<GatewayStatus>(response);
+      setStatus(nextStatus);
+    } catch (actionError) {
+      setError(actionError instanceof Error ? actionError.message : `Could not ${nextAction} gateway`);
+      void refreshStatus();
+    } finally {
+      setAction(null);
+    }
+  }, [refreshStatus]);
+
+  useEffect(() => {
+    void refreshStatus();
+  }, [refreshStatus]);
+
+  const busy = Boolean(action);
+  const running = Boolean(status?.running);
+
+  return (
+    <div className="space-y-6">
+      <div className="mb-4 flex items-center gap-3">
+        <div className="flex h-9 w-9 items-center justify-center rounded-md bg-emerald-100 text-emerald-800 dark:bg-emerald-900/30 dark:text-emerald-200">
+          <Activity className="h-5 w-5" />
+        </div>
+        <div className="min-w-0">
+          <div className="flex items-center gap-2">
+            <h3 className="text-lg font-medium text-foreground">Hermes Gateway</h3>
+            <HelpTooltip content={gatewayTooltip} position="right" />
+          </div>
+          <p className="text-sm text-muted-foreground">
+            Manage Hermes messaging gateway runtime for the active environment.
+          </p>
+        </div>
+      </div>
+
+      <SettingsSection
+        title="Runtime"
+        description="Start the gateway in the current CloudCLI server environment."
+      >
+        <SettingsCard>
+          <div className="flex flex-col gap-4 p-4 lg:flex-row lg:items-start lg:justify-between">
+            <div className="min-w-0 space-y-3">
+              <div className="flex flex-wrap items-center gap-2">
+                <Badge
+                  variant="secondary"
+                  className={running
+                    ? 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-300'
+                    : 'bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-300'}
+                >
+                  {loading ? 'Checking' : running ? 'Running' : 'Stopped'}
+                </Badge>
+                {status?.managedByCloudCLI && (
+                  <Badge variant="outline">Managed by CloudCLI</Badge>
+                )}
+                {status && !status.installed && (
+                  <Badge variant="destructive">Hermes not installed</Badge>
+                )}
+              </div>
+
+              <div className="space-y-1 text-sm">
+                <div className="text-foreground">
+                  Command: <span className="font-mono text-muted-foreground">{status?.command ?? 'hermes'}</span>
+                </div>
+                <div className="text-muted-foreground">
+                  {status?.version ?? 'Hermes status will appear after refresh.'}
+                </div>
+                {status?.lastExit && (
+                  <div className="text-muted-foreground">
+                    Last exit: code {status.lastExit.code ?? 'null'}
+                    {status.lastExit.signal ? `, signal ${status.lastExit.signal}` : ''}
+                  </div>
+                )}
+              </div>
+            </div>
+
+            <div className="flex flex-wrap gap-2 lg:justify-end">
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => void refreshStatus()}
+                disabled={loading || busy}
+              >
+                <RefreshCw className="h-4 w-4" />
+                Refresh
+              </Button>
+              <Button
+                type="button"
+                size="sm"
+                onClick={() => void runAction('start')}
+                disabled={!status?.installed || running || busy}
+              >
+                <Play className="h-4 w-4" />
+                {action === 'start' ? 'Starting' : 'Start'}
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => void runAction('restart')}
+                disabled={!status?.installed || busy}
+              >
+                <RotateCcw className="h-4 w-4" />
+                {action === 'restart' ? 'Restarting' : 'Restart'}
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                onClick={() => void runAction('stop')}
+                disabled={!status?.installed || !running || busy}
+              >
+                <Square className="h-4 w-4" />
+                {action === 'stop' ? 'Stopping' : 'Stop'}
+              </Button>
+            </div>
+          </div>
+
+          {status?.statusOutput && (
+            <div className="border-t border-border px-4 py-3">
+              <pre className="max-h-36 overflow-auto whitespace-pre-wrap text-xs leading-relaxed text-muted-foreground">
+                {status.statusOutput}
+              </pre>
+            </div>
+          )}
+
+          {error && (
+            <div className="border-t border-border px-4 py-3 text-sm text-red-600 dark:text-red-400">
+              {error}
+            </div>
+          )}
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection
+        title="Setup"
+        description="Configure messaging platforms through the Hermes CLI."
+      >
+        <SettingsCard>
+          <div className="flex flex-col gap-3 p-4 sm:flex-row sm:items-center sm:justify-between">
+            <div className="min-w-0">
+              <div className="flex items-center gap-2 text-sm font-medium text-foreground">
+                Platform setup
+                <HelpTooltip content={setupTooltip} position="right" />
+              </div>
+              <div className="mt-1 text-sm text-muted-foreground">
+                Opens <span className="font-mono">hermes gateway setup</span> in the shell.
+              </div>
+            </div>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              className="w-full sm:w-auto"
+              onClick={() => onOpenSetup('hermes gateway setup', 'Hermes Gateway Setup')}
+            >
+              <Terminal className="h-4 w-4" />
+              Open setup
+            </Button>
+          </div>
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection
+        title="Profiles"
+        description="View Hermes profiles detected in this environment."
+      >
+        <SettingsCard>
+          <div className="flex items-center gap-2 border-b border-border px-4 py-3 text-sm font-medium text-foreground">
+            <Layers3 className="h-4 w-4 text-muted-foreground" />
+            Hermes profiles
+            <HelpTooltip content={profilesTooltip} position="right" />
+          </div>
+          {status?.profiles.length ? (
+            <div className="divide-y divide-border">
+              {status.profiles.map((profile) => (
+                <div key={profile.name} className="grid gap-2 px-4 py-3 text-sm sm:grid-cols-[1fr_auto_auto] sm:items-center">
+                  <div className="min-w-0">
+                    <div className="flex items-center gap-2 font-medium text-foreground">
+                      {profile.name}
+                      {profile.current && <Badge variant="outline">Current</Badge>}
+                    </div>
+                    <div className="mt-0.5 truncate text-muted-foreground">
+                      {profile.model ?? 'No model configured'}
+                    </div>
+                  </div>
+                  <div className="text-muted-foreground">
+                    Gateway: {profile.gateway ?? 'unknown'}
+                  </div>
+                  <div className="text-muted-foreground">
+                    Alias: {profile.alias ?? 'none'}
+                  </div>
+                </div>
+              ))}
+            </div>
+          ) : (
+            <div className="px-4 py-4 text-sm text-muted-foreground">
+              {loading ? 'Loading profiles...' : 'No Hermes profiles were found.'}
+            </div>
+          )}
+        </SettingsCard>
+      </SettingsSection>
+
+      <SettingsSection
+        title="Logs"
+        description="Recent output from the gateway process managed by CloudCLI."
+      >
+        <SettingsCard>
+          <div className="flex items-center gap-2 border-b border-border px-4 py-3 text-sm font-medium text-foreground">
+            Gateway output
+            <HelpTooltip content={logsTooltip} position="right" />
+          </div>
+          <pre className="max-h-64 overflow-auto whitespace-pre-wrap px-4 py-3 text-xs leading-relaxed text-muted-foreground">
+            {status?.logs.length ? status.logs.join('\n') : 'No CloudCLI-managed gateway logs yet.'}
+          </pre>
+        </SettingsCard>
+      </SettingsSection>
+    </div>
+  );
+}

src/components/settings/view/tabs/agents-settings/types.ts

@@ -11,7 +11,7 @@ import type {
 
 export type AgentContext = {
   authStatus: AuthStatus;
-  onLogin: () => void;
+  onLogin: (customCommand?: string, customTitle?: string) => void;
 };
 
 export type AgentContextByProvider = Record<AgentProvider, AgentContext>;
@@ -19,7 +19,7 @@ export type ProviderAuthStatusByProvider = Record<AgentProvider, AuthStatus>;
 
 export type AgentsSettingsTabProps = {
   providerAuthStatus: ProviderAuthStatusByProvider;
-  onProviderLogin: (provider: AgentProvider) => void;
+  onProviderLogin: (provider: AgentProvider, customCommand?: string, customTitle?: string) => void;
   claudePermissions: ClaudePermissionsState;
   onClaudePermissionsChange: (value: ClaudePermissionsState) => void;
   cursorPermissions: CursorPermissionsState;

src/components/skills/hooks/useProviderSkills.ts

@@ -5,6 +5,9 @@ import type {
   ApiResponse,
   ProviderSkill,
   ProviderSkillCreatePayload,
+  ProviderSkillRegistryActionResponse,
+  ProviderSkillRegistryResult,
+  ProviderSkillRegistrySearchResponse,
   ProviderSkillsResponse,
   SkillsProject,
   SkillsProvider,
@@ -197,6 +200,50 @@ const saveProviderSkills = async (
   return (data.data.skills || []).map((skill) => normalizeSkill(provider, skill));
 };
 
+const searchProviderSkillRegistry = async (
+  provider: SkillsProvider,
+  query: string,
+  limit = 10,
+): Promise<ProviderSkillRegistryResult[]> => {
+  const params = new URLSearchParams({ query, limit: String(limit) });
+  const response = await authenticatedFetch(`/api/providers/${provider}/skills/registry/search?${params.toString()}`);
+  const data = await toResponseJson<ApiResponse<ProviderSkillRegistrySearchResponse>>(response);
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, 'Failed to search skill registry'));
+  }
+  return data.data.results || [];
+};
+
+const runProviderSkillRegistryAction = async (
+  provider: SkillsProvider,
+  action: 'install' | 'check' | 'update' | 'audit',
+  payload?: Record<string, unknown>,
+): Promise<ProviderSkillRegistryActionResponse['result']> => {
+  const response = await authenticatedFetch(`/api/providers/${provider}/skills/registry/${action}`, {
+    method: 'POST',
+    body: payload ? JSON.stringify(payload) : undefined,
+  });
+  const data = await toResponseJson<ApiResponse<ProviderSkillRegistryActionResponse>>(response);
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, `Failed to run ${action}`));
+  }
+  return data.data.result;
+};
+
+const uninstallProviderSkillRegistrySkill = async (
+  provider: SkillsProvider,
+  name: string,
+): Promise<ProviderSkillRegistryActionResponse['result']> => {
+  const response = await authenticatedFetch(`/api/providers/${provider}/skills/registry/${encodeURIComponent(name)}`, {
+    method: 'DELETE',
+  });
+  const data = await toResponseJson<ApiResponse<ProviderSkillRegistryActionResponse>>(response);
+  if (!response.ok || !data.success) {
+    throw new Error(getApiErrorMessage(data, 'Failed to uninstall skill'));
+  }
+  return data.data.result;
+};
+
 const getCacheKey = (provider: SkillsProvider, projects: ProjectTarget[]): string => {
   const projectKey = projects.map((project) => project.path).sort().join('|');
   return `${provider}:${projectKey}`;
@@ -221,6 +268,10 @@ export function useProviderSkills({ selectedProvider, currentProjects }: UseProv
   const [isLoadingProjectScopes, setIsLoadingProjectScopes] = useState(false);
   const [loadError, setLoadError] = useState<string | null>(null);
   const [saveStatus, setSaveStatus] = useState<'success' | 'error' | null>(null);
+  const [registryResults, setRegistryResults] = useState<ProviderSkillRegistryResult[]>([]);
+  const [registryError, setRegistryError] = useState<string | null>(null);
+  const [registryStatus, setRegistryStatus] = useState<string | null>(null);
+  const [registryBusyKey, setRegistryBusyKey] = useState<string | null>(null);
   const activeLoadIdRef = useRef(0);
 
   const projectTargets = useMemo(() => createProjectTargets(currentProjects), [currentProjects]);
@@ -250,7 +301,10 @@ export function useProviderSkills({ selectedProvider, currentProjects }: UseProv
     setIsLoadingProjectScopes(false);
     setLoadError(null);
 
-    let nextSkills = cachedEntry && !options.force ? cachedEntry.skills : [];
+    // Build the authoritative list from the fresh fetches only. The cache still
+    // feeds instant display above, but seeding the merge from it would let
+    // skills deleted out-of-band survive the union and never get pruned.
+    let nextSkills: ProviderSkill[] = [];
     let firstError: string | null = null;
 
     try {
@@ -319,12 +373,86 @@ export function useProviderSkills({ selectedProvider, currentProjects }: UseProv
     }
   }, [refreshSkills, selectedProvider]);
 
+  const searchRegistry = useCallback(async (query: string) => {
+    const normalizedQuery = query.trim();
+    if (!normalizedQuery) {
+      setRegistryResults([]);
+      setRegistryError(null);
+      return;
+    }
+
+    setRegistryBusyKey('search');
+    setRegistryError(null);
+    setRegistryStatus(null);
+    try {
+      setRegistryResults(await searchProviderSkillRegistry(selectedProvider, normalizedQuery, 12));
+    } catch (error) {
+      setRegistryError(error instanceof Error ? error.message : 'Failed to search skill registry');
+    } finally {
+      setRegistryBusyKey((current) => (current === 'search' ? null : current));
+    }
+  }, [selectedProvider]);
+
+  const installRegistrySkill = useCallback(async (identifier: string) => {
+    setRegistryBusyKey(`install:${identifier}`);
+    setRegistryError(null);
+    setRegistryStatus(null);
+    try {
+      await runProviderSkillRegistryAction(selectedProvider, 'install', { identifier });
+      clearProviderSkillCache(selectedProvider);
+      await refreshSkills({ force: true });
+      setRegistryStatus('Skill installed.');
+    } catch (error) {
+      setRegistryError(error instanceof Error ? error.message : 'Failed to install skill');
+    } finally {
+      setRegistryBusyKey((current) => (current === `install:${identifier}` ? null : current));
+    }
+  }, [refreshSkills, selectedProvider]);
+
+  const uninstallRegistrySkill = useCallback(async (name: string) => {
+    setRegistryBusyKey(`uninstall:${name}`);
+    setRegistryError(null);
+    setRegistryStatus(null);
+    try {
+      await uninstallProviderSkillRegistrySkill(selectedProvider, name);
+      clearProviderSkillCache(selectedProvider);
+      await refreshSkills({ force: true });
+      setRegistryStatus('Skill uninstalled.');
+    } catch (error) {
+      setRegistryError(error instanceof Error ? error.message : 'Failed to uninstall skill');
+    } finally {
+      setRegistryBusyKey((current) => (current === `uninstall:${name}` ? null : current));
+    }
+  }, [refreshSkills, selectedProvider]);
+
+  const runRegistryMaintenance = useCallback(async (action: 'check' | 'update' | 'audit') => {
+    setRegistryBusyKey(action);
+    setRegistryError(null);
+    setRegistryStatus(null);
+    try {
+      const result = await runProviderSkillRegistryAction(selectedProvider, action);
+      if (action === 'update' || action === 'audit') {
+        clearProviderSkillCache(selectedProvider);
+        await refreshSkills({ force: true });
+      }
+      setRegistryStatus((result.stdout || result.stderr || `${action} completed.`).trim());
+    } catch (error) {
+      setRegistryError(error instanceof Error ? error.message : `Failed to run ${action}`);
+    } finally {
+      setRegistryBusyKey((current) => (current === action ? null : current));
+    }
+  }, [refreshSkills, selectedProvider]);
+
   useEffect(() => {
     void refreshSkills();
   }, [refreshSkills]);
 
   useEffect(() => {
     setSaveStatus(null);
+    setRegistryResults([]);
+    setRegistryError(null);
+    setRegistryStatus(null);
+    setRegistryBusyKey(null);
   }, [selectedProvider]);
 
   useEffect(() => {
@@ -342,7 +470,15 @@ export function useProviderSkills({ selectedProvider, currentProjects }: UseProv
     isLoadingProjectScopes,
     loadError,
     saveStatus,
+    registryResults,
+    registryError,
+    registryStatus,
+    registryBusyKey,
     addSkills,
     refreshSkills,
+    searchRegistry,
+    installRegistrySkill,
+    uninstallRegistrySkill,
+    runRegistryMaintenance,
   };
 }

src/components/skills/types.ts

@@ -43,6 +43,28 @@ export type ProviderSkillsResponse = {
   skills: Array<Partial<ProviderSkill>>;
 };
 
+export type ProviderSkillRegistryResult = {
+  name: string;
+  identifier: string;
+  source?: string;
+  trustLevel?: string;
+  description?: string;
+};
+
+export type ProviderSkillRegistrySearchResponse = {
+  provider: SkillsProvider;
+  results: ProviderSkillRegistryResult[];
+};
+
+export type ProviderSkillRegistryActionResponse = {
+  provider: SkillsProvider;
+  result: {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+  };
+};
+
 export type ApiSuccessResponse<T> = {
   success: true;
   data: T;

src/components/skills/view/ProviderSkills.tsx

@@ -2,20 +2,24 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useDropzone } from 'react-dropzone';
 import {
   CheckCircle2,
+  Compass,
   FileCode2,
   FileText,
   FileUp,
   FolderUp,
   Loader2,
+  Plus,
   RefreshCw,
   Search,
   Upload,
+  Wrench,
   X,
 } from 'lucide-react';
 import { useTranslation } from 'react-i18next';
 
 import { cn } from '../../../lib/utils';
 import {
+  ActionMenu,
   Badge,
   Button,
   Card,
@@ -23,6 +27,9 @@ import {
   CardDescription,
   CardHeader,
   CardTitle,
+  Dialog,
+  DialogContent,
+  DialogTitle,
   Input,
 } from '../../../shared/view/ui';
 import { useProviderSkills } from '../hooks/useProviderSkills';
@@ -62,6 +69,7 @@ const PROVIDER_NAMES: Record<SkillsProvider, string> = {
   cursor: 'Cursor',
   gemini: 'Gemini',
   opencode: 'OpenCode',
+  hermes: 'Hermes',
 };
 
 const PROVIDER_SKILL_PATHS: Record<Exclude<SkillsProvider, 'opencode'>, string> = {
@@ -69,8 +77,30 @@ const PROVIDER_SKILL_PATHS: Record<Exclude<SkillsProvider, 'opencode'>, string>
   codex: '~/.agents/skills/<skill-name>/SKILL.md',
   cursor: '~/.cursor/skills/<skill-name>/SKILL.md',
   gemini: '~/.gemini/skills/<skill-name>/SKILL.md',
+  hermes: '~/.hermes/skills/<skill-name>/SKILL.md',
 };
 
+const HERMES_SKILL_ACTIONS = [
+  {
+    label: 'Check Updates',
+    description: 'Check installed hub skills.',
+    action: 'check' as const,
+    icon: RefreshCw,
+  },
+  {
+    label: 'Update Hub Skills',
+    description: 'Apply available hub updates.',
+    action: 'update' as const,
+    icon: Upload,
+  },
+  {
+    label: 'Audit Installed',
+    description: 'Re-scan installed hub skills.',
+    action: 'audit' as const,
+    icon: CheckCircle2,
+  },
+];
+
 const SCOPE_LABELS: Record<SkillsScope, string> = {
   user: 'User',
   plugin: 'Plugin',
@@ -209,13 +239,23 @@ export default function ProviderSkills({ selectedProvider, currentProjects }: Pr
     isLoadingProjectScopes,
     loadError,
     saveStatus,
+    registryResults,
+    registryError,
+    registryStatus,
+    registryBusyKey,
     addSkills,
     refreshSkills,
+    searchRegistry,
+    installRegistrySkill,
+    runRegistryMaintenance,
   } = useProviderSkills({ selectedProvider, currentProjects });
   const [queuedFiles, setQueuedFiles] = useState<QueuedSkillFile[]>([]);
   const [submitError, setSubmitError] = useState<string | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [searchQuery, setSearchQuery] = useState('');
+  const [registryQuery, setRegistryQuery] = useState('');
+  const [isAddDialogOpen, setIsAddDialogOpen] = useState(false);
+  const [addMode, setAddMode] = useState<'upload' | 'hub'>('upload');
   const fileInputRef = useRef<HTMLInputElement>(null);
   const folderInputRef = useRef<HTMLInputElement>(null);
 
@@ -227,6 +267,9 @@ export default function ProviderSkills({ selectedProvider, currentProjects }: Pr
     setSubmitError(null);
     setIsSubmitting(false);
     setSearchQuery('');
+    setRegistryQuery('');
+    setIsAddDialogOpen(false);
+    setAddMode('upload');
   }, [selectedProvider]);
 
   useEffect(() => {
@@ -354,6 +397,7 @@ export default function ProviderSkills({ selectedProvider, currentProjects }: Pr
       })));
       await addSkills({ entries });
       setQueuedFiles([]);
+      setIsAddDialogOpen(false);
     } catch (error) {
       setSubmitError(error instanceof Error ? error.message : 'Failed to import skills');
     } finally {
@@ -361,6 +405,230 @@ export default function ProviderSkills({ selectedProvider, currentProjects }: Pr
     }
   }, [addSkills, queuedFiles]);
 
+  const uploadPanel = (
+    <div className="space-y-4">
+      <div className="rounded-lg border border-border/60 bg-muted/15 p-3">
+        <div className="text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground">Install Path</div>
+        <code className="mt-1 block whitespace-normal break-all text-xs text-foreground">{providerPath}</code>
+      </div>
+
+      <div
+        {...getRootProps()}
+        className={cn(
+          'rounded-xl border border-dashed p-4 transition-colors sm:p-5',
+          isDragActive
+            ? 'border-foreground/40 bg-muted/35'
+            : 'border-border/70 bg-muted/15 hover:border-foreground/25 hover:bg-muted/25',
+        )}
+      >
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept=".md,text/markdown"
+          multiple
+          className="hidden"
+          onChange={(event) => {
+            handleDrop(Array.from(event.target.files ?? []));
+            event.target.value = '';
+          }}
+        />
+        <input
+          ref={folderInputRef}
+          type="file"
+          multiple
+          className="hidden"
+          onChange={(event) => {
+            handleFolderSelection(Array.from(event.target.files ?? []));
+            event.target.value = '';
+          }}
+        />
+        <div className="flex flex-col items-center justify-center gap-3 py-4 text-center">
+          <FileUp className="h-7 w-7 text-muted-foreground" strokeWidth={1.5} />
+          <div className="space-y-1">
+            <div className="text-sm font-medium text-foreground">Drop `.md` files or skill folders here</div>
+            <div className="text-sm text-muted-foreground">
+              Upload standalone definitions or choose a full folder to include scripts, references, and assets.
+            </div>
+          </div>
+          <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row">
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => fileInputRef.current?.click()}
+              className="w-full sm:w-auto"
+            >
+              <FileUp className="h-4 w-4" />
+              Choose Files
+            </Button>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() => folderInputRef.current?.click()}
+              className="w-full sm:w-auto"
+            >
+              <FolderUp className="h-4 w-4" />
+              Choose Folder
+            </Button>
+          </div>
+        </div>
+      </div>
+
+      {queuedFiles.length > 0 && (
+        <div className="space-y-2">
+          <div className="text-sm font-medium text-foreground">Queued Files</div>
+          <div className="grid gap-2">
+            {queuedFiles.map((queuedFile) => (
+              <div
+                key={queuedFile.id}
+                className="flex flex-col gap-3 rounded-lg border border-border/70 bg-background/70 px-3 py-3 sm:flex-row sm:items-center sm:justify-between sm:py-2"
+              >
+                <div className="min-w-0">
+                  <div className="truncate text-sm font-medium text-foreground">{queuedFile.name}</div>
+                  <div className="text-xs text-muted-foreground">
+                    {queuedFile.kind === 'folder'
+                      ? `${queuedFile.files.length} files`
+                      : 'Markdown file'}
+                    {' · '}
+                    {formatFileSize(queuedFile.size)}
+                  </div>
+                </div>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  className="w-full sm:w-auto"
+                  onClick={() => {
+                    setQueuedFiles((previous) => previous.filter((file) => file.id !== queuedFile.id));
+                  }}
+                >
+                  Remove
+                </Button>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+
+      <div className="flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center">
+        <Button
+          type="button"
+          onClick={() => void handleUploadInstall()}
+          disabled={isSubmitting}
+          className="w-full sm:w-auto"
+        >
+          {isSubmitting ? <Loader2 className="h-4 w-4 animate-spin" /> : <Upload className="h-4 w-4" />}
+          Install {queuedFiles.length > 0 ? `${queuedFiles.length} Skill${queuedFiles.length === 1 ? '' : 's'}` : 'Skills'}
+        </Button>
+        <span className="text-xs text-muted-foreground">
+          Folder uploads keep the selected folder name; standalone files use the `name` in `SKILL.md`.
+        </span>
+      </div>
+    </div>
+  );
+
+  const hermesHubPanel = selectedProvider === 'hermes' ? (
+    <div className="flex min-h-full flex-col gap-4">
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center">
+        <div className="relative min-w-0 flex-1">
+          <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+          <Input
+            type="text"
+            value={registryQuery}
+            onChange={(event) => setRegistryQuery(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter') {
+                void searchRegistry(registryQuery);
+              }
+            }}
+            placeholder="Search Hermes skills..."
+            aria-label="Search Hermes skills registry"
+            className="h-9 w-full pl-9"
+          />
+        </div>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className="w-full sm:w-auto"
+          disabled={!registryQuery.trim() || registryBusyKey === 'search'}
+          onClick={() => void searchRegistry(registryQuery)}
+        >
+          {registryBusyKey === 'search' ? <Loader2 className="h-4 w-4 animate-spin" /> : <Search className="h-4 w-4" />}
+          Search
+        </Button>
+        <ActionMenu
+          label="Maintenance"
+          icon={Wrench}
+          className="w-full sm:w-auto"
+          triggerClassName="w-full sm:w-auto"
+          items={HERMES_SKILL_ACTIONS.map((action) => ({
+            key: action.action,
+            label: action.label,
+            description: action.description,
+            icon: action.icon,
+            loading: registryBusyKey === action.action,
+            disabled: Boolean(registryBusyKey && registryBusyKey !== action.action),
+            onSelect: () => void runRegistryMaintenance(action.action),
+          }))}
+        />
+      </div>
+
+      {registryResults.length > 0 && (
+        <div className="grid gap-2">
+          {registryResults.map((result) => (
+            <div
+              key={result.identifier}
+              className="flex flex-col gap-3 rounded-lg border border-border/70 bg-background/70 p-3 sm:flex-row sm:items-start sm:justify-between"
+            >
+              <div className="min-w-0">
+                <div className="flex flex-wrap items-center gap-2">
+                  <span className="text-sm font-medium text-foreground">{result.name}</span>
+                  {result.source && (
+                    <Badge variant="outline" className="rounded-full text-[10px]">{result.source}</Badge>
+                  )}
+                  {result.trustLevel && (
+                    <Badge variant="secondary" className="rounded-full text-[10px]">{result.trustLevel}</Badge>
+                  )}
+                </div>
+                <div className="mt-1 break-all font-mono text-xs text-muted-foreground">{result.identifier}</div>
+                {result.description && (
+                  <div className="mt-1 line-clamp-2 text-sm text-muted-foreground">{result.description}</div>
+                )}
+              </div>
+              <Button
+                type="button"
+                size="sm"
+                className="w-full sm:w-auto"
+                disabled={registryBusyKey === `install:${result.identifier}`}
+                onClick={() => void installRegistrySkill(result.identifier)}
+              >
+                {registryBusyKey === `install:${result.identifier}`
+                  ? <Loader2 className="h-4 w-4 animate-spin" />
+                  : <Upload className="h-4 w-4" />}
+                Install
+              </Button>
+            </div>
+          ))}
+        </div>
+      )}
+
+      {registryResults.length === 0 && (
+        <div className="flex min-h-[220px] flex-1 items-center justify-center rounded-lg border border-dashed border-border/70 bg-muted/15 px-4 py-8 text-center">
+          <div className="max-w-sm space-y-2">
+            <Compass className="mx-auto h-6 w-6 text-muted-foreground" />
+            <div className="text-sm font-medium text-foreground">Search the Hermes Skills Hub</div>
+            <div className="text-sm text-muted-foreground">
+              Find installable Hermes skills by name, provider, source, or task.
+            </div>
+          </div>
+        </div>
+      )}
+
+    </div>
+  ) : null;
+
   return (
     <div className="min-w-0 space-y-4 overflow-x-hidden">
       <div className="flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-start sm:justify-between">
@@ -376,160 +644,114 @@ export default function ProviderSkills({ selectedProvider, currentProjects }: Pr
           </div>
         </div>
 
-        <Button
-          onClick={() => void refreshSkills({ force: true })}
-          variant="outline"
-          size="sm"
-          className="w-full sm:w-auto"
-          disabled={isLoading || isLoadingProjectScopes}
-        >
-          <RefreshCw className={cn('h-4 w-4', (isLoading || isLoadingProjectScopes) && 'animate-spin')} />
-          Refresh
-        </Button>
+        <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row">
+          <Button
+            type="button"
+            size="sm"
+            className="w-full sm:w-auto"
+            onClick={() => {
+              setAddMode('upload');
+              setIsAddDialogOpen(true);
+            }}
+          >
+            <Plus className="h-4 w-4" />
+            Add Skill
+          </Button>
+          <Button
+            onClick={() => void refreshSkills({ force: true })}
+            variant="outline"
+            size="sm"
+            className="w-full sm:w-auto"
+            disabled={isLoading || isLoadingProjectScopes}
+          >
+            <RefreshCw className={cn('h-4 w-4', (isLoading || isLoadingProjectScopes) && 'animate-spin')} />
+            Refresh
+          </Button>
+        </div>
       </div>
 
-      <Card className="min-w-0 overflow-hidden border-border/70 bg-background shadow-sm">
-        <CardHeader className="space-y-3 border-b border-border/60 bg-muted/20">
-          <div className="flex flex-col gap-2 sm:flex-row sm:flex-wrap sm:items-center">
-            <div className="text-sm font-medium text-foreground">Upload Skills</div>
-            <div className="min-w-0 rounded-2xl border border-border/60 bg-background/70 p-3">
-              <div className="text-xs font-medium uppercase tracking-[0.18em] text-muted-foreground">Install Path</div>
-              <code className="mt-1 block whitespace-normal break-all text-xs text-foreground">{providerPath}</code>
-            </div>
-          </div>
-        </CardHeader>
-
-        <CardContent className="space-y-4 p-4">
-          <div className="space-y-4">
-            <div
-              {...getRootProps()}
-              className={cn(
-                'rounded-3xl border border-dashed p-4 transition-colors sm:p-5',
-                isDragActive
-                  ? 'border-foreground/40 bg-muted/35'
-                  : 'border-border/70 bg-muted/15 hover:border-foreground/25 hover:bg-muted/25',
-              )}
-            >
-              <input
-                ref={fileInputRef}
-                type="file"
-                accept=".md,text/markdown"
-                multiple
-                className="hidden"
-                onChange={(event) => {
-                  handleDrop(Array.from(event.target.files ?? []));
-                  event.target.value = '';
-                }}
-              />
-              <input
-                ref={folderInputRef}
-                type="file"
-                multiple
-                className="hidden"
-                onChange={(event) => {
-                  handleFolderSelection(Array.from(event.target.files ?? []));
-                  event.target.value = '';
-                }}
-              />
-              <div className="flex flex-col items-center justify-center gap-3 py-4 text-center sm:py-6">
-                <FileUp className="h-7 w-7 text-muted-foreground" strokeWidth={1.5} />
-                <div className="space-y-1">
-                  <div className="text-sm font-medium text-foreground">Drop `.md` files or skill folders here</div>
-                  <div className="text-sm text-muted-foreground">
-                    Upload standalone definitions or choose a full folder to include its scripts, references, and assets.
-                  </div>
-                </div>
-                <div className="flex w-full flex-col gap-2 sm:w-auto sm:flex-row">
-                  <Button
-                    type="button"
-                    variant="outline"
-                    size="sm"
-                    onClick={() => fileInputRef.current?.click()}
-                    className="w-full sm:w-auto"
-                  >
-                    <FileUp className="h-4 w-4" />
-                    Choose Files
-                  </Button>
-                  <Button
-                    type="button"
-                    variant="outline"
-                    size="sm"
-                    onClick={() => folderInputRef.current?.click()}
-                    className="w-full sm:w-auto"
-                  >
-                    <FolderUp className="h-4 w-4" />
-                    Choose Folder
-                  </Button>
+      <Dialog open={isAddDialogOpen} onOpenChange={setIsAddDialogOpen}>
+        <DialogContent
+          wrapperClassName="z-[10000]"
+          className="flex h-[calc(100vh-2rem)] max-h-[760px] w-[calc(100vw-2rem)] max-w-4xl flex-col overflow-hidden p-0 sm:h-[720px]"
+        >
+          <DialogTitle>Add {providerName} Skill</DialogTitle>
+          <div className="flex-shrink-0 border-b border-border/60 px-4 py-4">
+            <div className="flex items-start gap-3">
+              <div className="mt-0.5 flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-border/70 bg-muted/20 text-muted-foreground">
+                {addMode === 'hub' ? <Compass className="h-4 w-4" /> : <FileUp className="h-4 w-4" />}
+              </div>
+              <div className="min-w-0 flex-1">
+                <div className="text-base font-medium text-foreground">Add {providerName} Skill</div>
+                <div className="mt-1 text-sm text-muted-foreground">
+                  {selectedProvider === 'hermes'
+                    ? 'Upload a local skill or install one from the Hermes Skills Hub.'
+                    : 'Upload a markdown skill file or a complete skill folder.'}
                 </div>
               </div>
-            </div>
-
-            {queuedFiles.length > 0 && (
-              <div className="space-y-2">
-                <div className="text-sm font-medium text-foreground">Queued Files</div>
-                <div className="grid gap-2">
-                  {queuedFiles.map((queuedFile) => (
-                    <div
-                      key={queuedFile.id}
-                      className="flex flex-col gap-3 rounded-2xl border border-border/70 bg-background/70 px-3 py-3 sm:flex-row sm:items-center sm:justify-between sm:py-2"
-                    >
-                      <div className="min-w-0">
-                        <div className="truncate text-sm font-medium text-foreground">{queuedFile.name}</div>
-                        <div className="text-xs text-muted-foreground">
-                          {queuedFile.kind === 'folder'
-                            ? `${queuedFile.files.length} files`
-                            : 'Markdown file'}
-                          {' · '}
-                          {formatFileSize(queuedFile.size)}
-                        </div>
-                      </div>
-                      <Button
-                        type="button"
-                        variant="ghost"
-                        size="sm"
-                        className="w-full sm:w-auto"
-                        onClick={() => {
-                          setQueuedFiles((previous) => previous.filter((file) => file.id !== queuedFile.id));
-                        }}
-                      >
-                        Remove
-                      </Button>
-                    </div>
-                  ))}
-                </div>
-              </div>
-            )}
-
-            <div className="flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center">
               <Button
                 type="button"
-                onClick={() => void handleUploadInstall()}
-                disabled={isSubmitting}
-                className="w-full sm:w-auto"
+                variant="ghost"
+                size="sm"
+                className="h-8 w-8 p-0 text-muted-foreground hover:text-foreground"
+                aria-label="Close add skill dialog"
+                onClick={() => setIsAddDialogOpen(false)}
               >
-                {isSubmitting ? <Loader2 className="h-4 w-4 animate-spin" /> : <Upload className="h-4 w-4" />}
-                Install {queuedFiles.length > 0 ? `${queuedFiles.length} Skill${queuedFiles.length === 1 ? '' : 's'}` : 'Skills'}
+                <X className="h-4 w-4" />
               </Button>
-              <span className="text-xs text-muted-foreground">
-                Folder uploads keep the selected folder name; standalone files use the `name` in `SKILL.md`.
-              </span>
             </div>
+
+            {selectedProvider === 'hermes' && (
+              <div className="mt-4 inline-flex rounded-lg border border-border/70 bg-muted/20 p-1">
+                <Button
+                  type="button"
+                  variant={addMode === 'upload' ? 'secondary' : 'ghost'}
+                  size="sm"
+                  className="h-8 shadow-none"
+                  onClick={() => setAddMode('upload')}
+                >
+                  <FileUp className="h-4 w-4" />
+                  Upload
+                </Button>
+                <Button
+                  type="button"
+                  variant={addMode === 'hub' ? 'secondary' : 'ghost'}
+                  size="sm"
+                  className="h-8 shadow-none"
+                  onClick={() => setAddMode('hub')}
+                >
+                  <Compass className="h-4 w-4" />
+                  Skills Hub
+                </Button>
+              </div>
+            )}
           </div>
 
-          {(submitError || loadError) && (
-            <div className="rounded-2xl border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 dark:border-red-800/60 dark:bg-red-900/20 dark:text-red-200">
-              {submitError || loadError}
-            </div>
-          )}
+          <div className="min-h-0 flex-1 overflow-y-auto p-4">
+            {addMode === 'hub' && hermesHubPanel ? hermesHubPanel : uploadPanel}
+          </div>
 
-          {saveStatus === 'success' && (
-            <div className="inline-flex items-center gap-2 rounded-full border border-emerald-500/30 bg-emerald-500/10 px-3 py-1 text-xs font-medium text-emerald-700 dark:text-emerald-300">
-              <CheckCircle2 className="h-4 w-4" />
-              Skills saved successfully.
-            </div>
-          )}
-        </CardContent>
-      </Card>
+          <div className="min-h-14 flex-shrink-0 border-t border-border/60 px-4 py-3">
+            {(submitError || loadError || registryError || registryStatus || saveStatus === 'success') && (
+              <div className={cn(
+                'rounded-lg border px-3 py-2 text-sm',
+                submitError || loadError || registryError
+                  ? 'border-red-200 bg-red-50 text-red-700 dark:border-red-800/60 dark:bg-red-900/20 dark:text-red-200'
+                  : 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300',
+              )}>
+                {submitError || loadError || registryError || registryStatus || 'Skills saved successfully.'}
+              </div>
+            )}
+          </div>
+        </DialogContent>
+      </Dialog>
+
+      {saveStatus === 'success' && !isAddDialogOpen && (
+        <div className="inline-flex items-center gap-2 rounded-full border border-emerald-500/30 bg-emerald-500/10 px-3 py-1 text-xs font-medium text-emerald-700 dark:text-emerald-300">
+          <CheckCircle2 className="h-4 w-4" />
+          Skills saved successfully.
+        </div>
+      )}
 
       <Card className="min-w-0 border-border/70 bg-background/80 shadow-sm">
         <CardHeader className="border-b border-border/60">

src/i18n/locales/en/settings.json

@@ -3,6 +3,7 @@
   "tabs": {
     "account": "Account",
     "permissions": "Permissions",
+    "gateway": "Gateway",
     "mcpServers": "MCP Servers",
     "skills": "Skills",
     "appearance": "Appearance"

src/shared/view/ui/ActionMenu.tsx

@@ -0,0 +1,189 @@
+import * as React from 'react';
+import { ChevronDown, Loader2, type LucideIcon } from 'lucide-react';
+
+import { cn } from '../../../lib/utils';
+
+import { Button } from './Button';
+
+type ButtonVariant = 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
+type ButtonSize = 'default' | 'sm' | 'lg' | 'icon';
+
+export type ActionMenuItem = {
+  key: string;
+  label: string;
+  description?: string;
+  icon?: LucideIcon;
+  onSelect: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  isDanger?: boolean;
+  showDividerBefore?: boolean;
+};
+
+type ActionMenuProps = {
+  label: string;
+  items: ActionMenuItem[];
+  icon?: LucideIcon;
+  ariaLabel?: string;
+  align?: 'left' | 'right';
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  className?: string;
+  triggerClassName?: string;
+  disabled?: boolean;
+};
+
+export default function ActionMenu({
+  label,
+  items,
+  icon: TriggerIcon,
+  ariaLabel,
+  align = 'right',
+  variant = 'outline',
+  size = 'sm',
+  className,
+  triggerClassName,
+  disabled,
+}: ActionMenuProps) {
+  const [isOpen, setIsOpen] = React.useState(false);
+  const rootRef = React.useRef<HTMLDivElement | null>(null);
+  const triggerRef = React.useRef<HTMLButtonElement | null>(null);
+  const menuRef = React.useRef<HTMLDivElement | null>(null);
+  // Whether closing should move focus back to the trigger. Set for keyboard
+  // (Escape) and item selection, but left false for outside pointer clicks so
+  // focus is not stolen from wherever the user clicked.
+  const restoreFocusRef = React.useRef(false);
+  const wasOpenRef = React.useRef(false);
+  const menuId = React.useId();
+
+  React.useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    const closeOnOutsideClick = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (rootRef.current && !rootRef.current.contains(target)) {
+        setIsOpen(false);
+      }
+    };
+
+    const closeOnEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        restoreFocusRef.current = true;
+        setIsOpen(false);
+      }
+    };
+
+    document.addEventListener('mousedown', closeOnOutsideClick);
+    document.addEventListener('keydown', closeOnEscape);
+    return () => {
+      document.removeEventListener('mousedown', closeOnOutsideClick);
+      document.removeEventListener('keydown', closeOnEscape);
+    };
+  }, [isOpen]);
+
+  // Move focus into the menu on open and back to the trigger on a keyboard or
+  // selection close, so keyboard and screen-reader navigation match the menu role.
+  React.useEffect(() => {
+    if (isOpen) {
+      wasOpenRef.current = true;
+      const menu = menuRef.current;
+      const firstItem = menu?.querySelector<HTMLButtonElement>('[role="menuitem"]:not([disabled])');
+      (firstItem ?? menu)?.focus();
+      return;
+    }
+
+    if (wasOpenRef.current) {
+      wasOpenRef.current = false;
+      if (restoreFocusRef.current) {
+        triggerRef.current?.focus();
+      }
+      restoreFocusRef.current = false;
+    }
+  }, [isOpen]);
+
+  const runItem = (item: ActionMenuItem) => {
+    if (item.disabled || item.loading) {
+      return;
+    }
+
+    restoreFocusRef.current = true;
+    setIsOpen(false);
+    item.onSelect();
+  };
+
+  return (
+    <div ref={rootRef} className={cn('relative inline-flex', className)}>
+      <Button
+        ref={triggerRef}
+        type="button"
+        variant={variant}
+        size={size}
+        className={triggerClassName}
+        disabled={disabled}
+        aria-label={ariaLabel || label}
+        aria-haspopup="menu"
+        aria-expanded={isOpen}
+        aria-controls={isOpen ? menuId : undefined}
+        onClick={() => setIsOpen((current) => !current)}
+      >
+        {TriggerIcon && <TriggerIcon className="h-4 w-4" />}
+        <span>{label}</span>
+        <ChevronDown className={cn('h-4 w-4 transition-transform', isOpen && 'rotate-180')} />
+      </Button>
+
+      {isOpen && (
+        <div
+          ref={menuRef}
+          id={menuId}
+          role="menu"
+          tabIndex={-1}
+          className={cn(
+            'absolute top-full z-50 mt-2 min-w-[220px] rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-lg',
+            'animate-in fade-in-0 zoom-in-95',
+            align === 'right' ? 'right-0' : 'left-0',
+          )}
+        >
+          {items.map((item) => {
+            const Icon = item.icon;
+            return (
+              <React.Fragment key={item.key}>
+                {item.showDividerBefore && <div className="mx-2 my-1 h-px bg-border" />}
+                <button
+                  type="button"
+                  role="menuitem"
+                  disabled={item.disabled || item.loading}
+                  onClick={() => runItem(item)}
+                  className={cn(
+                    'flex w-full items-start gap-3 rounded-md px-3 py-2 text-left text-sm transition-colors',
+                    'focus:bg-accent focus:outline-none',
+                    item.disabled || item.loading
+                      ? 'cursor-not-allowed opacity-50'
+                      : item.isDanger
+                        ? 'text-red-600 hover:bg-red-50 dark:text-red-400 dark:hover:bg-red-950'
+                        : 'hover:bg-accent',
+                  )}
+                >
+                  {item.loading ? (
+                    <Loader2 className="mt-0.5 h-4 w-4 flex-shrink-0 animate-spin" />
+                  ) : (
+                    Icon && <Icon className="mt-0.5 h-4 w-4 flex-shrink-0" />
+                  )}
+                  <span className="min-w-0 flex-1">
+                    <span className="block font-medium leading-5">{item.label}</span>
+                    {item.description && (
+                      <span className="mt-0.5 block text-xs leading-4 text-muted-foreground">
+                        {item.description}
+                      </span>
+                    )}
+                  </span>
+                </button>
+              </React.Fragment>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

src/shared/view/ui/Dialog.tsx

@@ -92,12 +92,22 @@ DialogTrigger.displayName = 'DialogTrigger';
 interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement> {
   onEscapeKeyDown?: () => void;
   onPointerDownOutside?: () => void;
+  overlayClassName?: string;
+  wrapperClassName?: string;
 }
 
 const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
 const DialogContent = React.forwardRef<HTMLDivElement, DialogContentProps>(
-  ({ className, children, onEscapeKeyDown, onPointerDownOutside, ...props }, ref) => {
+  ({
+    className,
+    children,
+    onEscapeKeyDown,
+    onPointerDownOutside,
+    overlayClassName,
+    wrapperClassName,
+    ...props
+  }, ref) => {
     const { open, onOpenChange, triggerRef } = useDialog();
     const contentRef = React.useRef<HTMLDivElement | null>(null);
     const previousFocusRef = React.useRef<HTMLElement | null>(null);
@@ -171,10 +181,10 @@ const DialogContent = React.forwardRef<HTMLDivElement, DialogContentProps>(
     if (!open) return null;
 
     return createPortal(
-      <div className="fixed inset-0 z-50">
+      <div className={cn('fixed inset-0 z-50', wrapperClassName)}>
         {/* Overlay */}
         <div
-          className="fixed inset-0 animate-dialog-overlay-show bg-black/50 backdrop-blur-sm"
+          className={cn('fixed inset-0 animate-dialog-overlay-show bg-black/50 backdrop-blur-sm', overlayClassName)}
           onClick={() => {
             onPointerDownOutside?.();
             onOpenChange(false);

src/shared/view/ui/HelpTooltip.tsx

@@ -0,0 +1,32 @@
+import { CircleHelp } from 'lucide-react';
+
+import Tooltip from './Tooltip';
+
+type HelpTooltipProps = {
+  content: string;
+  label?: string;
+  position?: 'top' | 'bottom' | 'left' | 'right';
+};
+
+export default function HelpTooltip({
+  content,
+  label = 'Help',
+  position = 'top',
+}: HelpTooltipProps) {
+  return (
+    <Tooltip
+      content={content}
+      position={position}
+      className="max-w-[260px] whitespace-normal px-3 py-2 text-left text-xs leading-relaxed"
+    >
+      <span
+        aria-label={label}
+        className="inline-flex h-5 w-5 items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+        role="img"
+        title={content}
+      >
+        <CircleHelp className="h-4 w-4" />
+      </span>
+    </Tooltip>
+  );
+}

src/shared/view/ui/index.ts

@@ -1,4 +1,6 @@
 export { Alert, AlertTitle, AlertDescription, alertVariants } from './Alert';
+export { default as ActionMenu } from './ActionMenu';
+export type { ActionMenuItem } from './ActionMenu';
 export { Badge, badgeVariants } from './Badge';
 export { Button, buttonVariants } from './Button';
 export { Confirmation, ConfirmationTitle, ConfirmationRequest, ConfirmationAccepted, ConfirmationRejected, ConfirmationActions, ConfirmationAction } from './Confirmation';
@@ -7,6 +9,7 @@ export { Collapsible, CollapsibleTrigger, CollapsibleContent } from './Collapsib
 export { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator } from './Command';
 export { default as DarkModeToggle } from './DarkModeToggle';
 export { Dialog, DialogTrigger, DialogContent, DialogTitle } from './Dialog';
+export { default as HelpTooltip } from './HelpTooltip';
 export { Input } from './Input';
 export { ScrollArea } from './ScrollArea';
 export { Reasoning, ReasoningTrigger, ReasoningContent, useReasoning } from './Reasoning';

src/stores/useSessionStore.ts

@@ -166,6 +166,14 @@ function hasServerEchoForLocalUser(
   });
 }
 
+function assistantEchoFingerprint(message: NormalizedMessage): string | null {
+  const content = (message.content || '').trim();
+  if (!content) {
+    return null;
+  }
+  return content.replace(/\s+/g, '');
+}
+
 function compareMessagesChronologically(a: NormalizedMessage, b: NormalizedMessage): number {
   const timeA = readMessageTime(a) ?? 0;
   const timeB = readMessageTime(b) ?? 0;
@@ -248,7 +256,7 @@ function isAssistantTextEchoedInSameTurnOnServer(
   serverMessages: NormalizedMessage[],
   realtimeMessages: NormalizedMessage[],
 ): boolean {
-  const assistantText = (message.content || '').trim();
+  const assistantText = assistantEchoFingerprint(message);
   if (!assistantText) {
     return false;
   }
@@ -264,7 +272,7 @@ function isAssistantTextEchoedInSameTurnOnServer(
     .some((serverMessage) =>
       serverMessage.kind === 'text'
       && serverMessage.role === 'assistant'
-      && (serverMessage.content || '').trim() === assistantText,
+      && assistantEchoFingerprint(serverMessage) === assistantText,
     );
 }
 
@@ -281,9 +289,9 @@ function dedupeAdjacentAssistantEchoes(merged: NormalizedMessage[]): NormalizedM
     const prev = out[out.length - 1];
     if (prev) {
       if (prev.kind === 'stream_delta' && m.kind === 'text' && m.role === 'assistant') {
-        const ps = (prev.content || '').trim();
-        const ms = (m.content || '').trim();
-        if (ps.length > 0 && ps === ms) {
+        const ps = assistantEchoFingerprint(prev);
+        const ms = assistantEchoFingerprint(m);
+        if (ps && ps === ms) {
           out[out.length - 1] = m;
           continue;
         }
@@ -294,8 +302,12 @@ function dedupeAdjacentAssistantEchoes(merged: NormalizedMessage[]): NormalizedM
         && prev.role === 'assistant'
         && m.role === 'assistant'
       ) {
-        const ms = (m.content || '').trim();
-        if (ms.length > 0 && ms === (prev.content || '').trim()) {
+        const ps = assistantEchoFingerprint(prev);
+        const ms = assistantEchoFingerprint(m);
+        if (ms && ms === ps) {
+          if ((m.content || '').length > (prev.content || '').length) {
+            out[out.length - 1] = m;
+          }
           continue;
         }
       }

src/types/app.ts

@@ -1,4 +1,4 @@
-export type LLMProvider = 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode';
+export type LLMProvider = 'claude' | 'cursor' | 'codex' | 'gemini' | 'opencode' | 'hermes';
 
 export type ProviderModelOption = {
   value: string;