feat(telemetry): add PostHog analytics with runtime opt-out control

Instrument key app lifecycle and reliability events with PostHog, and add a persisted Settings toggle that immediately enables or disables telemetry capture at runtime.

Made-with: Cursor

Author: beautyfree

bun.lock

@@ -42,6 +42,7 @@
     "handlebars": "^4.7.9",
     "i18next": "^25.8.19",
     "lucide-react": "^0.577.0",
+    "posthog-js": "^1.370.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-i18next": "^16.5.8",

package.json

@@ -1,8 +1,13 @@
-import { useEffect, useState } from 'react'
-import { HashRouter, Routes, Route, Navigate } from 'react-router-dom'
+import { useEffect, useRef, useState } from 'react'
+import { HashRouter, Routes, Route, Navigate, useLocation } from 'react-router-dom'
 import { useQueryClient } from '@tanstack/react-query'
 import { listen, invoke } from '@/mainview/lib/native'
 import { useTranslation } from 'react-i18next'
+import {
+  captureTelemetry,
+  identifyTelemetry,
+  setTelemetryEnabled,
+} from '@/mainview/lib/telemetry'
 import Layout from './components/Layout'
 import Dashboard from './pages/Dashboard'
 import SkillsManager from './pages/SkillsManager'
@@ -22,8 +27,11 @@ const STAR_PROMPT_RESHOW_MS = 3 * 24 * 60 * 60 * 1000
 
 function AppInner() {
   const queryClient = useQueryClient()
+  const location = useLocation()
   const { i18n } = useTranslation()
   useTheme()
+  const appOpenedTrackedRef = useRef(false)
+  const [telemetryReady, setTelemetryReady] = useState(false)
   const [closeDialogOpen, setCloseDialogOpen] = useState(false)
   const [showGithubStarPrompt, setShowGithubStarPrompt] = useState(false)
   // Onboarding shows on very first launch (or when user explicitly replays it
@@ -37,6 +45,25 @@ function AppInner() {
     }
   })
 
+  useEffect(() => {
+    if (!telemetryReady || appOpenedTrackedRef.current) return
+    appOpenedTrackedRef.current = true
+    captureTelemetry('app_opened')
+    void invoke('get_app_version')
+      .then((version) => {
+        identifyTelemetry(`desktop:${version}`, { app_version: version })
+      })
+      .catch(() => {})
+  }, [telemetryReady])
+
+  useEffect(() => {
+    if (!telemetryReady) return
+    captureTelemetry('page_view', {
+      path: location.pathname,
+      search: location.search,
+    })
+  }, [location.pathname, location.search, telemetryReady])
+
   useEffect(() => {
     const handler = (event: Event) => {
       const detail = (event as CustomEvent<{ force?: boolean }>).detail
@@ -96,8 +123,12 @@ function AppInner() {
         if (lang && lang !== i18n.language) {
           void i18n.changeLanguage(lang)
         }
+        setTelemetryEnabled(settings.analytics_enabled !== false)
+        setTelemetryReady(true)
+      })
+      .catch(() => {
+        setTelemetryReady(true)
       })
-      .catch(() => {})
   }, []) // eslint-disable-line react-hooks/exhaustive-deps
 
   // Ask for a GitHub star once after meaningful usage cadence.
@@ -161,6 +192,7 @@ function AppInner() {
 
   const handleGithubStarDismiss = () => {
     setShowGithubStarPrompt(false)
+    captureTelemetry('github_star_prompt_dismissed')
     void invoke('read_settings')
       .then((settings) => {
         const existing = settings.github_star_prompt ?? {}
@@ -182,6 +214,7 @@ function AppInner() {
 
   const handleGithubStarClick = () => {
     setShowGithubStarPrompt(false)
+    captureTelemetry('github_star_prompt_clicked')
     void invoke('open_external', { url: GITHUB_REPO_URL })
     void invoke('read_settings')
       .then((settings) =>
@@ -198,6 +231,12 @@ function AppInner() {
       .catch(() => {})
   }
 
+  useEffect(() => {
+    if (showGithubStarPrompt) {
+      captureTelemetry('github_star_prompt_shown')
+    }
+  }, [showGithubStarPrompt])
+
   useEffect(() => {
     let cancelled = false
     let unlisten: (() => void) | undefined

src/mainview/App.tsx

@@ -299,6 +299,12 @@ const en = {
       "Blur is off because window blur was disabled via environment variable. Your choice is still saved for next launch without it.",
     // Language
     language: "Language",
+    // Analytics
+    analytics: "Telemetry",
+    analyticsDescription:
+      "Anonymous product analytics and diagnostics powered by PostHog. Disable this to stop tracking events from this app.",
+    analyticsOn: "On",
+    analyticsOff: "Off",
     // App Updates
     appUpdates: "App Updates",
     updateStateIdle: "Up to date",

src/mainview/i18n/en.ts

@@ -1,5 +1,6 @@
 import { isTrpcQueryProcedure } from '@/shared/trpc-query-procedures'
 import type { AppRPCSchema } from '@/shared/rpc-schema'
+import { captureTelemetry } from '@/mainview/lib/telemetry'
 
 /**
  * Renderer-side glue to the main process.
@@ -231,11 +232,32 @@ export async function invoke<K extends keyof BunRequests>(
 ): Promise<BunRequests[K]['response']> {
   const name = cmd as string
   const input = args[0]
-  return callTrpcProcedure<BunRequests[K]['response']>(
-    name,
-    input,
-    isTrpcQueryProcedure(name),
-  )
+  const isQuery = isTrpcQueryProcedure(name)
+  const startedAt = performance.now()
+  try {
+    const response = await callTrpcProcedure<BunRequests[K]['response']>(
+      name,
+      input,
+      isQuery,
+    )
+    if (!isQuery) {
+      captureTelemetry('rpc_mutation_called', {
+        command: name,
+        duration_ms: Math.round(performance.now() - startedAt),
+      })
+    }
+    return response
+  } catch (error) {
+    const message =
+      error instanceof Error ? error.message.slice(0, 240) : 'unknown'
+    captureTelemetry('rpc_call_failed', {
+      command: name,
+      is_query: isQuery,
+      duration_ms: Math.round(performance.now() - startedAt),
+      message,
+    })
+    throw error
+  }
 }
 
 export async function listen<T>(

src/mainview/lib/native.ts

@@ -0,0 +1,83 @@
+import posthog from 'posthog-js'
+
+const DEFAULT_POSTHOG_KEY = 'phc_q6DHwwvAXc2XeGRFsZ3qQiyF5p5gbXqLJduYm4kR742G'
+const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com'
+
+const env = import.meta as ImportMeta & {
+  env?: {
+    VITE_POSTHOG_KEY?: string
+    VITE_POSTHOG_HOST?: string
+    MODE?: string
+  }
+}
+
+const TELEMETRY_DISABLED =
+  (env.env?.VITE_POSTHOG_KEY ?? DEFAULT_POSTHOG_KEY).trim().length === 0
+
+let initialized = false
+let telemetryEnabled = false
+
+export function initTelemetry(): void {
+  if (initialized || TELEMETRY_DISABLED) return
+  initialized = true
+
+  posthog.init(env.env?.VITE_POSTHOG_KEY ?? DEFAULT_POSTHOG_KEY, {
+    api_host: env.env?.VITE_POSTHOG_HOST ?? DEFAULT_POSTHOG_HOST,
+    capture_pageview: false,
+    capture_pageleave: true,
+    autocapture: true,
+    person_profiles: 'identified_only',
+    persistence: 'localStorage+cookie',
+    loaded: (client) => {
+      client.register({
+        app: 'skiller-desktop',
+        app_env: env.env?.MODE ?? 'unknown',
+      })
+      if (!telemetryEnabled) {
+        client.opt_out_capturing()
+      }
+    },
+  })
+}
+
+export function setTelemetryEnabled(enabled: boolean): void {
+  telemetryEnabled = enabled
+  if (TELEMETRY_DISABLED || !initialized) return
+  try {
+    if (enabled) {
+      posthog.opt_in_capturing()
+    } else {
+      posthog.opt_out_capturing()
+    }
+  } catch {
+    // Keep telemetry non-blocking for UX and app flow.
+  }
+}
+
+export function isTelemetryEnabled(): boolean {
+  return telemetryEnabled
+}
+
+export function captureTelemetry(
+  event: string,
+  properties?: Record<string, unknown>,
+): void {
+  if (TELEMETRY_DISABLED || !initialized || !telemetryEnabled) return
+  try {
+    posthog.capture(event, properties)
+  } catch {
+    // Keep telemetry non-blocking for UX and app flow.
+  }
+}
+
+export function identifyTelemetry(
+  distinctId: string,
+  properties?: Record<string, unknown>,
+): void {
+  if (TELEMETRY_DISABLED || !initialized || !telemetryEnabled) return
+  try {
+    posthog.identify(distinctId, properties)
+  } catch {
+    // Keep telemetry non-blocking for UX and app flow.
+  }
+}

src/mainview/lib/telemetry.ts

@@ -4,10 +4,30 @@ import ReactDOM from 'react-dom/client'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import App from '@/mainview/App'
 import { ToastProvider } from '@/mainview/components/ToastProvider'
+import { captureTelemetry, initTelemetry } from '@/mainview/lib/telemetry'
 import '@/mainview/i18n'
 import '@/mainview/index.css'
 
 const queryClient = new QueryClient()
+initTelemetry()
+
+window.addEventListener('error', (event) => {
+  captureTelemetry('renderer_error', {
+    message: event.message || 'unknown',
+    source: event.filename || 'unknown',
+    line: event.lineno || 0,
+  })
+})
+
+window.addEventListener('unhandledrejection', (event) => {
+  const reason =
+    event.reason instanceof Error
+      ? event.reason.message
+      : typeof event.reason === 'string'
+        ? event.reason
+        : 'unknown'
+  captureTelemetry('renderer_unhandled_rejection', { reason })
+})
 
 /* ── Global mouse tracker for liquid-glass highlight (one listener; HMR dispose removes the previous) ── */
 {

src/mainview/main.tsx

@@ -13,6 +13,7 @@ import {
   AlertTriangle,
 } from 'lucide-react'
 import { openUrl, invoke, listen } from '@/mainview/lib/native'
+import { setTelemetryEnabled } from '@/mainview/lib/telemetry'
 import type {
   AppUpdateStatusJson,
 } from '@/shared/rpc-schema'
@@ -27,6 +28,7 @@ interface AppSettings {
   language: string | null
   path_overrides: Record<string, string[]> | null
   close_action: string | null
+  analytics_enabled?: boolean | null
   macos_window_blur?: boolean | null
   assumed_listing_char_budget?: number | null
   assumed_context_window_chars?: number | null
@@ -37,6 +39,7 @@ const DEFAULT_SETTINGS: AppSettings = {
   language: null,
   path_overrides: null,
   close_action: null,
+  analytics_enabled: null,
   macos_window_blur: null,
 }
 
@@ -425,6 +428,42 @@ export default function SettingsPage() {
           </div>
         </section>
 
+        {/* Analytics */}
+        <section className="rounded-2xl p-5 glass-panel settings-panel space-y-3">
+          <div className="flex items-start justify-between gap-4">
+            <div className="min-w-0">
+              <h2 className="text-sm font-medium">{t('settings.analytics')}</h2>
+              <p className="mt-1 text-xs text-muted-foreground leading-relaxed">
+                {t('settings.analyticsDescription')}
+              </p>
+            </div>
+            <div className="flex shrink-0 gap-1.5">
+              {([true, false] as const).map((enabled) => {
+                const currentEnabled = settings?.analytics_enabled !== false
+                const isActive = currentEnabled === enabled
+                return (
+                  <Button
+                    key={enabled ? 'on' : 'off'}
+                    variant={isActive ? 'default' : 'outline'}
+                    size="sm"
+                    onClick={() => {
+                      setTelemetryEnabled(enabled)
+                      saveMutation.mutate({
+                        ...(settings ?? DEFAULT_SETTINGS),
+                        analytics_enabled: enabled,
+                      })
+                    }}
+                  >
+                    {enabled
+                      ? t('settings.analyticsOn')
+                      : t('settings.analyticsOff')}
+                  </Button>
+                )
+              })}
+            </div>
+          </div>
+        </section>
+
         {/* Close Behavior */}
         <section className="rounded-2xl p-5 glass-panel settings-panel space-y-3">
           <div className="flex items-start justify-between gap-4">

src/mainview/pages/Settings.tsx

@@ -95,6 +95,8 @@ export type AppSettingsJson = {
   assumed_listing_char_budget?: number | null;
   /** Optional context window size (chars); 1% can derive a listing budget when budget is unset. */
   assumed_context_window_chars?: number | null;
+  /** Product telemetry and analytics (PostHog). Default true when omitted. */
+  analytics_enabled?: boolean | null;
   /** One-time GitHub star prompt cadence metadata. */
   github_star_prompt?: {
     first_seen_at?: string | null;