🤖 feat: move PostHog telemetry to backend to avoid adblock

This moves telemetry event capture from the browser (posthog-js) to the
Electron main process (posthog-node). Events from the renderer are now
forwarded via ORPC to the backend TelemetryService.

Benefits:
- Ad blockers cannot block telemetry requests from the main process
- Centralized distinct ID management (persisted in ~/.mux/telemetry_id)
- Base properties (version, platform, electronVersion) added by backend

Changes:
- Add posthog-node dependency
- Create TelemetryService in src/node/services/
- Add ORPC telemetry.{track, setEnabled, isEnabled} routes
- Update frontend client to call backend via ORPC
- Simplify payload types (backend adds base properties)

The frontend API (useTelemetry hook, trackEvent function) remains unchanged.

_Generated with mux_

Author: ammar-agent

bun.lock

@@ -1,6 +1,5 @@
 {
   "lockfileVersion": 1,
-  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "mux",
@@ -50,6 +49,7 @@
         "ollama-ai-provider-v2": "^1.5.4",
         "openai": "^6.9.1",
         "parse-duration": "^2.1.4",
+        "posthog-node": "^5.17.0",
         "rehype-harden": "^1.1.5",
         "shescape": "^2.1.6",
         "source-map-support": "^0.5.21",
@@ -3003,6 +3003,8 @@
 
     "posthog-js": ["posthog-js@1.299.0", "", { "dependencies": { "@posthog/core": "1.6.0", "core-js": "^3.38.1", "fflate": "^0.4.8", "preact": "^10.19.3", "web-vitals": "^4.2.4" } }, "sha512-euHXKcEqQpRJNWitudVl4/doTJsftgaBDRLNGczt/v3S9N6ppLMzEOmeoqvNhNDIlpxGVlTvSawfw9HeW1r5nA=="],
 
+    "posthog-node": ["posthog-node@5.17.0", "", { "dependencies": { "@posthog/core": "1.7.0" } }, "sha512-M+ftj0kLJk6wVF1xW5cStSany0LBC6YDVO7RPma2poo+PrpeiTk+ovhqcIqWAySDdTcBHJfBV9aIFYWPl2y6kg=="],
+
     "preact": ["preact@10.28.0", "", {}, "sha512-rytDAoiXr3+t6OIP3WGlDd0ouCUG1iCWzkcY3++Nreuoi17y6T5i/zRhe6uYfoVcxq6YU+sBtJouuRDsq8vvqA=="],
 
     "prelude-ls": ["prelude-ls@1.2.1", "", {}, "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g=="],
@@ -4085,6 +4087,8 @@
 
     "pkg-dir/find-up": ["find-up@4.1.0", "", { "dependencies": { "locate-path": "^5.0.0", "path-exists": "^4.0.0" } }, "sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw=="],
 
+    "posthog-node/@posthog/core": ["@posthog/core@1.7.0", "", { "dependencies": { "cross-spawn": "^7.0.6" } }, "sha512-d6ZV4grpzeH/6/LP8quMVpSjY1puRkrqfwcPvGRKUAX7tb7YHyp/zMiTDuJmOFbpUxAMBXH5nDwcPiyCY2WGzA=="],
+
     "pretty-format/ansi-styles": ["ansi-styles@5.2.0", "", {}, "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA=="],
 
     "prop-types/react-is": ["react-is@16.13.1", "", {}, "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ=="],

package.json

@@ -90,6 +90,7 @@
     "ollama-ai-provider-v2": "^1.5.4",
     "openai": "^6.9.1",
     "parse-duration": "^2.1.4",
+    "posthog-node": "^5.17.0",
     "rehype-harden": "^1.1.5",
     "shescape": "^2.1.6",
     "source-map-support": "^0.5.21",

src/browser/hooks/useTelemetry.ts

@@ -1,11 +1,13 @@
 import { useCallback } from "react";
-import { trackEvent, getBaseTelemetryProperties, roundToBase2 } from "@/common/telemetry";
+import { trackEvent, roundToBase2 } from "@/common/telemetry";
 import type { ErrorContext } from "@/common/telemetry/payload";
 
 /**
  * Hook for clean telemetry integration in React components
  *
- * Provides type-safe telemetry tracking with base properties automatically included.
+ * Provides type-safe telemetry tracking. Base properties (version, platform, etc.)
+ * are automatically added by the backend TelemetryService.
+ *
  * Usage:
  *
  * ```tsx
@@ -30,7 +32,6 @@ export function useTelemetry() {
     trackEvent({
       event: "workspace_switched",
       properties: {
-        ...getBaseTelemetryProperties(),
         fromWorkspaceId,
         toWorkspaceId,
       },
@@ -42,7 +43,6 @@ export function useTelemetry() {
     trackEvent({
       event: "workspace_created",
       properties: {
-        ...getBaseTelemetryProperties(),
         workspaceId,
       },
     });
@@ -53,7 +53,6 @@ export function useTelemetry() {
     trackEvent({
       event: "message_sent",
       properties: {
-        ...getBaseTelemetryProperties(),
         model,
         mode,
         message_length_b2: roundToBase2(messageLength),
@@ -66,7 +65,6 @@ export function useTelemetry() {
     trackEvent({
       event: "error_occurred",
       properties: {
-        ...getBaseTelemetryProperties(),
         errorType,
         context,
       },

src/cli/cli.test.ts

@@ -67,6 +67,7 @@ async function createTestServer(authToken?: string): Promise<TestServerHandle> {
     serverService: services.serverService,
     menuEventService: services.menuEventService,
     voiceService: services.voiceService,
+    telemetryService: services.telemetryService,
   };
 
   // Use the actual createOrpcServer function

src/cli/server.test.ts

@@ -70,6 +70,7 @@ async function createTestServer(): Promise<TestServerHandle> {
     serverService: services.serverService,
     menuEventService: services.menuEventService,
     voiceService: services.voiceService,
+    telemetryService: services.telemetryService,
   };
 
   // Use the actual createOrpcServer function

src/cli/server.ts

@@ -78,6 +78,7 @@ const mockWindow: BrowserWindow = {
     serverService: serviceContainer.serverService,
     menuEventService: serviceContainer.menuEventService,
     voiceService: serviceContainer.voiceService,
+    telemetryService: serviceContainer.telemetryService,
   };
 
   const server = await createOrpcServer({

src/common/orpc/schemas.ts

@@ -98,6 +98,8 @@ export {
   providers,
   ProvidersConfigMapSchema,
   server,
+  telemetry,
+  TelemetryEventSchema,
   terminal,
   tokenizer,
   update,

src/common/orpc/schemas/api.ts

@@ -16,6 +16,9 @@ import {
 import { BashToolResultSchema, FileTreeNodeSchema } from "./tools";
 import { FrontendWorkspaceMetadataSchema, WorkspaceActivitySnapshotSchema } from "./workspace";
 
+// Re-export telemetry schemas
+export { telemetry, TelemetryEventSchema } from "./telemetry";
+
 // --- API Router Schemas ---
 
 // Tokenizer

src/common/orpc/schemas/telemetry.ts

@@ -0,0 +1,84 @@
+/**
+ * Telemetry ORPC schemas
+ *
+ * Defines input/output schemas for backend telemetry endpoints.
+ */
+
+import { z } from "zod";
+
+// Error context enum (matches payload.ts)
+const ErrorContextSchema = z.enum([
+  "workspace-creation",
+  "workspace-deletion",
+  "workspace-switch",
+  "message-send",
+  "message-stream",
+  "project-add",
+  "project-remove",
+  "git-operation",
+]);
+
+// Individual event payload schemas
+const AppStartedPropertiesSchema = z.object({
+  isFirstLaunch: z.boolean(),
+});
+
+const WorkspaceCreatedPropertiesSchema = z.object({
+  workspaceId: z.string(),
+});
+
+const WorkspaceSwitchedPropertiesSchema = z.object({
+  fromWorkspaceId: z.string(),
+  toWorkspaceId: z.string(),
+});
+
+const MessageSentPropertiesSchema = z.object({
+  model: z.string(),
+  mode: z.string(),
+  message_length_b2: z.number(),
+});
+
+const ErrorOccurredPropertiesSchema = z.object({
+  errorType: z.string(),
+  context: ErrorContextSchema,
+});
+
+// Union of all telemetry events
+export const TelemetryEventSchema = z.discriminatedUnion("event", [
+  z.object({
+    event: z.literal("app_started"),
+    properties: AppStartedPropertiesSchema,
+  }),
+  z.object({
+    event: z.literal("workspace_created"),
+    properties: WorkspaceCreatedPropertiesSchema,
+  }),
+  z.object({
+    event: z.literal("workspace_switched"),
+    properties: WorkspaceSwitchedPropertiesSchema,
+  }),
+  z.object({
+    event: z.literal("message_sent"),
+    properties: MessageSentPropertiesSchema,
+  }),
+  z.object({
+    event: z.literal("error_occurred"),
+    properties: ErrorOccurredPropertiesSchema,
+  }),
+]);
+
+// API schemas
+export const telemetry = {
+  track: {
+    input: TelemetryEventSchema,
+    output: z.void(),
+  },
+  setEnabled: {
+    input: z.object({ enabled: z.boolean() }),
+    output: z.void(),
+  },
+  isEnabled: {
+    input: z.void(),
+    output: z.boolean(),
+  },
+};

src/common/telemetry/client.test.ts

@@ -1,13 +1,3 @@
-// Mock posthog-js to avoid import issues in test environment
-jest.mock("posthog-js", () => ({
-  __esModule: true,
-  default: {
-    init: jest.fn(),
-    capture: jest.fn(),
-    reset: jest.fn(),
-  },
-}));
-
 // Ensure NODE_ENV is set to test for telemetry detection
 // Must be set before importing the client module
 process.env.NODE_ENV = "test";
@@ -20,20 +10,18 @@ describe("Telemetry", () => {
       process.env.NODE_ENV = "test";
     });
 
-    it("should not initialize PostHog", () => {
+    it("should not initialize", () => {
       initTelemetry();
       expect(isTelemetryInitialized()).toBe(false);
     });
 
     it("should silently ignore track events", () => {
       // Should not throw even though not initialized
+      // Base properties (version, platform, electronVersion) are now added by backend
       expect(() => {
         trackEvent({
           event: "workspace_switched",
           properties: {
-            version: "1.0.0",
-            platform: "darwin",
-            electronVersion: "28.0.0",
             fromWorkspaceId: "test-from",
             toWorkspaceId: "test-to",
           },