feat(omo-codex): add PostHog telemetry with omo_codex_daily_active event + 4-flag opt-out

packages/omo-codex/src/telemetry/atomic-write.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, describe, expect, it } from "bun:test"
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+import { writeFileAtomically } from "./atomic-write"
+
+const tempPaths: string[] = []
+
+function createTempPath(prefix: string): string {
+  const tempPath = mkdtempSync(join(tmpdir(), `${prefix}-`))
+  tempPaths.push(tempPath)
+  return tempPath
+}
+
+afterEach(() => {
+  for (const tempPath of tempPaths.splice(0)) {
+    rmSync(tempPath, { recursive: true, force: true })
+  }
+})
+
+describe("writeFileAtomically", () => {
+  it("writes contents when target file does not exist", () => {
+    // given
+    const tempDir = createTempPath("omo-codex-atomic-new")
+    const targetFilePath = join(tempDir, "state.json")
+
+    // when
+    writeFileAtomically(targetFilePath, "first-content")
+
+    // then
+    expect(readFileSync(targetFilePath, "utf-8")).toBe("first-content")
+  })
+
+  it("replaces contents when target file already exists", () => {
+    // given
+    const tempDir = createTempPath("omo-codex-atomic-replace")
+    const targetFilePath = join(tempDir, "state.json")
+    writeFileSync(targetFilePath, "old-content", "utf-8")
+
+    // when
+    writeFileAtomically(targetFilePath, "new-content")
+
+    // then
+    expect(readFileSync(targetFilePath, "utf-8")).toBe("new-content")
+  })
+
+  it("throws when parent directory does not exist", () => {
+    // given
+    const tempDir = createTempPath("omo-codex-atomic-missing-parent")
+    const targetFilePath = join(tempDir, "missing-parent", "state.json")
+
+    // when
+    const writeWithMissingParent = (): void => {
+      writeFileAtomically(targetFilePath, "content")
+    }
+
+    // then
+    expect(writeWithMissingParent).toThrow()
+  })
+
+  it("produces last-write-wins result for sequential writes", () => {
+    // given
+    const tempDir = createTempPath("omo-codex-atomic-sequential")
+    const targetFilePath = join(tempDir, "state.json")
+
+    // when
+    writeFileAtomically(targetFilePath, "first")
+    writeFileAtomically(targetFilePath, "second")
+    writeFileAtomically(targetFilePath, "third")
+
+    // then
+    expect(readFileSync(targetFilePath, "utf-8")).toBe("third")
+  })
+})

packages/omo-codex/src/telemetry/atomic-write.ts

@@ -0,0 +1,22 @@
+import { renameSync, unlinkSync, writeFileSync } from "node:fs"
+
+export function writeFileAtomically(filePath: string, content: string): void {
+  const tempPath = `${filePath}.tmp`
+  writeFileSync(tempPath, content, "utf-8")
+
+  try {
+    renameSync(tempPath, filePath)
+  } catch (error) {
+    const isPermissionError =
+      error instanceof Error &&
+      (error.message.includes("EPERM") || error.message.includes("EACCES"))
+
+    if (process.platform === "win32" && isPermissionError) {
+      unlinkSync(filePath)
+      renameSync(tempPath, filePath)
+      return
+    }
+
+    throw error
+  }
+}

packages/omo-codex/src/telemetry/data-path.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, describe, expect, it } from "bun:test"
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+import {
+  __resetOsProviderForTesting,
+  __setOsProviderForTesting,
+  getActivityStateDir,
+  getDataDir,
+} from "./data-path"
+
+const originalXdgDataHome = process.env.XDG_DATA_HOME
+
+const tempPaths: string[] = []
+
+function createTempPath(prefix: string): string {
+  const tempPath = mkdtempSync(join(tmpdir(), `${prefix}-`))
+  tempPaths.push(tempPath)
+  return tempPath
+}
+
+afterEach(() => {
+  __resetOsProviderForTesting()
+
+  if (originalXdgDataHome === undefined) {
+    delete process.env.XDG_DATA_HOME
+  } else {
+    process.env.XDG_DATA_HOME = originalXdgDataHome
+  }
+
+  for (const tempPath of tempPaths.splice(0)) {
+    rmSync(tempPath, { recursive: true, force: true })
+  }
+})
+
+describe("telemetry data path", () => {
+  it("uses XDG_DATA_HOME when the preferred path is writable", () => {
+    // given
+    const xdgDataHome = createTempPath("omo-codex-xdg")
+    process.env.XDG_DATA_HOME = xdgDataHome
+
+    // when
+    const resolvedDataDir = getDataDir()
+
+    // then
+    expect(resolvedDataDir.startsWith(xdgDataHome)).toBe(true)
+  })
+
+  it("falls back to tmp directory when XDG_DATA_HOME points to a non-directory", () => {
+    // given
+    const nonDirectoryRoot = createTempPath("omo-codex-xdg-file")
+    const nonDirectoryPath = join(nonDirectoryRoot, "xdg-data-home")
+    writeFileSync(nonDirectoryPath, "not-a-directory", "utf-8")
+    process.env.XDG_DATA_HOME = nonDirectoryPath
+
+    // when
+    const resolvedDataDir = getDataDir()
+
+    // then
+    expect(resolvedDataDir).toBe(join(tmpdir(), "omo-codex-data"))
+  })
+
+  it("uses homedir/.local/share when XDG_DATA_HOME is unset", () => {
+    // given
+    delete process.env.XDG_DATA_HOME
+    const customHomeRoot = createTempPath("omo-codex-home")
+    const customTmpRoot = createTempPath("omo-codex-tmp")
+    __setOsProviderForTesting({
+      homedir: () => customHomeRoot,
+      tmpdir: () => customTmpRoot,
+    })
+
+    // when
+    const resolvedDataDir = getDataDir()
+
+    // then
+    expect(resolvedDataDir).toBe(join(customHomeRoot, ".local", "share"))
+  })
+
+  it("returns activity state path ending with omo-codex", () => {
+    // given
+    const xdgDataHome = createTempPath("omo-codex-activity")
+    process.env.XDG_DATA_HOME = xdgDataHome
+
+    // when
+    const activityStateDir = getActivityStateDir()
+
+    // then
+    expect(activityStateDir.endsWith(join("", "omo-codex"))).toBe(true)
+  })
+
+  it("respects injected os provider homedir override", () => {
+    // given
+    delete process.env.XDG_DATA_HOME
+    const injectedHome = createTempPath("omo-codex-injected-home")
+    const injectedTmp = createTempPath("omo-codex-injected-tmp")
+    __setOsProviderForTesting({
+      homedir: () => injectedHome,
+      tmpdir: () => injectedTmp,
+    })
+
+    // when
+    const resolvedDataDir = getDataDir()
+
+    // then
+    expect(resolvedDataDir.startsWith(injectedHome)).toBe(true)
+    expect(resolvedDataDir).toBe(join(injectedHome, ".local", "share"))
+  })
+})

packages/omo-codex/src/telemetry/data-path.ts

@@ -0,0 +1,45 @@
+import { accessSync, constants, mkdirSync } from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+import { CACHE_DIR_NAME } from "./product-identity"
+
+type OsProvider = Pick<typeof os, "homedir" | "tmpdir">
+
+let osProviderOverride: OsProvider | null = null
+
+export function getOsProvider(): OsProvider {
+  return osProviderOverride ?? os
+}
+
+/** @internal test-only */
+export function __setOsProviderForTesting(provider: OsProvider): void {
+  osProviderOverride = provider
+}
+
+/** @internal test-only */
+export function __resetOsProviderForTesting(): void {
+  osProviderOverride = null
+}
+
+function resolveWritableDirectory(preferredDir: string, fallbackSuffix: string): string {
+  try {
+    mkdirSync(preferredDir, { recursive: true })
+    accessSync(preferredDir, constants.W_OK)
+    return preferredDir
+  } catch {
+    const fallbackDir = path.join(getOsProvider().tmpdir(), fallbackSuffix)
+    mkdirSync(fallbackDir, { recursive: true })
+    return fallbackDir
+  }
+}
+
+export function getDataDir(): string {
+  const preferredDataDir =
+    process.env.XDG_DATA_HOME ?? path.join(getOsProvider().homedir(), ".local", "share")
+  return resolveWritableDirectory(preferredDataDir, "omo-codex-data")
+}
+
+export function getActivityStateDir(): string {
+  return path.join(getDataDir(), CACHE_DIR_NAME)
+}

packages/omo-codex/src/telemetry/env-flags.test.ts

@@ -0,0 +1,145 @@
+import { afterEach, describe, expect, it } from "bun:test"
+
+import { shouldDisablePostHog } from "./env-flags"
+
+const TELEMETRY_ENV_KEYS = [
+  "OMO_DISABLE_POSTHOG",
+  "OMO_SEND_ANONYMOUS_TELEMETRY",
+  "OMO_CODEX_DISABLE_POSTHOG",
+  "OMO_CODEX_SEND_ANONYMOUS_TELEMETRY",
+] as const
+
+function clearTelemetryEnv(): void {
+  for (const envKey of TELEMETRY_ENV_KEYS) {
+    delete process.env[envKey]
+  }
+}
+
+afterEach(() => {
+  clearTelemetryEnv()
+})
+
+describe("shouldDisablePostHog", () => {
+  it("returns false when no env vars are set", () => {
+    // given
+    clearTelemetryEnv()
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(false)
+  })
+
+  it("returns true when OMO_DISABLE_POSTHOG is 1", () => {
+    // given
+    process.env.OMO_DISABLE_POSTHOG = "1"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when OMO_DISABLE_POSTHOG is true", () => {
+    // given
+    process.env.OMO_DISABLE_POSTHOG = "true"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns false when OMO_DISABLE_POSTHOG is 0", () => {
+    // given
+    process.env.OMO_DISABLE_POSTHOG = "0"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(false)
+  })
+
+  it("returns true when OMO_SEND_ANONYMOUS_TELEMETRY is 0", () => {
+    // given
+    process.env.OMO_SEND_ANONYMOUS_TELEMETRY = "0"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when OMO_SEND_ANONYMOUS_TELEMETRY is false", () => {
+    // given
+    process.env.OMO_SEND_ANONYMOUS_TELEMETRY = "false"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when OMO_SEND_ANONYMOUS_TELEMETRY is no", () => {
+    // given
+    process.env.OMO_SEND_ANONYMOUS_TELEMETRY = "no"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when OMO_CODEX_DISABLE_POSTHOG is 1", () => {
+    // given
+    process.env.OMO_CODEX_DISABLE_POSTHOG = "1"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when OMO_CODEX_SEND_ANONYMOUS_TELEMETRY is 0", () => {
+    // given
+    process.env.OMO_CODEX_SEND_ANONYMOUS_TELEMETRY = "0"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when global telemetry is enabled but codex-specific disable is set", () => {
+    // given
+    process.env.OMO_DISABLE_POSTHOG = "0"
+    process.env.OMO_CODEX_DISABLE_POSTHOG = "1"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+
+  it("returns true when codex-specific telemetry is enabled but global disable is set", () => {
+    // given
+    process.env.OMO_CODEX_DISABLE_POSTHOG = "0"
+    process.env.OMO_DISABLE_POSTHOG = "1"
+
+    // when
+    const result = shouldDisablePostHog()
+
+    // then
+    expect(result).toBe(true)
+  })
+})

packages/omo-codex/src/telemetry/env-flags.ts

@@ -0,0 +1,43 @@
+import {
+  DEFAULT_POSTHOG_API_KEY,
+  DEFAULT_POSTHOG_HOST,
+} from "./product-identity"
+
+function normalizeEnvValue(value: string | undefined): string | undefined {
+  return value?.trim().toLowerCase()
+}
+
+function isDisableFlag(value: string | undefined): boolean {
+  const normalized = normalizeEnvValue(value)
+  return normalized === "1" || normalized === "true"
+}
+
+function isTelemetryOptOutFlag(value: string | undefined): boolean {
+  const normalized = normalizeEnvValue(value)
+  return normalized === "0" || normalized === "false" || normalized === "no"
+}
+
+export function shouldDisablePostHog(): boolean {
+  return (
+    isDisableFlag(process.env.OMO_DISABLE_POSTHOG) ||
+    isTelemetryOptOutFlag(process.env.OMO_SEND_ANONYMOUS_TELEMETRY) ||
+    isDisableFlag(process.env.OMO_CODEX_DISABLE_POSTHOG) ||
+    isTelemetryOptOutFlag(process.env.OMO_CODEX_SEND_ANONYMOUS_TELEMETRY)
+  )
+}
+
+export function getPostHogApiKey(): string {
+  const explicit = process.env.POSTHOG_API_KEY
+  if (explicit === undefined) {
+    return DEFAULT_POSTHOG_API_KEY
+  }
+  return explicit.trim()
+}
+
+export function hasPostHogApiKey(): boolean {
+  return getPostHogApiKey().length > 0
+}
+
+export function getPostHogHost(): string {
+  return process.env.POSTHOG_HOST?.trim() || DEFAULT_POSTHOG_HOST
+}

packages/omo-codex/src/telemetry/index.ts

@@ -0,0 +1,12 @@
+export {
+  __resetActivityStateProviderForTesting,
+  __resetOsProviderForTesting,
+  __setActivityStateProviderForTesting,
+  __setOsProviderForTesting,
+  createCliPostHog,
+  createInstallPostHog,
+  createPluginPostHog,
+  getPostHogDistinctId,
+} from "./posthog"
+
+export type { PostHogActivityReason, PostHogClient } from "./posthog"

packages/omo-codex/src/telemetry/posthog-activity-state.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it } from "bun:test"
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { tmpdir } from "node:os"
+
+import { CACHE_DIR_NAME } from "./product-identity"
+
+const originalXdgDataHome = process.env.XDG_DATA_HOME
+const tempPaths: string[] = []
+
+function createDataHomePath(): string {
+  const tempPath = mkdtempSync(join(tmpdir(), "omo-codex-posthog-state-"))
+  tempPaths.push(tempPath)
+  return tempPath
+}
+
+async function importPostHogActivityStateModule() {
+  return import(`./posthog-activity-state?test=${Date.now()}-${Math.random()}`)
+}
+
+function getStateFilePath(dataHomePath: string): string {
+  return join(dataHomePath, CACHE_DIR_NAME, "posthog-activity.json")
+}
+
+afterEach(() => {
+  for (const tempPath of tempPaths.splice(0)) {
+    rmSync(tempPath, { recursive: true, force: true })
+  }
+
+  if (originalXdgDataHome === undefined) {
+    delete process.env.XDG_DATA_HOME
+    return
+  }
+
+  process.env.XDG_DATA_HOME = originalXdgDataHome
+})
+
+describe("getPostHogActivityCaptureState", () => {
+  it("creates state file and captures daily when no state file exists", async () => {
+    // given
+    const dataHomePath = createDataHomePath()
+    process.env.XDG_DATA_HOME = dataHomePath
+    const { getPostHogActivityCaptureState } = await importPostHogActivityStateModule()
+
+    // when
+    const result = getPostHogActivityCaptureState(new Date("2026-05-25T01:02:03.000Z"))
+
+    // then
+    expect(result).toEqual({
+      dayUTC: "2026-05-25",
+      captureDaily: true,
+    })
+
+    const stateFilePath = getStateFilePath(dataHomePath)
+    const persistedState = JSON.parse(readFileSync(stateFilePath, "utf-8")) as {
+      readonly lastActiveDayUTC?: string
+    }
+    expect(persistedState.lastActiveDayUTC).toBe("2026-05-25")
+  })
+
+  it("does not capture daily and does not rewrite file when state has today's UTC day", async () => {
+    // given
+    const dataHomePath = createDataHomePath()
+    const stateFilePath = getStateFilePath(dataHomePath)
+    mkdirSync(join(dataHomePath, CACHE_DIR_NAME), { recursive: true })
+    const originalStateContent = '{"lastActiveDayUTC":"2026-05-25"}\n'
+    writeFileSync(stateFilePath, originalStateContent)
+    process.env.XDG_DATA_HOME = dataHomePath
+    const { getPostHogActivityCaptureState } = await importPostHogActivityStateModule()
+
+    // when
+    const result = getPostHogActivityCaptureState(new Date("2026-05-25T10:20:30.000Z"))
+
+    // then
+    expect(result).toEqual({
+      dayUTC: "2026-05-25",
+      captureDaily: false,
+    })
+
+    const stateContentAfterCall = readFileSync(stateFilePath, "utf-8")
+    expect(stateContentAfterCall).toBe(originalStateContent)
+  })
+
+  it("captures daily and updates state when state file has yesterday UTC day", async () => {
+    // given
+    const dataHomePath = createDataHomePath()
+    const stateFilePath = getStateFilePath(dataHomePath)
+    mkdirSync(join(dataHomePath, CACHE_DIR_NAME), { recursive: true })
+    writeFileSync(stateFilePath, '{"lastActiveDayUTC":"2026-05-24"}\n')
+    process.env.XDG_DATA_HOME = dataHomePath
+    const { getPostHogActivityCaptureState } = await importPostHogActivityStateModule()
+
+    // when
+    const result = getPostHogActivityCaptureState(new Date("2026-05-25T00:00:01.000Z"))
+
+    // then
+    expect(result).toEqual({
+      dayUTC: "2026-05-25",
+      captureDaily: true,
+    })
+
+    const persistedState = JSON.parse(readFileSync(stateFilePath, "utf-8")) as {
+      readonly lastActiveDayUTC?: string
+    }
+    expect(persistedState.lastActiveDayUTC).toBe("2026-05-25")
+  })
+
+  it("captures daily and does not throw when state file has corrupted JSON", async () => {
+    // given
+    const dataHomePath = createDataHomePath()
+    const stateFilePath = getStateFilePath(dataHomePath)
+    mkdirSync(join(dataHomePath, CACHE_DIR_NAME), { recursive: true })
+    writeFileSync(stateFilePath, "{bad-json\n")
+    process.env.XDG_DATA_HOME = dataHomePath
+    const { getPostHogActivityCaptureState } = await importPostHogActivityStateModule()
+
+    // when
+    const result = getPostHogActivityCaptureState(new Date("2026-05-25T10:20:30.000Z"))
+
+    // then
+    expect(result).toEqual({
+      dayUTC: "2026-05-25",
+      captureDaily: true,
+    })
+  })
+
+  it("captures daily when state file has array payload", async () => {
+    // given
+    const dataHomePath = createDataHomePath()
+    const stateFilePath = getStateFilePath(dataHomePath)
+    mkdirSync(join(dataHomePath, CACHE_DIR_NAME), { recursive: true })
+    writeFileSync(stateFilePath, "[]\n")
+    process.env.XDG_DATA_HOME = dataHomePath
+    const { getPostHogActivityCaptureState } = await importPostHogActivityStateModule()
+
+    // when
+    const result = getPostHogActivityCaptureState(new Date("2026-05-25T10:20:30.000Z"))
+
+    // then
+    expect(result).toEqual({
+      dayUTC: "2026-05-25",
+      captureDaily: true,
+    })
+  })
+
+  it("captures daily when state file has numeric payload", async () => {
+    // given
+    const dataHomePath = createDataHomePath()
+    const stateFilePath = getStateFilePath(dataHomePath)
+    mkdirSync(join(dataHomePath, CACHE_DIR_NAME), { recursive: true })
+    writeFileSync(stateFilePath, "42\n")
+    process.env.XDG_DATA_HOME = dataHomePath
+    const { getPostHogActivityCaptureState } = await importPostHogActivityStateModule()
+
+    // when
+    const result = getPostHogActivityCaptureState(new Date("2026-05-25T10:20:30.000Z"))
+
+    // then
+    expect(result).toEqual({
+      dayUTC: "2026-05-25",
+      captureDaily: true,
+    })
+  })
+})

packages/omo-codex/src/telemetry/posthog-activity-state.ts

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { writeFileAtomically } from "./atomic-write"
+import { getActivityStateDir } from "./data-path"
+
+export type PostHogActivityState = {
+  readonly lastActiveDayUTC?: string
+}
+
+export type PostHogActivityCaptureState = {
+  readonly dayUTC: string
+  readonly captureDaily: boolean
+}
+
+const POSTHOG_ACTIVITY_STATE_FILE = "posthog-activity.json"
+
+function getPostHogActivityStateFilePath(): string {
+  return join(getActivityStateDir(), POSTHOG_ACTIVITY_STATE_FILE)
+}
+
+function getUtcDayString(date: Date): string {
+  return date.toISOString().slice(0, 10)
+}
+
+function isPostHogActivityState(value: unknown): value is PostHogActivityState {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function readPostHogActivityState(): PostHogActivityState {
+  const stateFilePath = getPostHogActivityStateFilePath()
+
+  if (!existsSync(stateFilePath)) {
+    return {}
+  }
+
+  try {
+    const stateContent = readFileSync(stateFilePath, "utf-8")
+    const stateJson: unknown = JSON.parse(stateContent)
+
+    if (!isPostHogActivityState(stateJson)) {
+      return {}
+    }
+
+    return stateJson
+  } catch {
+    return {}
+  }
+}
+
+function writePostHogActivityState(nextState: PostHogActivityState): void {
+  const stateDir = getActivityStateDir()
+  const stateFilePath = getPostHogActivityStateFilePath()
+
+  try {
+    mkdirSync(stateDir, { recursive: true })
+    writeFileAtomically(stateFilePath, `${JSON.stringify(nextState, null, 2)}\n`)
+  } catch {
+    return
+  }
+}
+
+export function getPostHogActivityCaptureState(
+  now: Date = new Date(),
+): PostHogActivityCaptureState {
+  const state = readPostHogActivityState()
+  const dayUTC = getUtcDayString(now)
+  const captureDaily = state.lastActiveDayUTC !== dayUTC
+
+  if (captureDaily) {
+    writePostHogActivityState({
+      ...state,
+      lastActiveDayUTC: dayUTC,
+    })
+  }
+
+  return {
+    dayUTC,
+    captureDaily,
+  }
+}

packages/omo-codex/src/telemetry/posthog.test.ts

@@ -0,0 +1,233 @@
+import { afterEach, beforeEach, describe, expect, it, mock } from "bun:test"
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+type CapturedPostHogMessage = {
+  readonly distinctId: string
+  readonly event: string
+  readonly properties?: Record<string, unknown>
+}
+
+type PostHogModule = typeof import("./posthog")
+
+async function importPostHogModule(): Promise<PostHogModule> {
+  return import(`./posthog?test=${Date.now()}-${Math.random()}`)
+}
+
+function clearTelemetryEnv(): void {
+  delete process.env.OMO_DISABLE_POSTHOG
+  delete process.env.OMO_SEND_ANONYMOUS_TELEMETRY
+  delete process.env.OMO_CODEX_DISABLE_POSTHOG
+  delete process.env.OMO_CODEX_SEND_ANONYMOUS_TELEMETRY
+  delete process.env.POSTHOG_API_KEY
+  delete process.env.POSTHOG_HOST
+}
+
+function mockPostHogNode(capturedMessages: CapturedPostHogMessage[]): void {
+  mock.module("posthog-node", () => ({
+    PostHog: class {
+      capture(message: CapturedPostHogMessage): void {
+        capturedMessages.push(message)
+      }
+
+      async shutdown(): Promise<void> {}
+    },
+  }))
+}
+
+function setMatrix(
+  globalDisable: string | undefined,
+  globalAnonymous: string | undefined,
+  codexDisable: string | undefined,
+  codexAnonymous: string | undefined,
+): void {
+  if (globalDisable === undefined) delete process.env.OMO_DISABLE_POSTHOG
+  else process.env.OMO_DISABLE_POSTHOG = globalDisable
+  if (globalAnonymous === undefined) delete process.env.OMO_SEND_ANONYMOUS_TELEMETRY
+  else process.env.OMO_SEND_ANONYMOUS_TELEMETRY = globalAnonymous
+  if (codexDisable === undefined) delete process.env.OMO_CODEX_DISABLE_POSTHOG
+  else process.env.OMO_CODEX_DISABLE_POSTHOG = codexDisable
+  if (codexAnonymous === undefined) delete process.env.OMO_CODEX_SEND_ANONYMOUS_TELEMETRY
+  else process.env.OMO_CODEX_SEND_ANONYMOUS_TELEMETRY = codexAnonymous
+}
+
+describe("omo-codex posthog telemetry", () => {
+  beforeEach(() => {
+    mock.restore()
+    clearTelemetryEnv()
+  })
+
+  afterEach(() => {
+    mock.restore()
+    clearTelemetryEnv()
+  })
+
+  it("matrix row 1 disabled when OMO_DISABLE_POSTHOG=1", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    setMatrix("1", undefined, undefined, undefined)
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(0)
+  })
+
+  it("matrix row 2 disabled when OMO_SEND_ANONYMOUS_TELEMETRY=0", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    setMatrix(undefined, "0", undefined, undefined)
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(0)
+  })
+
+  it("matrix row 3 disabled when OMO_CODEX_DISABLE_POSTHOG=1", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    setMatrix(undefined, undefined, "1", undefined)
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(0)
+  })
+
+  it("matrix row 4 disabled when OMO_CODEX_SEND_ANONYMOUS_TELEMETRY=0", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    setMatrix(undefined, undefined, undefined, "0")
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(0)
+  })
+
+  it("matrix row 5 enabled when all vars unset", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    setMatrix(undefined, undefined, undefined, undefined)
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(1)
+  })
+
+  it("captures omo_codex_daily_active with omo-codex platform", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages[0]?.event).toBe("omo_codex_daily_active")
+    expect(capturedMessages[0]?.properties?.platform).toBe("omo-codex")
+  })
+
+  it("does not capture on same day", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: false }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(0)
+  })
+
+  it("createInstallPostHog sets source=install", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createInstallPostHog().trackActive("distinct", "install_started")
+
+    // then
+    expect(capturedMessages[0]?.properties?.source).toBe("install")
+  })
+
+  it("createCliPostHog sets source=cli", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = "test-api-key"
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages[0]?.properties?.source).toBe("cli")
+  })
+
+  it("returns no-op when POSTHOG_API_KEY override is empty", async () => {
+    // given
+    const capturedMessages: CapturedPostHogMessage[] = []
+    mockPostHogNode(capturedMessages)
+    process.env.POSTHOG_API_KEY = " "
+    const posthog = await importPostHogModule()
+    posthog.__setActivityStateProviderForTesting(() => ({ dayUTC: "2026-05-25", captureDaily: true }))
+
+    // when
+    posthog.createCliPostHog().trackActive("distinct", "cli_run")
+
+    // then
+    expect(capturedMessages).toHaveLength(0)
+  })
+
+  it("uses API key exactly matching omodex source bytes", async () => {
+    // given
+    const posthog = await importPostHogModule()
+    const omodexPosthog = readFileSync(join(import.meta.dir, "../../../../src/shared/posthog.ts"), "utf-8")
+    const match = omodexPosthog.match(/DEFAULT_POSTHOG_API_KEY = "(phc_[a-zA-Z0-9]+)"/)
+
+    // when
+    const sourceKey = match?.[1]
+
+    // then
+    expect(sourceKey).toBe(posthog.DEFAULT_POSTHOG_API_KEY)
+  })
+})

packages/omo-codex/src/telemetry/posthog.ts

@@ -0,0 +1,188 @@
+import { createHash } from "node:crypto"
+import os from "node:os"
+
+import { PostHog } from "posthog-node"
+import packageJson from "../../package.json" with { type: "json" }
+
+import { getPostHogApiKey, getPostHogHost, hasPostHogApiKey, shouldDisablePostHog } from "./env-flags"
+import { getPostHogActivityCaptureState } from "./posthog-activity-state"
+import {
+  DEFAULT_POSTHOG_API_KEY,
+  DEFAULT_POSTHOG_HOST,
+  EVENT_NAME,
+  PACKAGE_NAME,
+  PRODUCT_NAME,
+} from "./product-identity"
+
+export { DEFAULT_POSTHOG_API_KEY, DEFAULT_POSTHOG_HOST }
+
+export type PostHogSource = "cli" | "plugin" | "install"
+export type PostHogActivityReason = "install_started" | "install_completed" | "cli_run"
+
+export type PostHogClient = {
+  trackActive: (distinctId: string, reason: PostHogActivityReason) => void
+  shutdown: () => Promise<void>
+}
+
+type OsProvider = Pick<typeof os, "arch" | "cpus" | "hostname" | "platform" | "release" | "totalmem" | "type">
+type ActivityStateProvider = typeof getPostHogActivityCaptureState
+
+let osProviderOverride: OsProvider | null = null
+let activityStateProviderOverride: ActivityStateProvider | null = null
+
+const NO_OP_POSTHOG: PostHogClient = {
+  trackActive: () => undefined,
+  shutdown: async () => undefined,
+}
+
+type PostHogCaptureEvent = Parameters<PostHog["capture"]>[0]
+
+function resolveOsProvider(): OsProvider {
+  return osProviderOverride ?? os
+}
+
+function resolveActivityStateProvider(): ActivityStateProvider {
+  return activityStateProviderOverride ?? getPostHogActivityCaptureState
+}
+
+function getSafeCpuInfo(): { readonly count: number; readonly model: string | undefined } {
+  try {
+    const cpuInfo = resolveOsProvider().cpus()
+    return {
+      count: cpuInfo.length,
+      model: cpuInfo[0]?.model,
+    }
+  } catch {
+    return {
+      count: 0,
+      model: undefined,
+    }
+  }
+}
+
+function getSharedProperties(source: PostHogSource): NonNullable<PostHogCaptureEvent["properties"]> {
+  const osProvider = resolveOsProvider()
+  const cpuInfo = getSafeCpuInfo()
+
+  return {
+    platform: "omo-codex",
+    product_name: PRODUCT_NAME,
+    package_name: PACKAGE_NAME,
+    package_version: packageJson.version,
+    runtime: "bun",
+    runtime_version: process.versions.bun ?? process.version,
+    source,
+    $os: osProvider.platform(),
+    $os_version: osProvider.release(),
+    os_arch: osProvider.arch(),
+    os_type: osProvider.type(),
+    cpu_count: cpuInfo.count,
+    cpu_model: cpuInfo.model,
+    total_memory_gb: Math.round(osProvider.totalmem() / 1024 / 1024 / 1024),
+    locale: Intl.DateTimeFormat().resolvedOptions().locale,
+    timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    shell: process.env.SHELL,
+    ci: Boolean(process.env.CI),
+    terminal: process.env.TERM_PROGRAM,
+  }
+}
+
+function createPostHogClient(
+  source: PostHogSource,
+  options: ConstructorParameters<typeof PostHog>[1],
+): PostHogClient {
+  if (shouldDisablePostHog() || !hasPostHogApiKey()) {
+    return NO_OP_POSTHOG
+  }
+
+  let client: PostHog
+  try {
+    client = new PostHog(getPostHogApiKey(), {
+      ...options,
+      host: getPostHogHost(),
+      disableGeoip: false,
+    })
+  } catch {
+    return NO_OP_POSTHOG
+  }
+
+  const sharedProperties = getSharedProperties(source)
+
+  return {
+    trackActive: (distinctId, reason) => {
+      const activityState = resolveActivityStateProvider()()
+      if (!activityState.captureDaily) {
+        return
+      }
+
+      client.capture({
+        distinctId,
+        event: EVENT_NAME,
+        properties: {
+          ...sharedProperties,
+          $process_person_profile: false,
+          day_utc: activityState.dayUTC,
+          reason,
+        },
+      })
+    },
+    shutdown: async () => client.shutdown(),
+  }
+}
+
+export function getPostHogDistinctId(): string {
+  return createHash("sha256").update(`omo-codex:${resolveOsProvider().hostname()}`).digest("hex")
+}
+
+export function createCliPostHog(): PostHogClient {
+  return createPostHogClient("cli", {
+    enableExceptionAutocapture: false,
+    enableLocalEvaluation: false,
+    strictLocalEvaluation: true,
+    disableRemoteConfig: true,
+    flushAt: 1,
+    flushInterval: 0,
+  })
+}
+
+export function createInstallPostHog(): PostHogClient {
+  return createPostHogClient("install", {
+    enableExceptionAutocapture: false,
+    enableLocalEvaluation: false,
+    strictLocalEvaluation: true,
+    disableRemoteConfig: true,
+    flushAt: 1,
+    flushInterval: 0,
+  })
+}
+
+export function createPluginPostHog(): PostHogClient {
+  return createPostHogClient("plugin", {
+    enableExceptionAutocapture: false,
+    enableLocalEvaluation: false,
+    strictLocalEvaluation: true,
+    disableRemoteConfig: true,
+    flushAt: 1,
+    flushInterval: 0,
+  })
+}
+
+/** @internal test-only */
+export function __setOsProviderForTesting(provider: OsProvider): void {
+  osProviderOverride = provider
+}
+
+/** @internal test-only */
+export function __resetOsProviderForTesting(): void {
+  osProviderOverride = null
+}
+
+/** @internal test-only */
+export function __setActivityStateProviderForTesting(provider: ActivityStateProvider): void {
+  activityStateProviderOverride = provider
+}
+
+/** @internal test-only */
+export function __resetActivityStateProviderForTesting(): void {
+  activityStateProviderOverride = null
+}

packages/omo-codex/src/telemetry/product-identity.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "bun:test"
+
+import { getProductVersion } from "./product-identity"
+
+describe("getProductVersion", () => {
+  it("returns omo-codex package version", () => {
+    // given
+
+    // when
+    const version = getProductVersion()
+
+    // then
+    expect(version).toBe("0.1.0")
+  })
+})

packages/omo-codex/src/telemetry/product-identity.ts

@@ -0,0 +1,13 @@
+import packageJson from "../../package.json" with { type: "json" }
+
+export const PRODUCT_NAME = "omo-codex"
+export const PACKAGE_NAME = "@oh-my-opencode/omo-codex"
+export const CACHE_DIR_NAME = "omo-codex"
+export const EVENT_NAME = "omo_codex_daily_active"
+export const LEGACY_PARENT_PACKAGE = "oh-my-opencode"
+export const DEFAULT_POSTHOG_HOST = "https://us.i.posthog.com"
+export const DEFAULT_POSTHOG_API_KEY = "phc_CFJhj5HyvA62QPhvyaUCtaq23aUfznnijg5VaaGkNk74"
+
+export function getProductVersion(): string {
+  return packageJson.version
+}