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

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 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. 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, 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 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 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. 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, 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, 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 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 supports user-defined entries with custom icons and internationalization keys.

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.

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 and SelectionToolbar.tsx.
• State management uses a dedicated Redux slice (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.
• Customization allows users to add, reorder, and disable actions through 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 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 cannot create the toolbar window or respond to selection events. The application displays 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, including enabled status, trigger mode, action list, filter lists, and UI preferences. The hook in 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.

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