# Selection Assistant in Cherry Studio: AI-Powered Text Actions Explained

> Discover Cherry Studio's Selection Assistant, your AI-powered toolbar for instant text actions like translation and summarization directly within any window.

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

---

**The Selection Assistant is a floating, always-on-top toolbar that appears when you select text in any window, allowing instant AI-powered actions like translation, summarization, or custom workflows.**

The **Selection Assistant** is a core productivity feature in the [cherryhq/cherry-studio](https://github.com/cherryhq/cherry-studio) repository that bridges the gap between system-wide text selection and AI processing. Unlike traditional copy-paste workflows, this feature creates a frameless Electron window that dynamically positions itself near your cursor, offering immediate access to language models without switching applications. It is currently implemented for Windows and macOS platforms only, with Linux support disabled due to platform limitations.

## Architecture of the Selection Assistant

The implementation spans both the renderer and main processes of the Electron application, utilizing a Redux-backed state management system and IPC bridges for cross-process communication.

### Configuration Layer

The settings interface is defined in [`src/renderer/src/pages/settings/SelectionAssistantSettings/SelectionAssistantSettings.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/pages/settings/SelectionAssistantSettings/SelectionAssistantSettings.tsx). This component renders switches for enabling the assistant, radio buttons for trigger modes, sliders for opacity control, and advanced filter lists for application whitelisting. All UI controls bind to the Redux store through the `useSelectionAssistant` hook, ensuring immediate synchronization between the settings page and the active toolbar.

### State Management

Persistent configuration lives in [`src/renderer/src/store/selectionStore.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/selectionStore.ts), which defines the `SelectionState` interface. This slice stores the enabled flag, trigger mode (selection vs. shortcut), compact UI preference, filter mode, opacity level, and the action item list. Reducers such as `setSelectionEnabled` and `setTriggerMode` handle state mutations, while default actions for translation and summarization are pre-populated in the initial state.

### IPC Bridge and Hooks

The [`src/renderer/src/hooks/useSelectionAssistant.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/hooks/useSelectionAssistant.ts) hook serves as the primary interface for components. Each setter method performs dual updates: it dispatches Redux actions to update local state **and** invokes `window.api.selection` methods to forward changes to the main process. For example, calling `setSelectionEnabled(true)` updates the store and simultaneously triggers the IPC bridge to create or destroy the toolbar window in the main process.

### Main Process Service

[`src/main/services/SelectionService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/main/services/SelectionService.ts) manages the lifecycle of the toolbar window. Key methods include `toggleEnabled()` for activation, `createToolbarWindow()` for initialization, and `showToolbarAtPosition()` for dynamic positioning relative to text selections. The service listens for IPC calls from the renderer and synchronizes state changes across all open windows using the `storeSyncService`.

### Toolbar Window

The floating interface is a frameless, transparent `BrowserWindow` defined in [`src/renderer/src/windows/selection/toolbar/SelectionToolbar.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/windows/selection/toolbar/SelectionToolbar.tsx). It is configured as always-on-top and uses platform-specific display methods: on Windows, it appears without stealing focus, while macOS utilizes `showInactive()` to prevent window activation. The component renders action buttons based on the `actionItems` array stored in the Redux state.

### Action Execution

When a user clicks an action button, the toolbar sends an IPC request back to the main process. `SelectionService` routes this to the appropriate AI core plugin (defined in `packages/aiCore`) without exposing implementation details to the selection feature. The action list is rendered by [`SelectionActionsList.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionActionsList.tsx), which supports reordering, enabling/disabling, and custom icon mapping through the `ActionItem` interface.

## Platform Support and Accessibility Requirements

The Selection Assistant is conditionally compiled for Windows (`win32`) and macOS (`darwin`) platforms only. In [`SelectionAssistantSettings.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionAssistantSettings.tsx), Linux users see a disabled state message explaining the platform limitation.

On macOS, the feature requires a trusted accessibility process to detect text selections system-wide. If the process lacks accessibility permissions, [`MacProcessTrustHintModal.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/MacProcessTrustHintModal.tsx) displays a modal explaining how to grant permissions through System Settings. Without these rights, the toolbar cannot detect text selection events or position itself relative to the cursor.

## Customizing Selection Assistant Actions

Users can extend the toolbar beyond built-in translation and summarization features by defining custom action items. The action list stored in [`selectionStore.ts`](https://github.com/cherryhq/cherry-studio/blob/main/selectionStore.ts) supports user-defined entries with custom icons and internationalization keys.

```typescript
import { useSelectionAssistant } from '@renderer/hooks/useSelectionAssistant'
import type { ActionItem } from '@renderer/types/selectionTypes'

function AddCustomAction() {
  const { actionItems, setActionItems } = useSelectionAssistant()

  const addAction = () => {
    const customAction: ActionItem = {
      id: 'my-custom-action',
      name: 'selection.action.custom.myCustom', // i18n key for localization
      enabled: true,
      isBuiltIn: false,
      icon: 'sparkles',
    }
    setActionItems([...actionItems, customAction])
  }

  return <button onClick={addAction}>Add Custom Action</button>
}

```

Each action item requires a unique identifier, display name key, enabled status, built-in flag, and icon reference. Changes persist through the Redux store and sync immediately to the toolbar window via the IPC bridge.

## Programmatically Controlling the Selection Assistant

Developers integrating with Cherry Studio can toggle the assistant programmatically using the `useSelectionAssistant` hook, which handles both state updates and window management.

```typescript
import { useSelectionAssistant } from '@renderer/hooks/useSelectionAssistant'

function ToggleSelectionAssistant() {
  const { selectionEnabled, setSelectionEnabled } = useSelectionAssistant()

  const enableAssistant = async () => {
    // Verify platform compatibility before enabling
    if (process.platform === 'win32' || process.platform === 'darwin') {
      await setSelectionEnabled(true)
      // Updates Redux state and calls window.api.selection.setEnabled
    }
  }

  return (
    <button onClick={enableAssistant} disabled={selectionEnabled}>
      Enable Selection Assistant
    </button>
  )
}

```

This pattern ensures that the floating toolbar window is created in the main process only when the platform supports it and the user has granted necessary permissions.

## Summary

- The **Selection Assistant** creates a system-wide floating toolbar for instant AI actions on selected text, implemented in [`SelectionService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionService.ts) and [`SelectionToolbar.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionToolbar.tsx).
- **State management** uses a dedicated Redux slice ([`selectionStore.ts`](https://github.com/cherryhq/cherry-studio/blob/main/selectionStore.ts)) with the `useSelectionAssistant` hook bridging renderer and main processes via IPC.
- **Platform support** is limited to Windows and macOS; macOS requires accessibility permissions managed through [`MacProcessTrustHintModal.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/MacProcessTrustHintModal.tsx).
- **Customization** allows users to add, reorder, and disable actions through [`SelectionActionsList.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionActionsList.tsx), with configurations persisting through the Redux store.
- **Architecture** separates concerns between settings UI, state management, IPC communication, and the frameless toolbar window for maintainable cross-platform support.

## Frequently Asked Questions

### Is Selection Assistant available on Linux?

No, the Selection Assistant is explicitly disabled on Linux. The codebase checks `process.platform` and only enables the feature for Windows (`win32`) and macOS (`darwin`). Users on Linux will see a disabled message in the settings interface, as the system-level text selection detection and always-on-top window behaviors required by the feature are not supported on that platform.

### How do I add custom actions to the Selection Assistant toolbar?

Custom actions can be added through the `setActionItems` method exposed by `useSelectionAssistant`. You must construct an `ActionItem` object with a unique ID, internationalization key for the display name, icon identifier, and `isBuiltIn: false` flag. These custom actions appear alongside built-in options in [`SelectionActionsList.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionActionsList.tsx) and execute through the same IPC routing mechanism to the AI core.

### Why does the Selection Assistant require accessibility permissions on macOS?

macOS requires trusted accessibility processes to detect text selection events in other applications and to position the floating toolbar window relative to the cursor. Without these permissions, [`SelectionService.ts`](https://github.com/cherryhq/cherry-studio/blob/main/SelectionService.ts) cannot create the toolbar window or respond to selection events. The application displays [`MacProcessTrustHintModal.tsx`](https://github.com/cherryhq/cherry-studio/blob/main/MacProcessTrustHintModal.tsx) to guide users through granting these permissions in System Settings when the accessibility check fails.

### Where is the Selection Assistant configuration stored?

Configuration persists in the Redux store defined in [`src/renderer/src/store/selectionStore.ts`](https://github.com/cherryhq/cherry-studio/blob/main/src/renderer/src/store/selectionStore.ts), including enabled status, trigger mode, action list, filter lists, and UI preferences. The hook in [`useSelectionAssistant.ts`](https://github.com/cherryhq/cherry-studio/blob/main/useSelectionAssistant.ts) synchronizes these values to the main process via `window.api.selection` IPC calls, ensuring the `SelectionService` maintains the current state across window reloads and application restarts.