Add telemetry with improved reliability and testing

Implement anonymous usage telemetry with race condition prevention, failure tracking, and comprehensive tests:
- Add flushing guard to prevent concurrent flush calls
- Track consecutive failures and stop retrying after 3 attempts
- Use shorter 1.5s timeout on app exit instead of 5s for faster shutdown
- Remove high-frequency j/k navigation tracking (redundant with story_selected)
- Add tests for auto-flush threshold, concurrent flush prevention, and failure limits
- Include documentation in README and CLAUDE.md with opt-out instructions

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: brianlovin

CLAUDE.md

@@ -57,8 +57,15 @@ bun run debug highlighted-comment # Test comment highlighting
 - `src/api.ts` - API client for fetching from HNPWA API
 - `src/app.ts` - Main app class (testable)
 - `src/index.ts` - Entry point
+- `src/telemetry.ts` - Anonymous usage telemetry
 - `src/test/` - Test suite using OpenTUI testing framework
 
+## Telemetry
+
+Anonymous usage telemetry is enabled by default. Disable with:
+- Settings menu (`s`) → toggle Telemetry off
+- `hn --disable-telemetry` flag (permanently disables)
+
 ## Dependencies
 
 - `@opentui/core` - Terminal UI framework with Yoga layout engine

README.md

@@ -130,6 +130,38 @@ I made these choices so that it's easier for me to keep up with the most interes
 
 If you want your version of this tool to work differently, feel free to clone or consider opening a PR with more advanced settings to let people customize the default experience.
 
+## Telemetry
+
+This CLI collects anonymous usage data to help understand how people use it and what features to improve. No personal information or content is ever collected.
+
+### What's collected
+
+- App launches (with version number)
+- Feature usage counts (TLDR, chat, refresh)
+- Navigation patterns (stories selected, comments viewed)
+- Keyboard shortcut usage
+
+### What's NOT collected
+
+- Story content, titles, or URLs
+- Chat messages or AI responses
+- API keys or credentials
+- IP addresses or location data
+
+### Disabling telemetry
+
+**Option 1: Settings menu**
+
+Press `s` to open settings, then toggle "Telemetry" off.
+
+**Option 2: Launch flag**
+
+```bash
+hn --disable-telemetry
+```
+
+This permanently disables telemetry. Your preference is stored locally at `~/.config/hn-cli/config.json`.
+
 ## Credits
 
 Built with [OpenTUI](https://github.com/anthropics/opentui)

src/app.ts

@@ -1,5 +1,6 @@
 import { BoxRenderable, type CliRenderer, type RenderContext } from "@opentui/core";
 import { log } from "./logger";
+import * as telemetry from "./telemetry";
 import { getRankedPosts, getPostById } from "./api";
 import type { HackerNewsPost } from "./types";
 import {
@@ -10,6 +11,8 @@ import {
   saveConfig,
   loadConfig,
   clearAllApiKeys,
+  isTelemetryEnabled,
+  setTelemetryEnabled,
 } from "./config";
 import { type UpdateInfo } from "./version";
 import { COLORS, detectTheme } from "./theme";
@@ -442,6 +445,11 @@ export class HackerNewsApp {
         }
         this.rerenderSettings();
         break;
+
+      case "toggle_telemetry":
+        setTelemetryEnabled(!isTelemetryEnabled());
+        this.rerenderSettings();
+        break;
     }
   }
 
@@ -591,6 +599,7 @@ export class HackerNewsApp {
 
   private handleMainKey(key: any) {
     if (key.name === "s") {
+      telemetry.track("settings_opened");
       this.settingsIntent = "settings";
       this.showSettings();
       return;
@@ -601,15 +610,20 @@ export class HackerNewsApp {
     } else if (key.name === "k") {
       this.navigateStory(-1);
     } else if (key.name === "space" || key.name === " ") {
+      telemetry.track("comment_nav");
       // Space navigates to next root comment only (forward)
       this.navigateToNextComment();
     } else if (key.name === "o") {
+      telemetry.track("url_opened", { type: "url" });
       this.openStoryUrl();
     } else if (key.name === "c") {
+      telemetry.track("chat_opened");
       this.openChat();
     } else if (key.name === "r") {
+      telemetry.track("refresh");
       this.refresh();
     } else if (key.name === "t") {
+      telemetry.track("tldr_requested");
       this.handleTldrRequest();
     }
   }
@@ -651,6 +665,8 @@ export class HackerNewsApp {
     if (index < 0 || index >= this.posts.length) return;
     if (this.renderer.isDestroyed) return;
 
+    telemetry.track("story_selected");
+
     // Stop TLDR loading animation in detail view when switching stories
     // (TLDR generation continues in background - AI indicator keeps showing)
     if (this.tldrLoading) {
@@ -795,6 +811,7 @@ export class HackerNewsApp {
     generateTLDR(this.selectedPost, provider, {
       onComplete: (tldr) => {
         if (this.renderer.isDestroyed) return;
+        telemetry.track("tldr_completed", { success: true });
         this.tldrCache.set(storyId, tldr);
         this.tldrLoading = false;
         this.tldrLoadingStoryId = null;
@@ -806,6 +823,7 @@ export class HackerNewsApp {
         }
       },
       onError: (error) => {
+        telemetry.track("tldr_completed", { success: false });
         log("[ERROR]", "TLDR generation failed:", error);
         this.tldrErrorIds.add(storyId);
         this.tldrLoading = false;
@@ -1102,6 +1120,8 @@ export class HackerNewsApp {
     const userMessage = this.chatPanelState.input.plainText.trim();
     if (!userMessage) return;
 
+    telemetry.track("chat_message");
+
     // Clear input and suggestions
     this.chatPanelState.input.clear();
     this.chatPanelState.suggestions.suggestions = [];

src/components/SettingsPanel.ts

@@ -4,13 +4,15 @@ import {
   type Provider,
   getApiKey,
   getModel,
+  isTelemetryEnabled,
   ANTHROPIC_MODELS,
   OPENAI_MODELS,
 } from "../config";
 
 type SettingsItemType =
   | { type: "provider"; provider: Provider; hasKey: boolean }
   | { type: "model"; modelId: string; modelName: string }
+  | { type: "telemetry"; enabled: boolean }
   | { type: "action"; action: "done" | "clear_keys" };
 
 interface SettingsListItem {
@@ -56,6 +58,12 @@ function getSettingsList(chatProvider: Provider): SettingsListItem[] {
     }
   }
 
+  // Telemetry toggle
+  items.push({
+    item: { type: "telemetry", enabled: isTelemetryEnabled() },
+    enabled: true,
+  });
+
   // Action buttons
   items.push({
     item: { type: "action", action: "done" },
@@ -193,6 +201,48 @@ export function renderSettings(
     }
   }
 
+  // Telemetry section
+  container.add(new BoxRenderable(ctx, { height: 1 }));
+
+  const telemetryHeader = new TextRenderable(ctx, {
+    content: t`${bold("Telemetry")}`,
+    fg: COLORS.textSecondary,
+  });
+  container.add(telemetryHeader);
+
+  for (let i = 0; i < items.length; i++) {
+    const listItem = items[i];
+    if (!listItem || listItem.item.type !== "telemetry") continue;
+
+    const isSelected = i === state.selectedIndex;
+    const isEnabled = listItem.item.enabled;
+
+    const itemBox = new BoxRenderable(ctx, {
+      flexDirection: "row",
+      gap: 1,
+    });
+
+    const indicator = new TextRenderable(ctx, {
+      content: isSelected ? "›" : " ",
+      fg: COLORS.accent,
+    });
+    itemBox.add(indicator);
+
+    const toggle = new TextRenderable(ctx, {
+      content: isEnabled ? "●" : "○",
+      fg: isEnabled ? COLORS.accent : COLORS.textSecondary,
+    });
+    itemBox.add(toggle);
+
+    const label = new TextRenderable(ctx, {
+      content: isEnabled ? "Enabled" : "Disabled",
+      fg: isSelected ? COLORS.accent : COLORS.textPrimary,
+    });
+    itemBox.add(label);
+
+    container.add(itemBox);
+  }
+
   container.add(new BoxRenderable(ctx, { height: 1 }));
 
   // Actions section
@@ -258,6 +308,7 @@ export type SettingsAction =
   | { type: "add_anthropic" }
   | { type: "add_openai" }
   | { type: "clear_keys" }
+  | { type: "toggle_telemetry" }
   | { type: "done" }
   | null;
 
@@ -290,6 +341,9 @@ export function selectSettingsItem(
         provider: chatProvider,
       };
 
+    case "telemetry":
+      return { type: "toggle_telemetry" };
+
     case "action":
       switch (selected.item.action) {
         case "done":

src/config.ts

@@ -33,6 +33,8 @@ export interface Config {
   openaiApiKey?: string;
   anthropicModel?: AnthropicModel;
   openaiModel?: OpenAIModel;
+  telemetryEnabled?: boolean;
+  userId?: string;
 }
 
 const CONFIG_DIR = join(homedir(), ".config", "hn-cli");
@@ -167,6 +169,45 @@ export function clearApiKey(provider: Provider): void {
 }
 
 export function clearAllApiKeys(): void {
-  // Clear everything - start fresh (currently Config only contains API-related settings)
-  saveConfig({});
+  // Clear API-related settings but preserve telemetry preferences
+  const config = loadConfig();
+  saveConfig({
+    telemetryEnabled: config.telemetryEnabled,
+    userId: config.userId,
+  });
+}
+
+// Telemetry settings
+
+/**
+ * Check if telemetry is enabled (default: true)
+ */
+export function isTelemetryEnabled(): boolean {
+  const config = loadConfig();
+  return config.telemetryEnabled !== false;
+}
+
+/**
+ * Enable or disable telemetry
+ */
+export function setTelemetryEnabled(enabled: boolean): void {
+  const config = loadConfig();
+  config.telemetryEnabled = enabled;
+  saveConfig(config);
+}
+
+/**
+ * Get or generate anonymous user ID for telemetry
+ */
+export function getUserId(): string {
+  const config = loadConfig();
+  if (config.userId) {
+    return config.userId;
+  }
+
+  // Generate a new UUID
+  const userId = crypto.randomUUID();
+  config.userId = userId;
+  saveConfig(config);
+  return userId;
 }

src/index.ts

@@ -2,13 +2,24 @@
 import { createCliRenderer } from "@opentui/core";
 import { exec } from "child_process";
 import { HackerNewsApp } from "./app";
-import { checkForUpdates } from "./version";
+import { checkForUpdates, currentVersion } from "./version";
+import { setTelemetryEnabled } from "./config";
+import * as telemetry from "./telemetry";
 
 const COLORS = {
   bg: "#1a1a1a",
 };
 
 async function main() {
+  // Handle --disable-telemetry flag (permanently disables telemetry)
+  if (process.argv.includes("--disable-telemetry")) {
+    setTelemetryEnabled(false);
+  }
+
+  // Initialize telemetry and track app launch
+  telemetry.init();
+  telemetry.track("app_launch", { version: currentVersion });
+
   const renderer = await createCliRenderer({
     exitOnCtrlC: true,
     backgroundColor: COLORS.bg,
@@ -25,7 +36,8 @@ async function main() {
     onOpenUrl: (url) => {
       exec(`open "${url}"`);
     },
-    onExit: () => {
+    onExit: async () => {
+      await telemetry.flushSync();
       renderer.destroy();
       process.exit(0);
     },