feat: add OS notifications for completed/failed tasks

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;

apps/web/src/components/settings/SettingsPanels.tsx

@@ -9,8 +9,9 @@ import {
  type ProviderInstanceId,
  type ScopedThreadRef,
 } from "@t3tools/contracts";
+import { DEFAULT_UNIFIED_SETTINGS, NotificationLevel } from "@t3tools/contracts/settings";
+import { normalizeModelSlug } from "@t3tools/shared/model";
 import { scopeThreadRef } from "@t3tools/client-runtime";
-import { DEFAULT_UNIFIED_SETTINGS } from "@t3tools/contracts/settings";
 import { createModelSelection } from "@t3tools/shared/model";
 import { Equal } from "effect";
 import { APP_VERSION } from "../../branding";
@@ -26,6 +27,7 @@ import { TraitsPicker } from "../chat/TraitsPicker";
 import { resolveAndPersistPreferredEditor } from "../../editorPreferences";
 import { isElectron } from "../../env";
 import { useTheme } from "../../hooks/useTheme";
+import { useNotification } from "../../hooks/useNotification";
 import { useSettings, useUpdateSettings } from "../../hooks/useSettings";
 import { useThreadActions } from "../../hooks/useThreadActions";
 import {
@@ -48,6 +50,8 @@ import {
  useStore,
 } from "../../store";
 import { formatRelativeTime, formatRelativeTimeLabel } from "../../timestampFormat";
+import { cn } from "../../lib/utils";
+import { showNativeNotification } from "../../lib/nativeNotifications";
 import { Button } from "../ui/button";
 import { Empty, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from "../ui/empty";
 import { DraftInput } from "../ui/draft-input";
@@ -95,6 +99,29 @@ const TIMESTAMP_FORMAT_LABELS = {
  "24-hour": "24-hour",
 } as const;
 
+const NOTIFICATION_LEVELS = [
+ {
+ value: NotificationLevel.Off,
+ label: "Off",
+ description: "Disable all OS notifications.",
+ },
+ {
+ value: NotificationLevel.Important,
+ label: "Important",
+ description: "Approval/input required and failed tasks only.",
+ },
+ {
+ value: NotificationLevel.Normal,
+ label: "Normal",
+ description: "Important plus completed tasks.",
+ },
+ {
+ value: NotificationLevel.Verbose,
+ label: "Verbose",
+ description: "Normal plus task activity updates.",
+ },
+] as const;
+
 const DEFAULT_DRIVER_KIND = ProviderDriverKind.make("codex");
 
 function withoutProviderInstanceKey<V>(
@@ -451,6 +478,25 @@ export function GeneralSettingsPanel() {
  const { theme, setTheme } = useTheme();
  const settings = useSettings();
  const { updateSettings } = useUpdateSettings();
+ const { permission: notificationPermission, requestPermission } = useNotification();
+ const [openProviderDetails, setOpenProviderDetails] = useState<Record<ProviderKind, boolean>>({
+ codex: Boolean(
+ settings.providers.codex.binaryPath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.binaryPath ||
+ settings.providers.codex.homePath !== DEFAULT_UNIFIED_SETTINGS.providers.codex.homePath ||
+ settings.providers.codex.customModels.length > 0,
+ ),
+ claudeAgent: Boolean(
+ settings.providers.claudeAgent.binaryPath !==
+ DEFAULT_UNIFIED_SETTINGS.providers.claudeAgent.binaryPath ||
+ settings.providers.claudeAgent.customModels.length > 0,
+ ),
+ });
+ const [customModelInputByProvider, setCustomModelInputByProvider] = useState<
+ Record<ProviderKind, string>
+ >({
+ codex: "",
+ claudeAgent: "",
+ });
  const [openingPathByTarget, setOpeningPathByTarget] = useState({
  keybindings: false,
  logsDirectory: false,
@@ -946,6 +992,117 @@ export function GeneralSettingsPanel() {
  }
  />
 
+ <SettingsRow
+ title="Notifications"
+ description="Allow T3 Code to show OS notifications when a task completes."
+ resetAction={
+ settings.notificationLevel !== DEFAULT_UNIFIED_SETTINGS.notificationLevel ? (
+ <SettingResetButton
+ label="notifications"
+ onClick={() =>
+ updateSettings({
+ notificationLevel: DEFAULT_UNIFIED_SETTINGS.notificationLevel,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ value={settings.notificationLevel}
+ onValueChange={(value) => {
+ if (
+ value === NotificationLevel.Off ||
+ value === NotificationLevel.Important ||
+ value === NotificationLevel.Normal ||
+ value === NotificationLevel.Verbose
+ ) {
+ updateSettings({ notificationLevel: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Notification level">
+ <SelectValue>
+ {NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.label ?? "Normal"}
+ </SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {NOTIFICATION_LEVELS.map((option) => (
+ <SelectItem hideIndicator key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ status={
+ NOTIFICATION_LEVELS.find((option) => option.value === settings.notificationLevel)
+ ?.description ?? null
+ }
+ >
+ <div className="mt-3 flex flex-col gap-3 border-t border-border/60 pt-3">
+ <div className="flex flex-col gap-2 rounded-lg border border-border/70 bg-background/70 px-3 py-2 sm:flex-row sm:items-center sm:justify-between">
+ <div className="min-w-0 flex-1">
+ <p className="text-xs font-medium text-foreground">Permission status</p>
+ <p className="mt-1 text-[11px] text-muted-foreground">
+ {isElectron
+ ? "Desktop app permissions are managed by your OS."
+ : notificationPermission === "unsupported"
+ ? "Notifications are not supported by this browser."
+ : notificationPermission === "granted"
+ ? "Allowed"
+ : notificationPermission === "denied"
+ ? "Blocked"
+ : "Not yet requested"}
+ </p>
+ </div>
+ {isElectron ? null : (
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ notificationPermission === "unsupported" || notificationPermission === "granted"
+ }
+ onClick={requestPermission}
+ >
+ Request permission
+ </Button>
+ )}
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2">
+ <Button
+ size="xs"
+ variant="outline"
+ disabled={
+ settings.notificationLevel === NotificationLevel.Off ||
+ (!isElectron && notificationPermission !== "granted")
+ }
+ onClick={() => {
+ showNativeNotification({
+ title: "T3 Code",
+ body: "Notification test from settings.",
+ tag: "t3code:test",
+ });
+ }}
+ >
+ Send test notification
+ </Button>
+ {!isElectron && notificationPermission === "denied" ? (
+ <p className="text-[11px] text-muted-foreground">
+ Enable notifications in your browser site settings to allow OS alerts.
+ </p>
+ ) : null}
+ {isElectron || notificationPermission === "granted" ? (
+ <p className="text-[11px] text-muted-foreground">
+ If notifications still do not appear, check OS notification settings.
+ </p>
+ ) : null}
+ </div>
+ </div>
+ </SettingsRow>
+
  <SettingsRow
  title="Auto-open task panel"
  description="Open the right-side plan and task panel automatically when steps appear."
@@ -971,7 +1128,6 @@ export function GeneralSettingsPanel() {
  />
  }
  />
-
  <SettingsRow
  title="New threads"
  description="Pick the default workspace mode for newly created draft threads."

apps/web/src/hooks/useNotification.ts

@@ -0,0 +1,30 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+ getNotificationPermission,
+ requestNotificationPermission,
+} from "../lib/nativeNotifications";
+
+export function useNotification() {
+ const [permission, setPermission] = useState(getNotificationPermission());
+
+ const refresh = useCallback(() => {
+ setPermission(getNotificationPermission());
+ }, []);
+
+ const requestPermission = useCallback(async () => {
+ const next = await requestNotificationPermission();
+ setPermission(next);
+ }, []);
+
+ useEffect(() => {
+ refresh();
+ window.addEventListener("focus", refresh);
+
+ return () => {
+ window.removeEventListener("focus", refresh);
+ };
+ }, [refresh]);
+
+ return { permission, requestPermission, refresh };
+}

apps/web/src/hooks/useSettings.ts

@@ -16,6 +16,11 @@ import {
  type ClientSettings,
  DEFAULT_CLIENT_SETTINGS,
  DEFAULT_UNIFIED_SETTINGS,
+ NotificationLevel,
+ NotificationLevelSchema,
+ SidebarProjectSortOrder,
+ SidebarThreadSortOrder,
+ TimestampFormat,
  UnifiedSettings,
 } from "@t3tools/contracts/settings";
 import { ensureLocalApi } from "~/localApi";
@@ -188,6 +193,140 @@ export function useUpdateSettings() {
  };
 }
 
+// ── One-time migration from localStorage ─────────────────────────────
+
+export function buildLegacyServerSettingsMigrationPatch(legacySettings: Record<string, unknown>) {
+ const patch: DeepMutable<ServerSettingsPatch> = {};
+
+ if (Predicate.isBoolean(legacySettings.enableAssistantStreaming)) {
+ patch.enableAssistantStreaming = legacySettings.enableAssistantStreaming;
+ }
+
+ if (Schema.is(ThreadEnvMode)(legacySettings.defaultThreadEnvMode)) {
+ patch.defaultThreadEnvMode = legacySettings.defaultThreadEnvMode;
+ }
+
+ if (Schema.is(ModelSelection)(legacySettings.textGenerationModelSelection)) {
+ patch.textGenerationModelSelection = legacySettings.textGenerationModelSelection;
+ }
+
+ if (typeof legacySettings.codexBinaryPath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.binaryPath = legacySettings.codexBinaryPath;
+ }
+
+ if (typeof legacySettings.codexHomePath === "string") {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.homePath = legacySettings.codexHomePath;
+ }
+
+ if (Array.isArray(legacySettings.customCodexModels)) {
+ patch.providers ??= {};
+ patch.providers.codex ??= {};
+ patch.providers.codex.customModels = normalizeCustomModelSlugs(
+ legacySettings.customCodexModels,
+ new Set<string>(),
+ "codex",
+ );
+ }
+
+ if (Predicate.isString(legacySettings.claudeBinaryPath)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.binaryPath = legacySettings.claudeBinaryPath;
+ }
+
+ if (Array.isArray(legacySettings.customClaudeModels)) {
+ patch.providers ??= {};
+ patch.providers.claudeAgent ??= {};
+ patch.providers.claudeAgent.customModels = normalizeCustomModelSlugs(
+ legacySettings.customClaudeModels,
+ new Set<string>(),
+ "claudeAgent",
+ );
+ }
+
+ return patch;
+}
+
+export function buildLegacyClientSettingsMigrationPatch(
+ legacySettings: Record<string, unknown>,
+): Partial<DeepMutable<ClientSettings>> {
+ const patch: Partial<DeepMutable<ClientSettings>> = {};
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadArchive)) {
+ patch.confirmThreadArchive = legacySettings.confirmThreadArchive;
+ }
+
+ if (Predicate.isBoolean(legacySettings.confirmThreadDelete)) {
+ patch.confirmThreadDelete = legacySettings.confirmThreadDelete;
+ }
+
+ if (Predicate.isBoolean(legacySettings.diffWordWrap)) {
+ patch.diffWordWrap = legacySettings.diffWordWrap;
+ }
+
+ if (Schema.is(SidebarProjectSortOrder)(legacySettings.sidebarProjectSortOrder)) {
+ patch.sidebarProjectSortOrder = legacySettings.sidebarProjectSortOrder;
+ }
+
+ if (Schema.is(SidebarThreadSortOrder)(legacySettings.sidebarThreadSortOrder)) {
+ patch.sidebarThreadSortOrder = legacySettings.sidebarThreadSortOrder;
+ }
+
+ if (Schema.is(TimestampFormat)(legacySettings.timestampFormat)) {
+ patch.timestampFormat = legacySettings.timestampFormat;
+ }
+
+ if (Schema.is(NotificationLevelSchema)(legacySettings.notificationLevel)) {
+ patch.notificationLevel = legacySettings.notificationLevel as NotificationLevel;
+ }
+
+ return patch;
+}
+
+/**
+ * Call once on app startup.
+ * If the legacy localStorage key exists, migrate its values to the new server
+ * and client storage formats, then remove the legacy key so this only runs once.
+ */
+export function migrateLocalSettingsToServer(): void {
+ if (typeof window === "undefined") return;
+
+ const raw = localStorage.getItem(OLD_SETTINGS_KEY);
+ if (!raw) return;
+
+ try {
+ const old = JSON.parse(raw);
+ if (!Predicate.isObject(old)) return;
+
+ // Migrate server-relevant keys via RPC
+ const serverPatch = buildLegacyServerSettingsMigrationPatch(old);
+ if (Object.keys(serverPatch).length > 0) {
+ const api = ensureNativeApi();
+ void api.server.updateSettings(serverPatch);
+ }
+
+ // Migrate client-only keys to the new localStorage key
+ const clientPatch = buildLegacyClientSettingsMigrationPatch(old);
+ if (Object.keys(clientPatch).length > 0) {
+ const existing = localStorage.getItem(CLIENT_SETTINGS_STORAGE_KEY);
+ const current = existing ? (JSON.parse(existing) as Record<string, unknown>) : {};
+ localStorage.setItem(
+ CLIENT_SETTINGS_STORAGE_KEY,
+ JSON.stringify({ ...current, ...clientPatch }),
+ );
+ }
+ } catch (error) {
+ console.error("[MIGRATION] Error migrating local settings:", error);
+ } finally {
+ // Remove the legacy key regardless to keep migration one-shot behavior.
+ localStorage.removeItem(OLD_SETTINGS_KEY);
+ }
+}
+
 export function __resetClientSettingsPersistenceForTests(): void {
  clientSettingsSnapshot = DEFAULT_CLIENT_SETTINGS;
  clientSettingsHydrated = false;