Cherry Studio ConfigManager Service: Complete Configuration Options Reference

The ConfigManager service exposes 25+ typed configuration options—including theme modes, tray behavior, quick-assistant triggers, and developer flags—through a singleton wrapper around Electron Store in src/main/services/ConfigManager.ts.

The ConfigManager service serves as the central nervous system for Cherry Studio settings, managing both user preferences and system-level configurations. Located in the cherryhq/cherry-studio repository, this TypeScript service provides type-safe getters, setters, and reactive subscriptions for all application state, ensuring consistent access to persistent data across the main process.

Core Architecture of the ConfigManager Service

The ConfigManager implements a layered architecture built on Electron Store, providing typed access to persistent configuration through the ConfigKeys enum and a singleton instance.

The ConfigKeys Enum

At the heart of the service lies the ConfigKeys enum (lines 27‑55), which enumerates every supported configuration key as string constants. This enum ensures type safety throughout the application, preventing runtime errors from invalid key names. Each entry maps directly to an Electron Store key, creating a standardized vocabulary for all settings.

Store Wrapper and Singleton Pattern

The ConfigManager class (lines 56‑63) initializes a private Store instance in its constructor, configuring Electron's persistent storage with appropriate defaults. The service exports a single configManager singleton (lines 96‑97) that all modules import, ensuring consistent state across the application without multiple Store instances competing for file system access.

Reactive Subscriptions

Beyond simple storage, the service implements an observer pattern through subscribe and unsubscribe methods (lines 13‑28). These allow other services and UI components to listen for specific key changes in real-time. The internal setAndNotify helper (lines 63‑66) writes values to disk and triggers registered callbacks when isNotify is enabled, enabling reactive configuration updates without polling.

Complete List of Configuration Options

The ConfigManager service exposes 26 distinct configuration keys through the ConfigKeys enum, each accessible via dedicated getter and setter methods.

UI and Appearance Settings

• Language: UI locale (ISO language code) defaulting to the system locale or defaultLanguage from src/shared/config/constant.ts.
• Theme: Visual theme mode accepting light, dark, or system (defaults to ThemeMode.system).
• ZoomFactor: UI scaling factor as a number (defaults to 1).
• UseSystemTitleBar: Boolean flag to render the native OS title bar instead of custom Chrome (defaults to false).
• DisableHardwareAcceleration: Boolean to disable Electron hardware acceleration for compatibility (defaults to false).

System Tray and Window Behavior

• Tray: Boolean controlling whether the tray icon appears (defaults to true).
• TrayOnClose: Boolean keeping the tray icon active after closing the main window (defaults to true).
• LaunchToTray: Boolean starting the application minimized to tray instead of showing the main window (defaults to false).
• ClickTrayToShowQuickAssistant: Boolean enabling tray icon clicks to open the quick-assistant interface (defaults to false).

Quick Assistant Configuration

• EnableQuickAssistant: Master toggle for the quick-assistant feature (defaults to false).
• SelectionAssistantEnabled: Boolean enabling the selection-assistant text tool (defaults to false).
• SelectionAssistantTriggerMode: String enum determining activation method—either 'selected' (auto-trigger on text selection) or 'ctrlkey' (manual trigger) (defaults to 'selected').
• SelectionAssistantFollowToolbar: Boolean keeping the assistant window anchored to the toolbar (defaults to true).
• SelectionAssistantRemeberWinSize: Boolean persisting custom window dimensions between sessions (defaults to false).
• SelectionAssistantFilterMode: Filtering strategy for selected text, accepting 'default' or custom modes (defaults to 'default').
• SelectionAssistantFilterList: Array of strings defining blocked or allowed text patterns (defaults to []).

Updates, Telemetry, and Developer Tools

• AutoUpdate: Boolean enabling automatic update checks on startup (defaults to true).
• TestPlan: Boolean activating experimental features (defaults to false).
• TestChannel: Update channel selection (stable, beta, etc.) for test plan users.
• EnableDataCollection: Boolean controlling telemetry consent (defaults to true).
• EnableDeveloperMode: Boolean exposing developer-only UI elements and APIs (defaults to false).

Git Integration and Identity

• GitBashPath: Custom filesystem path to git-bash.exe for Windows environments.
• GitBashPathSource: Enum tracking how the Git path was set—manual, auto, or null.
• ClientId: Persistent UUID generated on first read to uniquely identify the installation.
• Proxy: Reserved configuration object for network proxy settings (currently unused).

Working with the ConfigManager API

All configuration options follow a consistent access pattern through the configManager singleton, with typed methods for each key.

Reading and Writing Values

Each configuration key exposes a getter method (e.g., getTheme()) and a setter method (e.g., setTheme()). Most getters call the generic get<T>() method with a sensible default defined in src/shared/config/constant.ts, while setters optionally notify subscribers.

import { configManager } from '@main/services/ConfigManager';

// Change UI language immediately
configManager.setLanguage('fr');

// Retrieve current theme with type safety
const currentTheme = configManager.getTheme(); // ThemeMode.light | .dark | .system

// Toggle system tray behavior
configManager.setLaunchToTray(true);

Subscribing to Configuration Changes

Services can react to runtime configuration changes without restarting the application by registering callback functions through the subscription API.

// React to hardware acceleration changes in real-time
configManager.subscribe<boolean>('disableHardwareAcceleration', (newValue) => {
  console.log('Hardware acceleration changed:', newValue);
  // Apply Electron app.disableHardwareAcceleration() here
});

// Later, when the setting is updated via UI or API
configManager.setDisableHardwareAcceleration(true); // triggers the subscriber

Unsubscribe using the returned callback or the explicit unsubscribe method to prevent memory leaks in destroyed components.

Selection Assistant Configuration Example

The selection assistant requires coordinated configuration of multiple related keys to function properly.

// Enable the feature and set manual trigger mode
configManager.setSelectionAssistantEnabled(true);
configManager.setSelectionAssistantTriggerMode('ctrlkey');

// Configure text filtering behavior
configManager.setSelectionAssistantFilterMode('custom');
configManager.setSelectionAssistantFilterList(['password', 'secret', 'token']);

// Verify current settings
const filters = configManager.getSelectionAssistantFilterList(); // string[]
const isFollowing = configManager.getSelectionAssistantFollowToolbar(); // boolean

Persistent Client Identification

The ClientId key automatically generates a UUID on first access, providing a stable identifier for telemetry or licensing without explicit initialization.

// Generates and persists UUID on first call, returns existing value thereafter
const clientId = configManager.getClientId(); 
console.log('Installation ID:', clientId);

Integration with Cherry Studio Services

The ConfigManager service integrates deeply with the application's architecture through several key files:

• src/shared/config/constant.ts: Defines default values such as defaultLanguage and ZOOM_SHORTCUTS consumed by the ConfigManager getters.
• src/main/utils/locales.ts: Maps Electron's system locale strings to the UI language codes used when initializing the Language key.
• src/main/services/WindowService.ts: Reads tray-related options (Tray, LaunchToTray, TrayOnClose) to control window lifecycle and system tray behavior according to user preferences.

This architecture ensures that configuration changes in the ConfigManager immediately propagate to window management, localization, and feature toggles throughout the application.

Summary

• The ConfigManager in src/main/services/ConfigManager.ts wraps Electron Store to provide typed, persistent configuration management for Cherry Studio.
• 26 configuration options are available through the ConfigKeys enum, covering UI themes, tray behavior, quick assistant settings, update channels, and developer tools.
• The service implements reactive subscriptions via subscribe() and setAndNotify(), allowing real-time configuration updates without application restarts.
• All options are accessible through a singleton instance with dedicated getter/setter methods (e.g., getTheme()/setTheme()), ensuring type safety and consistent defaults.
• Integration points include WindowService.ts for tray management and constant.ts for default value definitions.

Frequently Asked Questions

How do I add a new configuration option to Cherry Studio?

Define a new entry in the ConfigKeys enum at lines 27‑55 of ConfigManager.ts, then add corresponding getter and setter methods following the existing pattern (e.g., getNewOption() and setNewOption()). Include a default value in src/shared/config/constant.ts if applicable, and export the new methods in the class interface to maintain type safety across the application.

Can configuration changes trigger immediate UI updates without restarting Cherry Studio?

Yes. Use the configManager.subscribe<T>(key, callback) method to register a listener for specific configuration keys. When the value changes via setAndNotify() (which setters use internally), your callback receives the new value immediately. This powers live theme switching, hardware acceleration toggles, and quick-assistant visibility changes without requiring an application restart.

What is the difference between set() and setAndNotify() in the ConfigManager?

The ConfigManager exposes standard setters that internally call setAndNotify(). The setAndNotify() helper (lines 63‑66) writes the value to Electron Store and, when isNotify is true, triggers all registered subscribers for that key. Direct set() calls on the underlying Store instance bypass the notification system, so always use the ConfigManager's typed setters to ensure reactive updates propagate to other services.

Where are the configuration files physically stored on disk?

The ConfigManager delegates storage to the underlying Electron Store instance, which persists data according to Electron's app.getPath('userData') location. On Windows, this typically resolves to %APPDATA%/Cherry Studio/config.json; on macOS, ~/Library/Application Support/Cherry Studio/config.json; and on Linux, ~/.config/Cherry Studio/config.json. The exact path varies by operating system and installation method, but the ConfigManager abstracts these details through its typed API.

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