feat: add PostHog event tracking across apps

apps/admin/src/components/PostHogUserIdentifier/PostHogUserIdentifier.tsx

@@ -1,24 +1,27 @@
 "use client";
 
 import { useUser } from "@clerk/nextjs";
+import { useQuery } from "@tanstack/react-query";
 import posthog from "posthog-js";
 import { useEffect } from "react";
+import { useTRPC } from "../../trpc/react";
 
 export function PostHogUserIdentifier() {
-	const { user, isLoaded } = useUser();
+	const { isSignedIn } = useUser();
+	const trpc = useTRPC();
 
-	useEffect(() => {
-		if (!isLoaded) return;
+	const { data: user } = useQuery({
+		...trpc.user.me.queryOptions(),
+		enabled: isSignedIn,
+	});
 
+	useEffect(() => {
 		if (user) {
-			posthog.identify(user.id, {
-				email: user.primaryEmailAddress?.emailAddress,
-				name: user.fullName,
-			});
-		} else {
+			posthog.identify(user.id, { email: user.email, name: user.name });
+		} else if (isSignedIn === false) {
 			posthog.reset();
 		}
-	}, [user, isLoaded]);
+	}, [user, isSignedIn]);
 
 	return null;
 }

apps/desktop/package.json

@@ -79,6 +79,7 @@
 		"node-pty": "1.1.0-beta30",
 		"os-locale": "^6.0.2",
 		"posthog-js": "^1.306.1",
+		"posthog-node": "^5.18.0",
 		"react": "^19.2.3",
 		"react-arborist": "^3.4.3",
 		"react-dnd": "^16.0.1",

apps/desktop/src/lib/trpc/routers/auth/index.ts

@@ -1,5 +1,6 @@
 import { observable } from "@trpc/server/observable";
 import type { BrowserWindow } from "electron";
+import { clearUserCache } from "main/lib/analytics";
 import { authService } from "main/lib/auth";
 import { AUTH_PROVIDERS } from "shared/auth";
 import { z } from "zod";
@@ -53,6 +54,7 @@ export const createAuthRouter = (getWindow: () => BrowserWindow | null) => {
 		 */
 		signOut: publicProcedure.mutation(async () => {
 			await authService.signOut();
+			clearUserCache();
 			return { success: true };
 		}),
 	});

apps/desktop/src/lib/trpc/routers/workspaces/workspaces.ts

@@ -1,5 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { track } from "main/lib/analytics";
 import { db } from "main/lib/db";
 import { terminalManager } from "main/lib/terminal";
 import { nanoid } from "nanoid";
@@ -166,6 +167,13 @@ export const createWorkspacesRouter = () => {
 				// Load setup configuration from the main repo (where .superset/config.json lives)
 				const setupConfig = loadSetupConfig(project.mainRepoPath);
 
+				track("workspace_created", {
+					workspace_id: workspace.id,
+					project_id: project.id,
+					branch: branch,
+					base_branch: targetBranch,
+				});
+
 				return {
 					workspace,
 					initialCommands: setupConfig?.setup || null,
@@ -271,6 +279,13 @@ export const createWorkspacesRouter = () => {
 					}
 				});
 
+				track("workspace_opened", {
+					workspace_id: returnedWorkspace.id,
+					project_id: project.id,
+					type: "branch",
+					was_existing: wasExisting,
+				});
+
 				return {
 					workspace: returnedWorkspace,
 					worktreePath: project.mainRepoPath,
@@ -772,6 +787,8 @@ export const createWorkspacesRouter = () => {
 						? `${terminalResult.failed} terminal process(es) may still be running`
 						: undefined;
 
+				track("workspace_deleted", { workspace_id: input.id });
+
 				return { success: true, teardownError, terminalWarning };
 			}),
 
@@ -1059,6 +1076,12 @@ export const createWorkspacesRouter = () => {
 				// Load setup configuration from the main repo
 				const setupConfig = loadSetupConfig(project.mainRepoPath);
 
+				track("workspace_opened", {
+					workspace_id: workspace.id,
+					project_id: project.id,
+					type: "worktree",
+				});
+
 				return {
 					workspace,
 					initialCommands: setupConfig?.setup || null,
@@ -1110,6 +1133,8 @@ export const createWorkspacesRouter = () => {
 						? `${terminalResult.failed} terminal process(es) may still be running`
 						: undefined;
 
+				track("workspace_closed", { workspace_id: input.id });
+
 				return { success: true, terminalWarning };
 			}),
 	});

apps/desktop/src/main/env.main.ts

@@ -18,6 +18,8 @@ export const env = createEnv({
 		NEXT_PUBLIC_WEB_URL: z.url().default("https://app.superset.sh"),
 		GOOGLE_CLIENT_ID: z.string().min(1),
 		GH_CLIENT_ID: z.string().min(1),
+		NEXT_PUBLIC_POSTHOG_KEY: z.string().optional(),
+		NEXT_PUBLIC_POSTHOG_HOST: z.string().default("https://us.i.posthog.com"),
 	},
 
 	runtimeEnv: {
@@ -29,6 +31,8 @@ export const env = createEnv({
 		NEXT_PUBLIC_WEB_URL: process.env.NEXT_PUBLIC_WEB_URL,
 		GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
 		GH_CLIENT_ID: process.env.GH_CLIENT_ID,
+		NEXT_PUBLIC_POSTHOG_KEY: process.env.NEXT_PUBLIC_POSTHOG_KEY,
+		NEXT_PUBLIC_POSTHOG_HOST: process.env.NEXT_PUBLIC_POSTHOG_HOST,
 	},
 	emptyStringAsUndefined: true,
 

apps/desktop/src/main/index.ts

@@ -3,6 +3,7 @@ import { app, BrowserWindow } from "electron";
 import { makeAppSetup } from "lib/electron-app/factories/app/setup";
 import { PROTOCOL_SCHEME } from "shared/constants";
 import { setupAgentHooks } from "./lib/agent-setup";
+import { shutdown as shutdownAnalytics, track } from "./lib/analytics";
 import { initAppState } from "./lib/app-state";
 import { authService, handleAuthDeepLink, isAuthDeepLink } from "./lib/auth";
 import { setupAutoUpdater } from "./lib/auto-updater";
@@ -48,6 +49,7 @@ async function processDeepLink(url: string): Promise<void> {
 				refreshTokenExpiresAt: result.refreshTokenExpiresAt,
 				state: result.state,
 			});
+			track("auth_completed");
 			focusMainWindow();
 		} else {
 			console.error("[main] Auth deep link failed:", result.error);
@@ -138,9 +140,9 @@ if (!gotTheLock) {
 			await processDeepLink(coldStartUrl);
 		}
 
-		// Clean up all terminals when app is quitting
+		// Clean up all terminals and analytics when app is quitting
 		app.on("before-quit", async () => {
-			await terminalManager.cleanup();
+			await Promise.all([terminalManager.cleanup(), shutdownAnalytics()]);
 		});
 	})();
 }

apps/desktop/src/main/lib/analytics/index.ts

@@ -0,0 +1,73 @@
+import { env } from "main/env.main";
+import { apiClient } from "main/lib/api-client";
+import { PostHog } from "posthog-node";
+
+let client: PostHog | null = null;
+let cachedUserId: string | null = null;
+
+function getClient(): PostHog | null {
+	if (!env.NEXT_PUBLIC_POSTHOG_KEY) {
+		return null;
+	}
+
+	if (!client) {
+		client = new PostHog(env.NEXT_PUBLIC_POSTHOG_KEY, {
+			host: env.NEXT_PUBLIC_POSTHOG_HOST,
+			flushAt: 1, // Send events immediately for desktop app
+			flushInterval: 0,
+		});
+	}
+	return client;
+}
+
+async function getUserId(): Promise<string | null> {
+	if (cachedUserId) return cachedUserId;
+	try {
+		const user = await apiClient.user.me.query();
+		cachedUserId = user?.id ?? null;
+		return cachedUserId;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Clear cached user ID (call on sign out)
+ */
+export function clearUserCache(): void {
+	cachedUserId = null;
+}
+
+/**
+ * Track an event with the current user's ID as distinct_id.
+ * Fire-and-forget - errors are silently ignored.
+ */
+export function track(
+	event: string,
+	properties?: Record<string, unknown>,
+): void {
+	const posthog = getClient();
+	if (!posthog) return;
+
+	getUserId()
+		.then((userId) => {
+			if (!userId) return;
+			posthog.capture({
+				distinctId: userId,
+				event,
+				properties: {
+					...properties,
+					app_name: "desktop",
+					platform: process.platform,
+				},
+			});
+		})
+		.catch(() => {});
+}
+
+/**
+ * Shutdown PostHog client (call on app quit)
+ */
+export async function shutdown(): Promise<void> {
+	await client?.shutdown();
+}

apps/desktop/src/main/lib/terminal/manager.test.ts

@@ -6,14 +6,14 @@ import * as pty from "node-pty";
 import { getHistoryDir } from "../terminal-history";
 import { TerminalManager } from "./manager";
 
-// Use real history implementation - it will write to tmpdir thanks to NODE_ENV=test
-const testTmpDir = join(tmpdir(), "superset-test");
-
 // Mock node-pty
 mock.module("node-pty", () => ({
 	spawn: mock(() => {}),
 }));
 
+// Use real history implementation - it will write to tmpdir thanks to NODE_ENV=test
+const testTmpDir = join(tmpdir(), "superset-test");
+
 describe("TerminalManager", () => {
 	let manager: TerminalManager;
 	let mockPty: {

apps/desktop/src/main/lib/terminal/manager.ts

@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+import { track } from "main/lib/analytics";
 import { FALLBACK_SHELL, SHELL_CRASH_THRESHOLD_MS } from "./env";
 import {
 	closeSessionHistory,
@@ -58,7 +59,7 @@ export class TerminalManager extends EventEmitter {
 	private async doCreateSession(
 		params: InternalCreateSessionParams,
 	): Promise<SessionResult> {
-		const { paneId, initialCommands } = params;
+		const { paneId, workspaceId, initialCommands } = params;
 
 		// Create the session
 		const session = await createSession(params, (id, data) => {
@@ -75,6 +76,9 @@ export class TerminalManager extends EventEmitter {
 
 		this.sessions.set(paneId, session);
 
+		// Track terminal opened (only fires once per session creation)
+		track("terminal_opened", { workspace_id: workspaceId, pane_id: paneId });
+
 		return {
 			isNew: true,
 			scrollback: session.scrollback,

apps/desktop/src/renderer/components/PostHogUserIdentifier/PostHogUserIdentifier.tsx

@@ -4,20 +4,15 @@ import { trpc } from "renderer/lib/trpc";
 import { posthog } from "../../lib/posthog";
 
 export function PostHogUserIdentifier() {
-	const { data: user, isLoading } = trpc.user.me.useQuery();
+	const { data: user, isSuccess } = trpc.user.me.useQuery();
 
 	useEffect(() => {
-		if (isLoading) return;
-
 		if (user) {
-			posthog.identify(user.id, {
-				email: user.email,
-				name: user.name,
-			});
-		} else {
+			posthog.identify(user.id, { email: user.email, name: user.name });
+		} else if (isSuccess) {
 			posthog.reset();
 		}
-	}, [user, isLoading]);
+	}, [user, isSuccess]);
 
 	return null;
 }

apps/desktop/src/renderer/screens/sign-in/index.tsx

@@ -1,16 +1,24 @@
 import { COMPANY } from "@superset/shared/constants";
 import { Button } from "@superset/ui/button";
+import { useEffect } from "react";
 import { FaGithub } from "react-icons/fa";
 import { FcGoogle } from "react-icons/fc";
+import { posthog } from "renderer/lib/posthog";
 import { trpc } from "renderer/lib/trpc";
 import type { AuthProvider } from "shared/auth";
 import { SupersetLogo } from "./components/SupersetLogo";
 
 export function SignInScreen() {
 	const signInMutation = trpc.auth.signIn.useMutation();
 
-	const signIn = (provider: AuthProvider) =>
+	useEffect(() => {
+		posthog.capture("desktop_opened");
+	}, []);
+
+	const signIn = (provider: AuthProvider) => {
+		posthog.capture("auth_started", { provider });
 		signInMutation.mutate({ provider });
+	};
 
 	return (
 		<div className="flex flex-col h-full w-full bg-background">

apps/desktop/test-setup.ts

@@ -85,4 +85,17 @@ mock.module("electron", () => ({
 		handle: mock(),
 		on: mock(),
 	},
+	shell: {
+		openExternal: mock(() => Promise.resolve()),
+	},
+}));
+
+// =============================================================================
+// Analytics Mock (has Electron/API dependencies)
+// =============================================================================
+
+mock.module("main/lib/analytics", () => ({
+	track: mock(() => {}),
+	clearUserCache: mock(() => {}),
+	shutdown: mock(() => Promise.resolve()),
 }));

apps/marketing/src/app/components/DownloadButton/DownloadButton.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { COMPANY, DOWNLOAD_URL_MAC_ARM64 } from "@superset/shared/constants";
+import posthog from "posthog-js";
 import { HiMiniArrowDownTray, HiMiniClock } from "react-icons/hi2";
 import { type DropdownSection, PlatformDropdown } from "../PlatformDropdown";
 
@@ -21,6 +22,7 @@ export function DownloadButton({
 			: "px-3 sm:px-6 py-2 sm:py-3 text-sm sm:text-base";
 
 	const handleAppleSiliconDownload = () => {
+		posthog.capture("download_clicked");
 		window.open(DOWNLOAD_URL_MAC_ARM64, "_blank");
 	};
 
@@ -76,7 +78,10 @@ export function DownloadButton({
 					id: "waitlist",
 					label: "Join waitlist for Windows & Linux",
 					icon: <HiMiniClock className="size-4" />,
-					onClick: onJoinWaitlist || (() => {}),
+					onClick: () => {
+						posthog.capture("waitlist_clicked");
+						onJoinWaitlist?.();
+					},
 				},
 				{
 					id: "build-from-source",