feat: introduce notification system and claude notifications (#450)

* feat: introduce notification system and claude notifications * fix(sw): prevent caching of API requests and WebSocket upgrades * default to false for webpush notifications and translations for the button * fix: notifications orchestrator and add a notification when first enabled * fix: remove unused state update and dependency in settings controller hook * fix: show notifications settings tab * fix: add notifications for response completion for all providers * feat: show session name in notification and don't reload tab on clicking --- the notification --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Haileyesus <something@gmail.com>
2026-03-14 18:37:22 +00:00 · 2026-03-13 16:59:09 +01:00
parent 6f6dacad5e
commit 45e71a0e73
36 changed files with 1629 additions and 69 deletions
--- a/server/claude-sdk.js
+++ b/server/claude-sdk.js
@@ -18,6 +18,12 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import os from 'os';
 import { CLAUDE_MODELS } from '../shared/modelConstants.js';
+import {
+  createNotificationEvent,
+  notifyRunFailed,
+  notifyRunStopped,
+  notifyUserIfEnabled
+} from './services/notification-orchestrator.js';

 const activeSessions = new Map();
 const pendingToolApprovals = new Map();
@@ -461,12 +467,20 @@ async function loadMcpConfig(cwd) {
 * @returns {Promise<void>}
 */
 async function queryClaudeSDK(command, options = {}, ws) {
-  const { sessionId } = options;
+  const { sessionId, sessionSummary } = options;
  let capturedSessionId = sessionId;
  let sessionCreatedSent = false;
  let tempImagePaths = [];
  let tempDir = null;

+  const emitNotification = (event) => {
+    notifyUserIfEnabled({
+      userId: ws?.userId || null,
+      writer: ws,
+      event
+    });
+  };
+
  try {
    // Map CLI options to SDK format
    const sdkOptions = mapCliOptionsToSDK(options);
@@ -483,6 +497,26 @@ async function queryClaudeSDK(command, options = {}, ws) {
    tempImagePaths = imageResult.tempImagePaths;
    tempDir = imageResult.tempDir;

+    sdkOptions.hooks = {
+      Notification: [{
+        matcher: '',
+        hooks: [async (input) => {
+          const message = typeof input?.message === 'string' ? input.message : 'Claude requires your attention.';
+          emitNotification(createNotificationEvent({
+            provider: 'claude',
+            sessionId: capturedSessionId || sessionId || null,
+            kind: 'action_required',
+            code: 'agent.notification',
+            meta: { message, sessionName: sessionSummary },
+            severity: 'warning',
+            requiresUserAction: true,
+            dedupeKey: `claude:hook:notification:${capturedSessionId || sessionId || 'none'}:${message}`
+          }));
+          return {};
+        }]
+      }]
+    };
+
    sdkOptions.canUseTool = async (toolName, input, context) => {
      const requiresInteraction = TOOLS_REQUIRING_INTERACTION.has(toolName);

@@ -514,6 +548,16 @@ async function queryClaudeSDK(command, options = {}, ws) {
        input,
        sessionId: capturedSessionId || sessionId || null
      });
+      emitNotification(createNotificationEvent({
+        provider: 'claude',
+        sessionId: capturedSessionId || sessionId || null,
+        kind: 'action_required',
+        code: 'permission.required',
+        meta: { toolName, sessionName: sessionSummary },
+        severity: 'warning',
+        requiresUserAction: true,
+        dedupeKey: `claude:permission:${capturedSessionId || sessionId || 'none'}:${requestId}`
+      }));

      const decision = await waitForToolApproval(requestId, {
        timeoutMs: requiresInteraction ? 0 : undefined,
@@ -560,10 +604,22 @@ async function queryClaudeSDK(command, options = {}, ws) {
    const prevStreamTimeout = process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT;
    process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT = '300000';

-    const queryInstance = query({
-      prompt: finalCommand,
-      options: sdkOptions
-    });
+    let queryInstance;
+    try {
+      queryInstance = query({
+        prompt: finalCommand,
+        options: sdkOptions
+      });
+    } catch (hookError) {
+      // Older/newer SDK versions may not accept hook shapes yet.
+      // Keep notification behavior operational via runtime events even if hook registration fails.
+      console.warn('Failed to initialize Claude query with hooks, retrying without hooks:', hookError?.message || hookError);
+      delete sdkOptions.hooks;
+      queryInstance = query({
+        prompt: finalCommand,
+        options: sdkOptions
+      });
+    }

    // Restore immediately — Query constructor already captured the value
    if (prevStreamTimeout !== undefined) {
@@ -647,6 +703,13 @@ async function queryClaudeSDK(command, options = {}, ws) {
      exitCode: 0,
      isNewSession: !sessionId && !!command
    });
+    notifyRunStopped({
+      userId: ws?.userId || null,
+      provider: 'claude',
+      sessionId: capturedSessionId || sessionId || null,
+      sessionName: sessionSummary,
+      stopReason: 'completed'
+    });
    console.log('claude-complete event sent');

  } catch (error) {
@@ -666,6 +729,13 @@ async function queryClaudeSDK(command, options = {}, ws) {
      error: error.message,
      sessionId: capturedSessionId || sessionId || null
    });
+    notifyRunFailed({
+      userId: ws?.userId || null,
+      provider: 'claude',
+      sessionId: capturedSessionId || sessionId || null,
+      sessionName: sessionSummary,
+      error
+    });

    throw error;
  }
--- a/server/cursor-cli.js
+++ b/server/cursor-cli.js
@@ -1,5 +1,6 @@
 import { spawn } from 'child_process';
 import crossSpawn from 'cross-spawn';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';

 // Use cross-spawn on Windows for better command execution
 const spawnFunction = process.platform === 'win32' ? crossSpawn : spawn;
@@ -23,7 +24,7 @@ function isWorkspaceTrustPrompt(text = '') {

 async function spawnCursor(command, options = {}, ws) {
  return new Promise(async (resolve, reject) => {
-    const { sessionId, projectPath, cwd, resume, toolsSettings, skipPermissions, model } = options;
+    const { sessionId, projectPath, cwd, resume, toolsSettings, skipPermissions, model, sessionSummary } = options;
    let capturedSessionId = sessionId; // Track session ID throughout the process
    let sessionCreatedSent = false; // Track if we've already sent session-created event
    let hasRetriedWithTrust = false;
@@ -81,6 +82,35 @@ async function spawnCursor(command, options = {}, ws) {
      const isTrustRetry = runReason === 'trust-retry';
      let runSawWorkspaceTrustPrompt = false;
      let stdoutLineBuffer = '';
+      let terminalNotificationSent = false;
+
+      const notifyTerminalState = ({ code = null, error = null } = {}) => {
+        if (terminalNotificationSent) {
+          return;
+        }
+
+        terminalNotificationSent = true;
+
+        const finalSessionId = capturedSessionId || sessionId || processKey;
+        if (code === 0 && !error) {
+          notifyRunStopped({
+            userId: ws?.userId || null,
+            provider: 'cursor',
+            sessionId: finalSessionId,
+            sessionName: sessionSummary,
+            stopReason: 'completed'
+          });
+          return;
+        }
+
+        notifyRunFailed({
+          userId: ws?.userId || null,
+          provider: 'cursor',
+          sessionId: finalSessionId,
+          sessionName: sessionSummary,
+          error: error || `Cursor CLI exited with code ${code}`
+        });
+      };

      if (isTrustRetry) {
        console.log('Retrying Cursor CLI with --trust after workspace trust prompt');
@@ -255,7 +285,8 @@ async function spawnCursor(command, options = {}, ws) {
        ws.send({
          type: 'cursor-error',
          error: stderrText,
-          sessionId: capturedSessionId || sessionId || null
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'cursor'
        });
      });

@@ -287,12 +318,15 @@ async function spawnCursor(command, options = {}, ws) {
          type: 'claude-complete',
          sessionId: finalSessionId,
          exitCode: code,
+          provider: 'cursor',
          isNewSession: !sessionId && !!command // Flag to indicate this was a new session
        });

        if (code === 0) {
+          notifyTerminalState({ code });
          settleOnce(() => resolve());
        } else {
+          notifyTerminalState({ code });
          settleOnce(() => reject(new Error(`Cursor CLI exited with code ${code}`)));
        }
      });
@@ -308,8 +342,10 @@ async function spawnCursor(command, options = {}, ws) {
        ws.send({
          type: 'cursor-error',
          error: error.message,
-          sessionId: capturedSessionId || sessionId || null
+          sessionId: capturedSessionId || sessionId || null,
+          provider: 'cursor'
        });
+        notifyTerminalState({ error });

        settleOnce(() => reject(error));
      });
--- a/server/database/db.js
+++ b/server/database/db.js
@@ -100,6 +100,35 @@ const runMigrations = () => {
      db.exec('ALTER TABLE users ADD COLUMN has_completed_onboarding BOOLEAN DEFAULT 0');
    }

+    db.exec(`
+      CREATE TABLE IF NOT EXISTS user_notification_preferences (
+        user_id INTEGER PRIMARY KEY,
+        preferences_json TEXT NOT NULL,
+        updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+      )
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS vapid_keys (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        public_key TEXT NOT NULL,
+        private_key TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      )
+    `);
+
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS push_subscriptions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id INTEGER NOT NULL,
+        endpoint TEXT NOT NULL UNIQUE,
+        keys_p256dh TEXT NOT NULL,
+        keys_auth TEXT NOT NULL,
+        created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+        FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+      )
+    `);
    // Create app_config table if it doesn't exist (for existing installations)
    db.exec(`CREATE TABLE IF NOT EXISTS app_config (
      key TEXT PRIMARY KEY,
@@ -376,6 +405,116 @@ const credentialsDb = {
  }
 };

+const DEFAULT_NOTIFICATION_PREFERENCES = {
+  channels: {
+    inApp: false,
+    webPush: false
+  },
+  events: {
+    actionRequired: true,
+    stop: true,
+    error: true
+  }
+};
+
+const normalizeNotificationPreferences = (value) => {
+  const source = value && typeof value === 'object' ? value : {};
+
+  return {
+    channels: {
+      inApp: source.channels?.inApp === true,
+      webPush: source.channels?.webPush === true
+    },
+    events: {
+      actionRequired: source.events?.actionRequired !== false,
+      stop: source.events?.stop !== false,
+      error: source.events?.error !== false
+    }
+  };
+};
+
+const notificationPreferencesDb = {
+  getPreferences: (userId) => {
+    try {
+      const row = db.prepare('SELECT preferences_json FROM user_notification_preferences WHERE user_id = ?').get(userId);
+      if (!row) {
+        const defaults = normalizeNotificationPreferences(DEFAULT_NOTIFICATION_PREFERENCES);
+        db.prepare(
+          'INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at) VALUES (?, ?, CURRENT_TIMESTAMP)'
+        ).run(userId, JSON.stringify(defaults));
+        return defaults;
+      }
+
+      let parsed;
+      try {
+        parsed = JSON.parse(row.preferences_json);
+      } catch {
+        parsed = DEFAULT_NOTIFICATION_PREFERENCES;
+      }
+      return normalizeNotificationPreferences(parsed);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  updatePreferences: (userId, preferences) => {
+    try {
+      const normalized = normalizeNotificationPreferences(preferences);
+      db.prepare(
+        `INSERT INTO user_notification_preferences (user_id, preferences_json, updated_at)
+         VALUES (?, ?, CURRENT_TIMESTAMP)
+         ON CONFLICT(user_id) DO UPDATE SET
+           preferences_json = excluded.preferences_json,
+           updated_at = CURRENT_TIMESTAMP`
+      ).run(userId, JSON.stringify(normalized));
+      return normalized;
+    } catch (err) {
+      throw err;
+    }
+  }
+};
+
+const pushSubscriptionsDb = {
+  saveSubscription: (userId, endpoint, keysP256dh, keysAuth) => {
+    try {
+      db.prepare(
+        `INSERT INTO push_subscriptions (user_id, endpoint, keys_p256dh, keys_auth)
+         VALUES (?, ?, ?, ?)
+         ON CONFLICT(endpoint) DO UPDATE SET
+           user_id = excluded.user_id,
+           keys_p256dh = excluded.keys_p256dh,
+           keys_auth = excluded.keys_auth`
+      ).run(userId, endpoint, keysP256dh, keysAuth);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  getSubscriptions: (userId) => {
+    try {
+      return db.prepare('SELECT endpoint, keys_p256dh, keys_auth FROM push_subscriptions WHERE user_id = ?').all(userId);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  removeSubscription: (endpoint) => {
+    try {
+      db.prepare('DELETE FROM push_subscriptions WHERE endpoint = ?').run(endpoint);
+    } catch (err) {
+      throw err;
+    }
+  },
+
+  removeAllForUser: (userId) => {
+    try {
+      db.prepare('DELETE FROM push_subscriptions WHERE user_id = ?').run(userId);
+    } catch (err) {
+      throw err;
+    }
+  }
+};
+
 // Session custom names database operations
 const sessionNamesDb = {
  // Set (insert or update) a custom session name
@@ -482,8 +621,10 @@ export {
  userDb,
  apiKeysDb,
  credentialsDb,
+  notificationPreferencesDb,
+  pushSubscriptionsDb,
  sessionNamesDb,
  applyCustomSessionNames,
  appConfigDb,
  githubTokensDb // Backward compatibility
-};
+};
--- a/server/database/init.sql
+++ b/server/database/init.sql
@@ -51,6 +51,33 @@ CREATE INDEX IF NOT EXISTS idx_user_credentials_user_id ON user_credentials(user
 CREATE INDEX IF NOT EXISTS idx_user_credentials_type ON user_credentials(credential_type);
 CREATE INDEX IF NOT EXISTS idx_user_credentials_active ON user_credentials(is_active);

+-- User notification preferences (backend-owned, provider-agnostic)
+CREATE TABLE IF NOT EXISTS user_notification_preferences (
+    user_id INTEGER PRIMARY KEY,
+    preferences_json TEXT NOT NULL,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+-- VAPID key pair for Web Push notifications
+CREATE TABLE IF NOT EXISTS vapid_keys (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    public_key TEXT NOT NULL,
+    private_key TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Browser push subscriptions
+CREATE TABLE IF NOT EXISTS push_subscriptions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id INTEGER NOT NULL,
+    endpoint TEXT NOT NULL UNIQUE,
+    keys_p256dh TEXT NOT NULL,
+    keys_auth TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
 -- Session custom names (provider-agnostic display name overrides)
 CREATE TABLE IF NOT EXISTS session_names (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -69,4 +96,4 @@ CREATE TABLE IF NOT EXISTS app_config (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
-);
+);
--- a/server/gemini-cli.js
+++ b/server/gemini-cli.js
@@ -9,11 +9,12 @@ import os from 'os';
 import { getSessions, getSessionMessages } from './projects.js';
 import sessionManager from './sessionManager.js';
 import GeminiResponseHandler from './gemini-response-handler.js';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';

 let activeGeminiProcesses = new Map(); // Track active processes by session ID

 async function spawnGemini(command, options = {}, ws) {
-    const { sessionId, projectPath, cwd, resume, toolsSettings, permissionMode, images } = options;
+    const { sessionId, projectPath, cwd, resume, toolsSettings, permissionMode, images, sessionSummary } = options;
    let capturedSessionId = sessionId; // Track session ID throughout the process
    let sessionCreatedSent = false; // Track if we've already sent session-created event
    let assistantBlocks = []; // Accumulate the full response blocks including tools
@@ -172,6 +173,36 @@ async function spawnGemini(command, options = {}, ws) {
            stdio: ['pipe', 'pipe', 'pipe'],
            env: { ...process.env } // Inherit all environment variables
        });
+        let terminalNotificationSent = false;
+        let terminalFailureReason = null;
+
+        const notifyTerminalState = ({ code = null, error = null } = {}) => {
+            if (terminalNotificationSent) {
+                return;
+            }
+
+            terminalNotificationSent = true;
+
+            const finalSessionId = capturedSessionId || sessionId || processKey;
+            if (code === 0 && !error) {
+                notifyRunStopped({
+                    userId: ws?.userId || null,
+                    provider: 'gemini',
+                    sessionId: finalSessionId,
+                    sessionName: sessionSummary,
+                    stopReason: 'completed'
+                });
+                return;
+            }
+
+            notifyRunFailed({
+                userId: ws?.userId || null,
+                provider: 'gemini',
+                sessionId: finalSessionId,
+                sessionName: sessionSummary,
+                error: error || terminalFailureReason || `Gemini CLI exited with code ${code}`
+            });
+        };

        // Attach temp file info to process for cleanup later
        geminiProcess.tempImagePaths = tempImagePaths;
@@ -196,10 +227,12 @@ async function spawnGemini(command, options = {}, ws) {
            if (timeout) clearTimeout(timeout);
            timeout = setTimeout(() => {
                const socketSessionId = typeof ws.getSessionId === 'function' ? ws.getSessionId() : (capturedSessionId || sessionId || processKey);
+                terminalFailureReason = `Gemini CLI timeout - no response received for ${timeoutMs / 1000} seconds`;
                ws.send({
                    type: 'gemini-error',
                    sessionId: socketSessionId,
-                    error: `Gemini CLI timeout - no response received for ${timeoutMs / 1000} seconds`
+                    error: terminalFailureReason,
+                    provider: 'gemini'
                });
                try {
                    geminiProcess.kill('SIGTERM');
@@ -340,7 +373,8 @@ async function spawnGemini(command, options = {}, ws) {
            ws.send({
                type: 'gemini-error',
                sessionId: socketSessionId,
-                error: errorMsg
+                error: errorMsg,
+                provider: 'gemini'
            });
        });

@@ -367,6 +401,7 @@ async function spawnGemini(command, options = {}, ws) {
                type: 'claude-complete', // Use claude-complete for compatibility with UI
                sessionId: finalSessionId,
                exitCode: code,
+                provider: 'gemini',
                isNewSession: !sessionId && !!command // Flag to indicate this was a new session
            });

@@ -381,8 +416,13 @@ async function spawnGemini(command, options = {}, ws) {
            }

            if (code === 0) {
+                notifyTerminalState({ code });
                resolve();
            } else {
+                notifyTerminalState({
+                    code,
+                    error: code === null ? 'Gemini CLI process was terminated or timed out' : null
+                });
                reject(new Error(code === null ? 'Gemini CLI process was terminated or timed out' : `Gemini CLI exited with code ${code}`));
            }
        });
@@ -397,8 +437,10 @@ async function spawnGemini(command, options = {}, ws) {
            ws.send({
                type: 'gemini-error',
                sessionId: errorSessionId,
-                error: error.message
+                error: error.message,
+                provider: 'gemini'
            });
+            notifyTerminalState({ error });

            reject(error);
        });
--- a/server/index.js
+++ b/server/index.js
@@ -67,6 +67,7 @@ import geminiRoutes from './routes/gemini.js';
 import pluginsRoutes from './routes/plugins.js';
 import { startEnabledPluginServers, stopAllPlugins } from './utils/plugin-process-manager.js';
 import { initializeDatabase, sessionNamesDb, applyCustomSessionNames } from './database/db.js';
+import { configureWebPush } from './services/vapid-keys.js';
 import { validateApiKey, authenticateToken, authenticateWebSocket } from './middleware/auth.js';
 import { IS_PLATFORM } from './constants/config.js';

@@ -1406,7 +1407,7 @@ wss.on('connection', (ws, request) => {
    if (pathname === '/shell') {
        handleShellConnection(ws);
    } else if (pathname === '/ws') {
-        handleChatConnection(ws);
+        handleChatConnection(ws, request);
    } else {
        console.log('[WARN] Unknown WebSocket path:', pathname);
        ws.close();
@@ -1417,9 +1418,10 @@ wss.on('connection', (ws, request) => {
 * WebSocket Writer - Wrapper for WebSocket to match SSEStreamWriter interface
 */
 class WebSocketWriter {
-    constructor(ws) {
+    constructor(ws, userId = null) {
        this.ws = ws;
        this.sessionId = null;
+        this.userId = userId;
        this.isWebSocketWriter = true;  // Marker for transport detection
    }

@@ -1444,14 +1446,14 @@ class WebSocketWriter {
 }

 // Handle chat WebSocket connections
-function handleChatConnection(ws) {
+function handleChatConnection(ws, request) {
    console.log('[INFO] Chat WebSocket connected');

    // Add to connected clients for project updates
    connectedClients.add(ws);

    // Wrap WebSocket with writer for consistent interface with SSEStreamWriter
-    const writer = new WebSocketWriter(ws);
+    const writer = new WebSocketWriter(ws, request?.user?.id ?? request?.user?.userId ?? null);

    ws.on('message', async (message) => {
        try {
@@ -2500,6 +2502,9 @@ async function startServer() {
        // Initialize authentication database
        await initializeDatabase();

+        // Configure Web Push (VAPID keys)
+        configureWebPush();
+
        // Check if running in production mode (dist folder exists)
        const distIndexPath = path.join(__dirname, '../dist/index.html');
        const isProduction = fs.existsSync(distIndexPath);
--- a/server/middleware/auth.js
+++ b/server/middleware/auth.js
@@ -95,7 +95,7 @@ const authenticateWebSocket = (token) => {
    try {
      const user = userDb.getFirstUser();
      if (user) {
-        return { userId: user.id, username: user.username };
+        return { id: user.id, userId: user.id, username: user.username };
      }
      return null;
    } catch (error) {
@@ -129,4 +129,4 @@ export {
  generateToken,
  authenticateWebSocket,
  JWT_SECRET
-};
+};
--- a/server/openai-codex.js
+++ b/server/openai-codex.js
@@ -14,6 +14,7 @@
 */

 import { Codex } from '@openai/codex-sdk';
+import { notifyRunFailed, notifyRunStopped } from './services/notification-orchestrator.js';

 // Track active sessions
 const activeCodexSessions = new Map();
@@ -191,6 +192,7 @@ function mapPermissionModeToCodexOptions(permissionMode) {
 export async function queryCodex(command, options = {}, ws) {
  const {
    sessionId,
+    sessionSummary,
    cwd,
    projectPath,
    model,
@@ -203,6 +205,7 @@ export async function queryCodex(command, options = {}, ws) {
  let codex;
  let thread;
  let currentSessionId = sessionId;
+  let terminalFailure = null;
  const abortController = new AbortController();

  try {
@@ -268,6 +271,17 @@ export async function queryCodex(command, options = {}, ws) {
        sessionId: currentSessionId
      });

+      if (event.type === 'turn.failed' && !terminalFailure) {
+        terminalFailure = event.error || new Error('Turn failed');
+        notifyRunFailed({
+          userId: ws?.userId || null,
+          provider: 'codex',
+          sessionId: currentSessionId,
+          sessionName: sessionSummary,
+          error: terminalFailure
+        });
+      }
+
      // Extract and send token usage if available (normalized to match Claude format)
      if (event.type === 'turn.completed' && event.usage) {
        const totalTokens = (event.usage.input_tokens || 0) + (event.usage.output_tokens || 0);
@@ -283,11 +297,21 @@ export async function queryCodex(command, options = {}, ws) {
    }

    // Send completion event
-    sendMessage(ws, {
-      type: 'codex-complete',
-      sessionId: currentSessionId,
-      actualSessionId: thread.id
-    });
+    if (!terminalFailure) {
+      sendMessage(ws, {
+        type: 'codex-complete',
+        sessionId: currentSessionId,
+        actualSessionId: thread.id,
+        provider: 'codex'
+      });
+      notifyRunStopped({
+        userId: ws?.userId || null,
+        provider: 'codex',
+        sessionId: currentSessionId,
+        sessionName: sessionSummary,
+        stopReason: 'completed'
+      });
+    }

  } catch (error) {
    const session = currentSessionId ? activeCodexSessions.get(currentSessionId) : null;
@@ -301,8 +325,18 @@ export async function queryCodex(command, options = {}, ws) {
      sendMessage(ws, {
        type: 'codex-error',
        error: error.message,
-        sessionId: currentSessionId
+        sessionId: currentSessionId,
+        provider: 'codex'
      });
+      if (!terminalFailure) {
+        notifyRunFailed({
+          userId: ws?.userId || null,
+          provider: 'codex',
+          sessionId: currentSessionId,
+          sessionName: sessionSummary,
+          error
+        });
+      }
    }

  } finally {
--- a/server/routes/agent.js
+++ b/server/routes/agent.js
@@ -450,9 +450,10 @@ async function cleanupProject(projectPath, sessionId = null) {
 * SSE Stream Writer - Adapts SDK/CLI output to Server-Sent Events
 */
 class SSEStreamWriter {
-  constructor(res) {
+  constructor(res, userId = null) {
    this.res = res;
    this.sessionId = null;
+    this.userId = userId;
    this.isSSEStreamWriter = true;  // Marker for transport detection
  }

@@ -485,9 +486,10 @@ class SSEStreamWriter {
 * Non-streaming response collector
 */
 class ResponseCollector {
-  constructor() {
+  constructor(userId = null) {
    this.messages = [];
    this.sessionId = null;
+    this.userId = userId;
  }

  send(data) {
@@ -920,7 +922,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
      res.setHeader('Connection', 'keep-alive');
      res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering

-      writer = new SSEStreamWriter(res);
+      writer = new SSEStreamWriter(res, req.user.id);

      // Send initial status
      writer.send({
@@ -930,7 +932,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
      });
    } else {
      // Non-streaming mode: collect messages
-      writer = new ResponseCollector();
+      writer = new ResponseCollector(req.user.id);

      // Collect initial status message
      writer.send({
@@ -1219,7 +1221,7 @@ router.post('/', validateExternalApiKey, async (req, res) => {
        res.setHeader('Cache-Control', 'no-cache');
        res.setHeader('Connection', 'keep-alive');
        res.setHeader('X-Accel-Buffering', 'no');
-        writer = new SSEStreamWriter(res);
+        writer = new SSEStreamWriter(res, req.user.id);
      }

      if (!res.writableEnded) {
--- a/server/routes/settings.js
+++ b/server/routes/settings.js
@@ -1,5 +1,7 @@
 import express from 'express';
-import { apiKeysDb, credentialsDb } from '../database/db.js';
+import { apiKeysDb, credentialsDb, notificationPreferencesDb, pushSubscriptionsDb } from '../database/db.js';
+import { getPublicKey } from '../services/vapid-keys.js';
+import { createNotificationEvent, notifyUserIfEnabled } from '../services/notification-orchestrator.js';

 const router = express.Router();

@@ -175,4 +177,100 @@ router.patch('/credentials/:credentialId/toggle', async (req, res) => {
  }
 });

+// ===============================
+// Notification Preferences
+// ===============================
+
+router.get('/notification-preferences', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.getPreferences(req.user.id);
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error fetching notification preferences:', error);
+    res.status(500).json({ error: 'Failed to fetch notification preferences' });
+  }
+});
+
+router.put('/notification-preferences', async (req, res) => {
+  try {
+    const preferences = notificationPreferencesDb.updatePreferences(req.user.id, req.body || {});
+    res.json({ success: true, preferences });
+  } catch (error) {
+    console.error('Error saving notification preferences:', error);
+    res.status(500).json({ error: 'Failed to save notification preferences' });
+  }
+});
+
+// ===============================
+// Push Subscription Management
+// ===============================
+
+router.get('/push/vapid-public-key', async (req, res) => {
+  try {
+    const publicKey = getPublicKey();
+    res.json({ publicKey });
+  } catch (error) {
+    console.error('Error fetching VAPID public key:', error);
+    res.status(500).json({ error: 'Failed to fetch VAPID public key' });
+  }
+});
+
+router.post('/push/subscribe', async (req, res) => {
+  try {
+    const { endpoint, keys } = req.body;
+    if (!endpoint || !keys?.p256dh || !keys?.auth) {
+      return res.status(400).json({ error: 'Missing subscription fields' });
+    }
+    pushSubscriptionsDb.saveSubscription(req.user.id, endpoint, keys.p256dh, keys.auth);
+
+    // Enable webPush in preferences so the confirmation goes through the full pipeline
+    const currentPrefs = notificationPreferencesDb.getPreferences(req.user.id);
+    if (!currentPrefs?.channels?.webPush) {
+      notificationPreferencesDb.updatePreferences(req.user.id, {
+        ...currentPrefs,
+        channels: { ...currentPrefs?.channels, webPush: true },
+      });
+    }
+
+    res.json({ success: true });
+
+    // Send a confirmation push through the full notification pipeline
+    const event = createNotificationEvent({
+      provider: 'system',
+      kind: 'info',
+      code: 'push.enabled',
+      meta: { message: 'Push notifications are now enabled!' },
+      severity: 'info'
+    });
+    notifyUserIfEnabled({ userId: req.user.id, event });
+  } catch (error) {
+    console.error('Error saving push subscription:', error);
+    res.status(500).json({ error: 'Failed to save push subscription' });
+  }
+});
+
+router.post('/push/unsubscribe', async (req, res) => {
+  try {
+    const { endpoint } = req.body;
+    if (!endpoint) {
+      return res.status(400).json({ error: 'Missing endpoint' });
+    }
+    pushSubscriptionsDb.removeSubscription(endpoint);
+
+    // Disable webPush in preferences to match subscription state
+    const currentPrefs = notificationPreferencesDb.getPreferences(req.user.id);
+    if (currentPrefs?.channels?.webPush) {
+      notificationPreferencesDb.updatePreferences(req.user.id, {
+        ...currentPrefs,
+        channels: { ...currentPrefs.channels, webPush: false },
+      });
+    }
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Error removing push subscription:', error);
+    res.status(500).json({ error: 'Failed to remove push subscription' });
+  }
+});
+
 export default router;
--- a/server/services/notification-orchestrator.js
+++ b/server/services/notification-orchestrator.js
@@ -0,0 +1,227 @@
+import webPush from 'web-push';
+import { notificationPreferencesDb, pushSubscriptionsDb, sessionNamesDb } from '../database/db.js';
+
+const KIND_TO_PREF_KEY = {
+  action_required: 'actionRequired',
+  stop: 'stop',
+  error: 'error'
+};
+
+const PROVIDER_LABELS = {
+  claude: 'Claude',
+  cursor: 'Cursor',
+  codex: 'Codex',
+  gemini: 'Gemini',
+  system: 'System'
+};
+
+const recentEventKeys = new Map();
+const DEDUPE_WINDOW_MS = 20000;
+
+const cleanupOldEventKeys = () => {
+  const now = Date.now();
+  for (const [key, timestamp] of recentEventKeys.entries()) {
+    if (now - timestamp > DEDUPE_WINDOW_MS) {
+      recentEventKeys.delete(key);
+    }
+  }
+};
+
+function shouldSendPush(preferences, event) {
+  const webPushEnabled = Boolean(preferences?.channels?.webPush);
+  const prefEventKey = KIND_TO_PREF_KEY[event.kind];
+  const eventEnabled = prefEventKey ? Boolean(preferences?.events?.[prefEventKey]) : true;
+
+  return webPushEnabled && eventEnabled;
+}
+
+function isDuplicate(event) {
+  cleanupOldEventKeys();
+  const key = event.dedupeKey || `${event.provider}:${event.kind || 'info'}:${event.code || 'generic'}:${event.sessionId || 'none'}`;
+  if (recentEventKeys.has(key)) {
+    return true;
+  }
+  recentEventKeys.set(key, Date.now());
+  return false;
+}
+
+function createNotificationEvent({
+  provider,
+  sessionId = null,
+  kind = 'info',
+  code = 'generic.info',
+  meta = {},
+  severity = 'info',
+  dedupeKey = null,
+  requiresUserAction = false
+}) {
+  return {
+    provider,
+    sessionId,
+    kind,
+    code,
+    meta,
+    severity,
+    requiresUserAction,
+    dedupeKey,
+    createdAt: new Date().toISOString()
+  };
+}
+
+function normalizeErrorMessage(error) {
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error && typeof error.message === 'string') {
+    return error.message;
+  }
+
+  if (error == null) {
+    return 'Unknown error';
+  }
+
+  return String(error);
+}
+
+function normalizeSessionName(sessionName) {
+  if (typeof sessionName !== 'string') {
+    return null;
+  }
+
+  const normalized = sessionName.replace(/\s+/g, ' ').trim();
+  if (!normalized) {
+    return null;
+  }
+
+  return normalized.length > 80 ? `${normalized.slice(0, 77)}...` : normalized;
+}
+
+function resolveSessionName(event) {
+  const explicitSessionName = normalizeSessionName(event.meta?.sessionName);
+  if (explicitSessionName) {
+    return explicitSessionName;
+  }
+
+  if (!event.sessionId || !event.provider) {
+    return null;
+  }
+
+  return normalizeSessionName(sessionNamesDb.getName(event.sessionId, event.provider));
+}
+
+function buildPushBody(event) {
+  const CODE_MAP = {
+    'permission.required': event.meta?.toolName
+      ? `Action Required: Tool "${event.meta.toolName}" needs approval`
+      : 'Action Required: A tool needs your approval',
+    'run.stopped': event.meta?.stopReason || 'Run Stopped: The run has stopped',
+    'run.failed': event.meta?.error ? `Run Failed: ${event.meta.error}` : 'Run Failed: The run encountered an error',
+    'agent.notification': event.meta?.message ? String(event.meta.message) : 'You have a new notification',
+    'push.enabled': 'Push notifications are now enabled!'
+  };
+  const providerLabel = PROVIDER_LABELS[event.provider] || 'Assistant';
+  const sessionName = resolveSessionName(event);
+  const message = CODE_MAP[event.code] || 'You have a new notification';
+
+  return {
+    title: sessionName || 'Claude Code UI',
+    body: `${providerLabel}: ${message}`,
+    data: {
+      sessionId: event.sessionId || null,
+      code: event.code,
+      provider: event.provider || null,
+      sessionName,
+      tag: `${event.provider || 'assistant'}:${event.sessionId || 'none'}:${event.code}`
+    }
+  };
+}
+
+async function sendWebPush(userId, event) {
+  const subscriptions = pushSubscriptionsDb.getSubscriptions(userId);
+  if (!subscriptions.length) return;
+
+  const payload = JSON.stringify(buildPushBody(event));
+
+  const results = await Promise.allSettled(
+    subscriptions.map((sub) =>
+      webPush.sendNotification(
+        {
+          endpoint: sub.endpoint,
+          keys: {
+            p256dh: sub.keys_p256dh,
+            auth: sub.keys_auth
+          }
+        },
+        payload
+      )
+    )
+  );
+
+  // Clean up gone subscriptions (410 Gone or 404)
+  results.forEach((result, index) => {
+    if (result.status === 'rejected') {
+      const statusCode = result.reason?.statusCode;
+      if (statusCode === 410 || statusCode === 404) {
+        pushSubscriptionsDb.removeSubscription(subscriptions[index].endpoint);
+      }
+    }
+  });
+}
+
+function notifyUserIfEnabled({ userId, event }) {
+  if (!userId || !event) {
+    return;
+  }
+
+  const preferences = notificationPreferencesDb.getPreferences(userId);
+  if (!shouldSendPush(preferences, event)) {
+    return;
+  }
+  if (isDuplicate(event)) {
+    return;
+  }
+
+  sendWebPush(userId, event).catch((err) => {
+    console.error('Web push send error:', err);
+  });
+}
+
+function notifyRunStopped({ userId, provider, sessionId = null, stopReason = 'completed', sessionName = null }) {
+  notifyUserIfEnabled({
+    userId,
+    event: createNotificationEvent({
+      provider,
+      sessionId,
+      kind: 'stop',
+      code: 'run.stopped',
+      meta: { stopReason, sessionName },
+      severity: 'info',
+      dedupeKey: `${provider}:run:stop:${sessionId || 'none'}:${stopReason}`
+    })
+  });
+}
+
+function notifyRunFailed({ userId, provider, sessionId = null, error, sessionName = null }) {
+  const errorMessage = normalizeErrorMessage(error);
+
+  notifyUserIfEnabled({
+    userId,
+    event: createNotificationEvent({
+      provider,
+      sessionId,
+      kind: 'error',
+      code: 'run.failed',
+      meta: { error: errorMessage, sessionName },
+      severity: 'error',
+      dedupeKey: `${provider}:run:error:${sessionId || 'none'}:${errorMessage}`
+    })
+  });
+}
+
+export {
+  createNotificationEvent,
+  notifyUserIfEnabled,
+  notifyRunStopped,
+  notifyRunFailed
+};
--- a/server/services/vapid-keys.js
+++ b/server/services/vapid-keys.js
@@ -0,0 +1,35 @@
+import webPush from 'web-push';
+import { db } from '../database/db.js';
+
+let cachedKeys = null;
+
+function ensureVapidKeys() {
+  if (cachedKeys) return cachedKeys;
+
+  const row = db.prepare('SELECT public_key, private_key FROM vapid_keys ORDER BY id DESC LIMIT 1').get();
+  if (row) {
+    cachedKeys = { publicKey: row.public_key, privateKey: row.private_key };
+    return cachedKeys;
+  }
+
+  const keys = webPush.generateVAPIDKeys();
+  db.prepare('INSERT INTO vapid_keys (public_key, private_key) VALUES (?, ?)').run(keys.publicKey, keys.privateKey);
+  cachedKeys = keys;
+  return cachedKeys;
+}
+
+function getPublicKey() {
+  return ensureVapidKeys().publicKey;
+}
+
+function configureWebPush() {
+  const keys = ensureVapidKeys();
+  webPush.setVapidDetails(
+    'mailto:noreply@claudecodeui.local',
+    keys.publicKey,
+    keys.privateKey
+  );
+  console.log('Web Push notifications configured');
+}
+
+export { ensureVapidKeys, getPublicKey, configureWebPush };