Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(console): ask once whether to share anonymous usage data (CHOO-1955) (#215)

Louis Amaudruz3e16e4158502
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a8d1a5402..1e885653a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -645,6 +645,19 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Added
+
+- Switch Console now asks, the first time you open it, whether you are happy to
+ share anonymous usage data, and states plainly what that would and would not
+ include. The choice is saved per install and can be changed at any time from
+ **Settings → General** (CHOO-1955).
+- The app still sends nothing: there is no telemetry to consent to yet. What
+ this adds is the control and the contract — a single gate that any future
+ collection must ask before sending, which fails closed, so a fresh install
+ that has not reached the prompt sends nothing regardless of how the toggle
+ reads. Because the toggle defaults to on, `console/AGENTS.md` now pins what a
+ payload may ever contain: anonymous counters, and no identifier of any kind.
+
#### Fixed
- Two Switch Console installs sharing a host no longer destroy each other's
diff --git a/console/AGENTS.md b/console/AGENTS.md
index d4832f2b6..a0b742882 100644
--- a/console/AGENTS.md
+++ b/console/AGENTS.md
@@ -394,11 +394,27 @@ pnpm run lint
or generated dependency folders.
- Application secrets are stored through encrypted app secret services and Electron
safe storage.
-- The app ships no telemetry or analytics; do not add tracking or phone-home behavior.
- Logs are local-only and no code path transmits them off the machine. Do not add one.
- `getDiagnosticLogAttachment()` builds a redacted export and is the only function
- intended to ever feed such a path; anything that ships log content must go through it
- rather than reading the log itself.
+- The app sends no telemetry or analytics today, and nothing may start sending without
+ going through the consent gate below. Logs are local-only and no code path transmits
+ them off the machine. Do not add one. `getDiagnosticLogAttachment()` builds a redacted
+ export and is the only function intended to ever feed such a path; anything that ships
+ log content must go through it rather than reading the log itself.
+- **Telemetry consent is a gate, not a preference.** Anything that would send usage data
+ must `await isTelemetryAllowed()` (`src/main/core/telemetry/consent.ts`) at the point of
+ emission and send nothing when it returns false. Do not read `telemetry.enabled` from
+ settings directly — it does not distinguish "said yes" from "not asked yet" — and do not
+ cache the answer across a send, since the user can revoke it at any time.
+- **What telemetry may contain, if it is ever built.** The consent toggle defaults to *on*,
+ which is only defensible for data that is not personal, so the payload is limited to
+ anonymous counters: feature-usage counts, error and crash counts, app version, operating
+ system. It must carry **no identifier of any kind** — no install id, machine id, user id,
+ or any other value that distinguishes one install from another — and no prompts, code,
+ file paths, or agent/room/project/server names. Adding an identifier makes the data
+ pseudonymous personal data under GDPR/nFADP, at which point an opt-out default is no
+ longer valid and the default has to flip to off. That is a decision for the product
+ owner, not a code change: if you need per-install numbers, raise it rather than adding
+ a field. The user-facing wording of this promise lives in
+ `src/renderer/features/telemetry/telemetry-copy.ts` and must be kept in step.
- **Redaction is split by destination, and both halves must be preserved:**
- **Secrets** (tokens, keys, JWTs, PEM blocks, URL credentials) are redacted on the
write path by `redactSecrets()` and must never reach disk.
diff --git a/console/apps/switch-console-desktop/src/main/core/settings/schema.ts b/console/apps/switch-console-desktop/src/main/core/settings/schema.ts
index b5ba8bce1..c0ac45b0b 100644
--- a/console/apps/switch-console-desktop/src/main/core/settings/schema.ts
+++ b/console/apps/switch-console-desktop/src/main/core/settings/schema.ts
@@ -102,6 +102,21 @@ export const browserSettingsSchema = z
settings.profiles.some((profile) => profile.id === settings.defaultProfileId)
);
+/**
+ * Whether the user lets the app send anonymous usage data, and when they were
+ * asked.
+ *
+ * `askedAt` is null until the user has answered the first-run prompt, and is
+ * what distinguishes "hasn't been asked yet" from "was asked and left it on".
+ * Nothing may be sent while it is null, however `enabled` reads — see
+ * `isTelemetryAllowed` in `@main/core/telemetry/consent`, which is the only
+ * supported way to read this setting before emitting.
+ */
+export const telemetrySettingsSchema = z.object({
+ enabled: z.boolean(),
+ askedAt: z.number().nullable(),
+});
+
/**
* How many sessions on one remote host keep a live terminal at once.
*
@@ -147,6 +162,7 @@ export const APP_SETTINGS_SCHEMA_MAP = {
changesViewMode: changesViewModeSchema,
remote: remoteSettingsSchema,
onboarding: onboardingSettingsSchema,
+ telemetry: telemetrySettingsSchema,
} as const;
export const appSettingsSchema = z.object({
@@ -164,4 +180,5 @@ export const appSettingsSchema = z.object({
changesViewMode: changesViewModeSchema,
remote: remoteSettingsSchema,
onboarding: onboardingSettingsSchema,
+ telemetry: telemetrySettingsSchema,
});
diff --git a/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts b/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts
index 91ab8c6a6..e1755f1d2 100644
--- a/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts
+++ b/console/apps/switch-console-desktop/src/main/core/settings/settings-registry.ts
@@ -65,6 +65,10 @@ export const SETTINGS_DEFAULTS = {
staged: 'flat' as const,
pr: 'flat' as const,
},
+ telemetry: {
+ enabled: true,
+ askedAt: null,
+ },
} satisfies SettingsDefaultsMap;
export function getDefaultForKey<K extends AppSettingsKey>(key: K): AppSettings[K] {
diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.ts
new file mode 100644
index 000000000..da22e7192
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.test.ts
@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@main/core/settings/settings-service', () => ({
+ appSettingsService: {
+ get: vi.fn(),
+ },
+}));
+
+import { appSettingsService } from '@main/core/settings/settings-service';
+import { isTelemetryAllowed } from './consent';
+
+describe('isTelemetryAllowed', () => {
+ beforeEach(() => {
+ vi.resetAllMocks();
+ });
+
+ it('allows sending once the user has been asked and left the toggle on', async () => {
+ vi.mocked(appSettingsService.get).mockResolvedValue({ enabled: true, askedAt: 1_700_000_000 });
+ await expect(isTelemetryAllowed()).resolves.toBe(true);
+ });
+
+ it('refuses on a fresh install that has not reached the prompt yet', async () => {
+ vi.mocked(appSettingsService.get).mockResolvedValue({ enabled: true, askedAt: null });
+ await expect(isTelemetryAllowed()).resolves.toBe(false);
+ });
+
+ it('refuses once the user has turned it off', async () => {
+ vi.mocked(appSettingsService.get).mockResolvedValue({ enabled: false, askedAt: 1_700_000_000 });
+ await expect(isTelemetryAllowed()).resolves.toBe(false);
+ });
+
+ it('refuses when the toggle is off and the prompt was never answered', async () => {
+ vi.mocked(appSettingsService.get).mockResolvedValue({ enabled: false, askedAt: null });
+ await expect(isTelemetryAllowed()).resolves.toBe(false);
+ });
+});
diff --git a/console/apps/switch-console-desktop/src/main/core/telemetry/consent.ts b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.ts
new file mode 100644
index 000000000..077458e55
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/main/core/telemetry/consent.ts
@@ -0,0 +1,25 @@
+import { appSettingsService } from '@main/core/settings/settings-service';
+
+/**
+ * Whether anonymous usage data may leave this machine right now.
+ *
+ * Nothing may be sent without calling this first and getting `true` back. It is
+ * the only supported way to read the consent setting at an emission point: read
+ * `telemetry.enabled` directly and you miss the "hasn't been asked yet" case,
+ * which is not the same as "said yes".
+ *
+ * It fails closed on purpose. Consent requires both that the user has seen the
+ * first-run prompt (`askedAt`) and that the toggle is on, so a fresh install
+ * that has not reached the prompt sends nothing, and a settings read that
+ * throws sends nothing either.
+ *
+ * There is no telemetry in the app today — this is the gate the collection work
+ * (CHOO-1683) is expected to call once there is something to send. What it may
+ * send is constrained: see the payload rule in `console/AGENTS.md`. Anonymous
+ * counters only, and no identifier of any kind, because the toggle defaults to
+ * on and an opt-out default is only defensible for non-personal data.
+ */
+export async function isTelemetryAllowed(): Promise<boolean> {
+ const telemetry = await appSettingsService.get('telemetry');
+ return telemetry.askedAt !== null && telemetry.enabled;
+}
diff --git a/console/apps/switch-console-desktop/src/renderer/App.tsx b/console/apps/switch-console-desktop/src/renderer/App.tsx
index e803ee39f..3e5c3e088 100644
--- a/console/apps/switch-console-desktop/src/renderer/App.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/App.tsx
@@ -3,6 +3,7 @@ import { AppMenuEvents } from './app/app-menu-events';
import { Workspace } from './app/workspace';
import { SessionFocusReporter } from './features/sessions/session-focus-reporter-mount';
import { SessionDeeplinkListener } from './features/switch-rooms/session-deeplink-listener';
+import { TelemetryConsentGate } from './features/telemetry/TelemetryConsentGate';
import { WorkspaceLayoutContextProvider } from './lib/layout/layout-provider';
import { WorkspaceViewProvider } from './lib/layout/provider';
import { ModalRenderer } from './lib/modal/modal-renderer';
@@ -24,6 +25,7 @@ function AppContent() {
<RightSidebarProvider>
<ThemeProvider>
<ModalRenderer />
+ <TelemetryConsentGate />
<Workspace />
</ThemeProvider>
</RightSidebarProvider>
diff --git a/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx b/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx
index f2dfdb9a6..2a3e4126a 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/features/settings/components/SettingsPage.tsx
@@ -13,6 +13,7 @@ import {
EnableTmuxRow,
PreserveSessionNameCapitalizationRow,
} from './SessionSettingsRows';
+import TelemetrySettingsCard from './TelemetrySettingsCard';
import TerminalSettingsCard from './TerminalSettingsCard';
import ThemeCard from './ThemeCard';
import { UpdateCard } from './UpdateCard';
@@ -46,6 +47,7 @@ function GeneralSettingsPage() {
<EnableTmuxRow />
<NotificationSettingsCard />
<OnboardingChecklistRow />
+ <TelemetrySettingsCard />
</div>
);
}
diff --git a/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsx b/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsx
new file mode 100644
index 000000000..af02a919d
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/settings/components/TelemetrySettingsCard.tsx
@@ -0,0 +1,55 @@
+import React, { useCallback } from 'react';
+import { useAppSettingsKey } from '@renderer/features/settings/use-app-settings-key';
+import {
+ TELEMETRY_NEVER_SHARED,
+ TELEMETRY_SHARED,
+ TELEMETRY_SUMMARY,
+} from '@renderer/features/telemetry/telemetry-copy';
+import { Switch } from '@renderer/lib/ui/switch';
+import { SettingRow } from './SettingRow';
+
+function joinAsSentence(items: string[]): string {
+ return items.map((item, index) => (index === 0 ? item : item.toLowerCase())).join('; ');
+}
+
+const TelemetrySettingsCard: React.FC = () => {
+ const {
+ value: telemetry,
+ update,
+ isLoading: loading,
+ isSaving: saving,
+ } = useAppSettingsKey('telemetry');
+
+ const enabled = telemetry?.enabled ?? true;
+
+ const toggle = useCallback(
+ (next: boolean) => {
+ // Answering here counts as being asked, so a user who reaches Settings
+ // before the prompt appears is not asked again for a choice they made.
+ update({ enabled: next, askedAt: telemetry?.askedAt ?? Date.now() });
+ },
+ [telemetry?.askedAt, update]
+ );
+
+ return (
+ <SettingRow
+ title="Share anonymous usage data"
+ description={
+ <>
+ <p>{TELEMETRY_SUMMARY}</p>
+ <p className="mt-1">
+ <span className="text-foreground-muted">Shared:</span>{' '}
+ {joinAsSentence(TELEMETRY_SHARED)}.
+ </p>
+ <p>
+ <span className="text-foreground-muted">Never shared:</span>{' '}
+ {joinAsSentence(TELEMETRY_NEVER_SHARED)}.
+ </p>
+ </>
+ }
+ control={<Switch checked={enabled} disabled={loading || saving} onCheckedChange={toggle} />}
+ />
+ );
+};
+
+export default TelemetrySettingsCard;
diff --git a/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsx b/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsx
new file mode 100644
index 000000000..f833a4c5b
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentDialog.tsx
@@ -0,0 +1,122 @@
+import { CheckIcon, XIcon } from 'lucide-react';
+import React, { useCallback, useState } from 'react';
+import { useAppSettingsKey } from '@renderer/features/settings/use-app-settings-key';
+import { Button } from '@renderer/lib/ui/button';
+import { Dialog, DialogContent, DialogContentArea, DialogFooter } from '@renderer/lib/ui/dialog';
+import { SectionLabel } from '@renderer/lib/ui/label';
+import { Shortcut } from '@renderer/lib/ui/shortcut';
+import { Switch } from '@renderer/lib/ui/switch';
+import {
+ TELEMETRY_NEVER_SHARED,
+ TELEMETRY_REVERSIBLE,
+ TELEMETRY_SHARED,
+ TELEMETRY_SUMMARY,
+} from './telemetry-copy';
+
+function DisclosureList({
+ title,
+ items,
+ tone,
+}: {
+ title: string;
+ items: string[];
+ tone: 'shared' | 'never';
+}) {
+ const Icon = tone === 'shared' ? CheckIcon : XIcon;
+ return (
+ <div className="flex flex-col gap-1.5">
+ <SectionLabel className="text-foreground-tertiary-passive">{title}</SectionLabel>
+ <ul className="flex flex-col gap-1.5">
+ {items.map((item) => (
+ <li key={item} className="flex items-start gap-2 text-sm text-foreground-muted">
+ <Icon
+ aria-hidden
+ className={
+ tone === 'shared'
+ ? 'mt-0.5 size-3.5 shrink-0 text-foreground-success'
+ : 'mt-0.5 size-3.5 shrink-0 text-foreground-tertiary-passive'
+ }
+ />
+ <span>{item}</span>
+ </li>
+ ))}
+ </ul>
+ </div>
+ );
+}
+
+/**
+ * The first-run consent prompt.
+ *
+ * Rendered only when the user has never answered it, and not dismissible: the
+ * answer is recorded by `askedAt`, so closing it without choosing would leave
+ * the app asking again on every launch. Declining is a first-class option, not
+ * a hidden one — the toggle starts on, matching the default, and the user can
+ * turn it off before continuing.
+ */
+export function TelemetryConsentDialog({ onAnswered }: { onAnswered: () => void }) {
+ const { value, updateAsync } = useAppSettingsKey('telemetry');
+ const [enabled, setEnabled] = useState(value?.enabled ?? true);
+ const [saving, setSaving] = useState(false);
+
+ const confirm = useCallback(() => {
+ setSaving(true);
+ void updateAsync({ enabled, askedAt: Date.now() })
+ .then(onAnswered)
+ .finally(() => setSaving(false));
+ }, [enabled, onAnswered, updateAsync]);
+
+ // Enter confirms, because the footer advertises it. The switch answers to
+ // Space, so this does not steal the keyboard from changing the choice.
+ const onKeyDown = useCallback(
+ (event: React.KeyboardEvent) => {
+ if (event.key !== 'Enter' || saving) return;
+ event.preventDefault();
+ confirm();
+ },
+ [confirm, saving]
+ );
+
+ return (
+ // Controlled `open` with no `onOpenChange`: Escape and outside clicks are
+ // requests the parent ignores, so the prompt cannot be dismissed unanswered.
+ <Dialog open>
+ <DialogContent aria-labelledby="telemetry-consent-heading" onKeyDown={onKeyDown}>
+ <div className="flex flex-col gap-2 p-6 pb-4">
+ <h2 id="telemetry-consent-heading" className="text-base font-normal text-foreground">
+ Help improve Switch Console
+ </h2>
+ <p className="text-sm text-foreground-muted">{TELEMETRY_SUMMARY}</p>
+ </div>
+ <DialogContentArea className="gap-4">
+ <DisclosureList title="What is shared" items={TELEMETRY_SHARED} tone="shared" />
+ <DisclosureList
+ title="What is never shared"
+ items={TELEMETRY_NEVER_SHARED}
+ tone="never"
+ />
+ <div className="mt-1 flex items-center justify-between gap-4 rounded-lg border border-border bg-background-1 p-3">
+ <label htmlFor="telemetry-consent-switch" className="text-sm text-foreground">
+ Share anonymous usage data
+ </label>
+ <Switch
+ id="telemetry-consent-switch"
+ checked={enabled}
+ disabled={saving}
+ onCheckedChange={setEnabled}
+ className="data-checked:bg-foreground-success [&[data-checked]:not([data-disabled]):hover]:bg-foreground-success/85"
+ />
+ </div>
+ <p className="text-xs text-foreground-tertiary-passive">{TELEMETRY_REVERSIBLE}</p>
+ </DialogContentArea>
+ <DialogFooter>
+ <Button disabled={saving} onClick={confirm}>
+ Continue <Shortcut hotkey="Enter" variant="badge" />
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ </Dialog>
+ );
+}
+
+export default TelemetryConsentDialog;
diff --git a/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentGate.tsx b/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentGate.tsx
new file mode 100644
index 000000000..e478be747
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/telemetry/TelemetryConsentGate.tsx
@@ -0,0 +1,23 @@
+import React, { useCallback, useState } from 'react';
+import { useAppSettingsKey } from '@renderer/features/settings/use-app-settings-key';
+import { TelemetryConsentDialog } from './TelemetryConsentDialog';
+
+/**
+ * Shows the consent prompt on first run and nothing thereafter.
+ *
+ * `askedAt` flips as soon as the answer is saved, but the local flag closes the
+ * dialog on the answer itself rather than waiting for the settings query to
+ * come back, so Continue does not leave the prompt sitting there.
+ */
+export function TelemetryConsentGate() {
+ const { value, isLoading } = useAppSettingsKey('telemetry');
+ const [answered, setAnswered] = useState(false);
+
+ const onAnswered = useCallback(() => setAnswered(true), []);
+
+ if (isLoading || !value || answered || value.askedAt !== null) return null;
+
+ return <TelemetryConsentDialog onAnswered={onAnswered} />;
+}
+
+export default TelemetryConsentGate;
diff --git a/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts b/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts
new file mode 100644
index 000000000..9504873ff
--- /dev/null
+++ b/console/apps/switch-console-desktop/src/renderer/features/telemetry/telemetry-copy.ts
@@ -0,0 +1,25 @@
+/**
+ * The disclosure shown to the user, in one place so the first-run prompt and
+ * the Settings row cannot drift into promising different things.
+ *
+ * These lists are a promise, not a description of a feature that exists: the
+ * app sends nothing today. Whatever eventually does the sending is held to them
+ * by the payload rule in `console/AGENTS.md`. Widening them is a consent
+ * decision, not a copy edit.
+ */
+export const TELEMETRY_SUMMARY =
+ 'Switch Console can share anonymous usage data to show which features get used and where the app runs into trouble.';
+
+export const TELEMETRY_SHARED = [
+ 'Which features are used, and how often',
+ 'Errors and crashes the app hits',
+ 'App version and operating system',
+];
+
+export const TELEMETRY_NEVER_SHARED = [
+ 'Anything that identifies you or your machine',
+ 'Your prompts, code, files, or file paths',
+ 'Agent, room, project, or server names',
+];
+
+export const TELEMETRY_REVERSIBLE = 'You can change this at any time in Settings, under General.';
diff --git a/console/apps/switch-console-desktop/src/renderer/main.tsx b/console/apps/switch-console-desktop/src/renderer/main.tsx
index 41e8fb94f..223a20517 100644
--- a/console/apps/switch-console-desktop/src/renderer/main.tsx
+++ b/console/apps/switch-console-desktop/src/renderer/main.tsx
@@ -32,6 +32,7 @@ async function bootstrap() {
rpc.viewState.getAll(),
appState.locations.load(),
prefetchAppSettingsKey('interface'),
+ prefetchAppSettingsKey('telemetry'),
]);
viewStateCache.populate(allViewState as Record<string, unknown>);
diff --git a/console/apps/switch-console-desktop/src/shared/core/app-settings.ts b/console/apps/switch-console-desktop/src/shared/core/app-settings.ts
index 89011df36..ef9d71ac8 100644
--- a/console/apps/switch-console-desktop/src/shared/core/app-settings.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/app-settings.ts
@@ -9,6 +9,7 @@ import {
type locationSettingsSchema,
type providerCustomConfigEntrySchema,
type sessionSettingsSchema,
+ type telemetrySettingsSchema,
type terminalSettingsSchema,
type themeSchema,
} from '@main/core/settings/schema';
@@ -17,6 +18,7 @@ export type LocalLocationSettings = z.infer<typeof localLocationSettingsSchema>;
export type LocationSettings = z.infer<typeof locationSettingsSchema>;
export type NotificationSettings = z.infer<typeof notificationSettingsSchema>;
export type SessionSettings = z.infer<typeof sessionSettingsSchema>;
+export type TelemetrySettings = z.infer<typeof telemetrySettingsSchema>;
export type TerminalSettings = z.infer<typeof terminalSettingsSchema>;
export type Theme = z.infer<typeof themeSchema>;