How the Analytics Service Tracks User Behavior in Cherry Studio

Cherry Studio records user behavior, specifically AI token usage, through a privacy‑aware pipeline that routes data from the renderer process through a secure preload bridge to the main process, where an AnalyticsService validates user consent before transmitting metrics to an external AnalyticsClient.

Cherry Studio implements a sophisticated analytics service to track user behavior and monitor token consumption across AI model interactions. This TypeScript‑based Electron application uses a multi‑layered IPC architecture to collect usage metrics while ensuring user data remains isolated and controllable through explicit consent settings.

Architecture of the Analytics Pipeline

The analytics implementation spans four distinct layers across Electron’s process model. The pipeline begins in the renderer process where token usage is calculated, passes through the preload script for secure context bridging, and terminates in the main process where the AnalyticsService manages transmission to the external client.

Token Extraction in the Renderer Process

When an AI model streams a response, the utility at src/renderer/src/utils/analytics.ts extracts input and output token counts. This module supports both OpenAI‑style payloads and the AI‑SDK format, then determines a stable provider identifier—system providers use their configured ID, while custom providers use the hostname of their apiHost URL.

If the calculation yields any tokens, the utility calls the IPC‑exposed function window.api.analytics.trackTokenUsage (lines 50‑68):

// src/renderer/src/utils/analytics.ts (simplified)
if (inputTokens > 0 || outputTokens > 0) {
  window.api.analytics.trackTokenUsage({
    provider: getProviderTrackId(model.provider),
    model: model.id,
    input_tokens: inputTokens,
    output_tokens: outputTokens,
  })
}

Preload Bridge and IPC Communication

The preload script at src/preload/index.ts safely exposes the analytics API to the renderer while maintaining process isolation. It forwards the trackTokenUsage call to the main process via Electron’s ipcRenderer.invoke on the dedicated channel Analytics_TrackTokenUsage (lines 700‑701):

// src/preload/index.ts
trackTokenUsage: (data) => ipcRenderer.invoke(IpcChannel.Analytics_TrackTokenUsage, data)

Main Process Handling and Service Delegation

In the main process, src/main/ipc.ts registers a handler for the Analytics_TrackTokenUsage channel. When invoked, it delegates the payload to the singleton AnalyticsService (lines 44‑47):

// src/main/ipc.ts
ipcMain.handle(IpcChannel.Analytics_TrackTokenUsage, (_, data) => {
  analyticsService.trackTokenUsage(data)
})

The AnalyticsService at src/main/services/AnalyticsService.ts manages the lifecycle of the external client. It lazily initializes an AnalyticsClient from the @cherrystudio/analytics-client package only when the user has explicitly enabled data collection. The trackTokenUsage method simply forwards the data to client.trackTokenUsage (lines 34‑36):

// src/main/services/AnalyticsService.ts
trackTokenUsage(data: TokenUsageData) {
  this.client?.trackTokenUsage(data)
}

Privacy Controls and User Consent

The analytics service respects user privacy through explicit opt‑in controls. Before initializing the AnalyticsClient, the service checks configManager.getEnableDataCollection(). When this setting is disabled, the service logs a message and never instantiates the client, ensuring zero data transmission (lines 20‑23):

// src/main/services/AnalyticsService.ts
if (!configManager.getEnableDataCollection()) {
  console.log('[Analytics] Data collection is disabled')
  return
}

This architecture ensures that Cherry Studio can reliably capture token consumption metrics per provider and model without exposing personal data or violating user consent preferences.

Summary

• Cherry Studio tracks user behavior through a four‑layer pipeline spanning renderer, preload, main process, and external analytics client.
• Token usage extraction occurs in src/renderer/src/utils/analytics.ts, supporting both OpenAI and AI‑SDK response formats.
• The preload bridge at src/preload/index.ts securely forwards data via the Analytics_TrackTokenUsage IPC channel.
• The main process handler in src/main/ipc.ts delegates to AnalyticsService, which manages the @cherrystudio/analytics-client lifecycle.
• Privacy is enforced through configManager.getEnableDataCollection(); when disabled, the client never initializes and no data leaves the device.

Frequently Asked Questions

How does Cherry Studio determine which AI provider sent the tokens?

Cherry Studio uses a stable identifier generated in src/renderer/src/utils/analytics.ts. For system providers, it uses the provider’s configured ID. For custom providers, it extracts and uses the hostname from the provider’s apiHost URL. This ensures consistent tracking regardless of how the provider was configured.

What specific user behavior does Cherry Studio currently track?

Currently, Cherry Studio tracks token usage metrics only. Specifically, it records the number of input tokens sent to and output tokens received from AI models, along with the provider and model identifiers. The architecture supports future expansion, but the current implementation focuses exclusively on consumption analytics.

Can users disable analytics tracking in Cherry Studio?

Yes. Users can disable analytics through the application settings. When configManager.getEnableDataCollection() returns false, the AnalyticsService in src/main/services/AnalyticsService.ts logs that data collection is disabled and never initializes the external AnalyticsClient. This ensures zero telemetry leaves the user’s device.

Where does the analytics data ultimately get sent?

The data is transmitted to Cherry Studio’s analytics backend via the external @cherrystudio/analytics-client package. The AnalyticsService acts as a thin wrapper that forwards the token usage payload to this client, which then handles the network transmission and backend ingestion. The specific endpoint and protocol details are encapsulated within the external client package.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}