# Cherry Studio ConfigManager Service: Complete Configuration Options Reference

> Explore Cherry Studio's ConfigManager service for 25+ typed configuration options. Discover settings for theme modes, tray behavior, quick assistant triggers, and developer flags.

- Repository: [CherryHQ/cherry-studio](https://github.com/cherryhq/cherry-studio)
- Tags: api-reference
- Published: 2026-02-27

---

**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`](https://github.com/cherryhq/cherry-studio/blob/main/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](https://github.com/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](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L27-L55)), 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](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L56-L63)) 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](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L96-L97)) 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](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L13-L28)). These allow other services and UI components to listen for specific key changes in real-time. The internal **`setAndNotify`** helper ([lines 63‑66](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L63-L66)) 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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/src/shared/config/constant.ts), while setters optionally notify subscribers.

```typescript
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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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`](https://github.com/cherryhq/cherry-studio/blob/main/src/shared/config/constant.ts)**: Defines default values such as `defaultLanguage` and `ZOOM_SHORTCUTS` consumed by the ConfigManager getters.
- **[`src/main/utils/locales.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/WindowService.ts) for tray management and [`constant.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L27-L55) of [`ConfigManager.ts`](https://github.com/cherryhq/cherry-studio/blob/main/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`](https://github.com/cherryhq/cherry-studio/blob/main/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](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/ConfigManager.ts#L63-L66)) 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.