Support system-wide (OS global) keybindings

[ulugbekna]

Why

Some workflows benefit from a keybinding that works even when VS Code does not have OS focus, for example a global shortcut to open or reveal the Agents window from anywhere. Today VS Code keybindings only fire when a VS Code window is focused.

What

Adds an opt-in "systemWide": true flag for entries in keybindings.json:

{
  "key": "ctrl+cmd+a",
  "command": "workbench.action.openAgentsWindow",
  "systemWide": true
}

When set, the shortcut is registered as an OS-global shortcut, so pressing it runs the command even while another application is focused.

Opt-in is per keybinding - there is no global on/off setting to flip. Any user keybinding that carries "systemWide": true is registered as a global shortcut. Because global shortcuts are captured OS-wide (they take the key combination away from other apps while VS Code is running), the first time such a binding is registered the user sees a one-time informational notice with a single "I Understand" button, so the behavior is never a surprise.

How it works

End to end: parse the flag, thread it through the resolved keybinding model, have a renderer contribution select the opted-in bindings and sync them to the main process over a new nativeHost IPC, and have a new main-process service own Electron's globalShortcut. On trigger, the service routes the command back into a window renderer via the existing vscode:runAction path.

Focus behavior

A system-wide shortcut fires while VS Code is typically unfocused, so the trigger deliberately does not pull the routing window to the foreground. The invoked command decides what to surface: openAgentsWindow, for instance, reveals and focuses the Agents window on its own, with no flicker of the main window.

For commands that surface UI in the current window (e.g. Quick Open) and therefore do want the window revealed, this PR also adds a generic workbench.action.focusWindow command that raises the current window using FocusMode.Force (works even when the app is not active). Users can compose it via runCommands:

{
  "key": "ctrl+cmd+p",
  "command": "runCommands",
  "args": { "commands": ["workbench.action.focusWindow", "workbench.action.quickOpen"] },
  "systemWide": true
}

Changes by area (suggested review order)

Review roughly top to bottom: shared contracts first, then parsing, then the renderer, then the main process, then trigger routing, then the focus command, then tests.

1. Shared contracts and data model

• platform/keybinding/common/keybinding.ts - adds systemWide?: boolean to IUserFriendlyKeybinding (the user-facing keybindings.json shape), documented as desktop-only and user-keybindings-only.
• platform/keybinding/common/resolvedKeybindingItem.ts - carries systemWide on ResolvedKeybindingItem as a new trailing constructor arg defaulting to false, so defaults and extension keybindings are never system-wide.
• platform/native/common/native.ts - new IPC contract: INativeSystemWideKeybinding (accelerator, commandId, args, label), INativeSystemWideKeybindingResult (failed[]), and syncSystemWideKeybindings(...) on the native host service.
• platform/window/common/window.ts - adds 'systemWideKeybinding' to the INativeRunActionInWindowRequest.from union.

2. Parsing and serialization (keybindings.json <-> model)

• workbench/services/keybinding/common/keybindingIO.ts - reads systemWide from JSON (defaults to false when absent/non-boolean) and writes it back out; adds the field to IUserKeybindingItem.
• workbench/services/keybinding/browser/keybindingService.ts - threads item.systemWide into both ResolvedKeybindingItem construction paths, and registers the systemWide property in the keybindings.json JSON schema (documented as desktop-only, single-combination-only, when ignored for the global trigger, with a one-time notice on first registration).

3. Renderer contribution (selection + sync)

• workbench/contrib/keybindings/electron-browser/systemWideKeybindings.contribution.ts - the core renderer logic. Exposes a pure selectSystemWideKeybindings() (filter opted-in bindings, translate to Electron accelerators, dedupe, drop unsupported chords with a warning), debounces syncing via a RunOnceScheduler, shows a one-time informational notice before the first registration (persisting an "acknowledged" flag in application storage so it appears only once), and calls nativeHostService.syncSystemWideKeybindings(...).
• workbench/workbench.desktop.main.ts - registers the contribution in the desktop workbench.

4. Main process (owns the OS globalShortcut)

• platform/globalKeybindings/electron-main/globalKeybindingsMainService.ts - the heart of the feature. Owns a per-window registry, registers/unregisters accelerators via an injected globalShortcut (IGlobalShortcutRegistry, for testability), resolves cross-window conflicts deterministically, returns labels that failed to register, and on trigger routes the command to a target window via sendWhenReady('vscode:runAction', ...). Cleans up on window destroy and shutdown.
• platform/native/electron-main/nativeHostMainService.ts - implements syncSystemWideKeybindings by forwarding to the service (keyed by the calling windowId).
• code/electron-main/app.ts - registers the service in DI, injecting Electron's globalShortcut as a constructor dependency.
• main.ts - enables Electron's GlobalShortcutsPortal feature on Linux so globalShortcut works under Wayland (no-op elsewhere).

5. Trigger routing (main -> renderer -> command)

• workbench/electron-browser/window.ts - handles from: 'systemWideKeybinding' in the vscode:runAction handler, running the command with exactly the configured args and intentionally not appending a { from } sentinel.

6. Focus behavior and the focusWindow command

• workbench/electron-browser/actions/windowActions.ts - adds FocusWindowAction (workbench.action.focusWindow) that raises the current window via hostService.focus(getActiveWindow(), { mode: FocusMode.Force }).
• workbench/electron-browser/desktop.contribution.ts - registers the new action.

7. Tests

• platform/globalKeybindings/test/electron-main/globalKeybindingsMainService.test.ts - registration, dedupe, cross-window conflict resolution, trigger payload/routing (asserts the routing window is not force-focused), and teardown on window close/shutdown.
• workbench/contrib/keybindings/test/electron-browser/systemWideKeybindings.test.ts - selectSystemWideKeybindings() filtering, args/when handling, chord rejection, and first-wins dedupe.
• workbench/services/keybinding/test/browser/keybindingIO.test.ts - round-trips the systemWide flag.
• workbench/services/keybinding/test/browser/keybindingEditing.test.ts - guards against data loss: editing one entry preserves systemWide on others.
• workbench/test/electron-browser/workbenchTestServices.ts - stub for the new native host method.

Notes for reviewers

• The feature is always active (any user keybinding with "systemWide": true); there is no enablement setting. The one-time informational notice makes the OS-global capture explicit before the first registration and is purely a heads-up, so there is no "off" state to get stuck in.
• Global shortcuts are a shared OS resource; the service resolves conflicts deterministically and unregisters on window close and shutdown.
• GlobalKeybindingsMainService takes Electron's globalShortcut as a constructor dependency so it stays unit-testable.
• Chorded bindings cannot be OS globals and are skipped with a warning; accelerator support follows Electron's globalShortcut capabilities.
• No new focusable UI surface is added (only a one-time informational notice dialog and a command palette entry), so no accessible-view work was required.

[Copilot]

Pull request overview

This PR adds experimental support for system-wide (OS global) keybindings on desktop by introducing an opt-in "systemWide": true flag in keybindings.json, syncing eligible shortcuts to the main process, and routing triggers back into a window via the existing vscode:runAction path.

Changes:

• Extend keybinding IO + resolved keybinding items to parse, persist, and carry a systemWide flag.
• Add a workbench contribution that selects/dedupes eligible system-wide bindings and syncs them to a new main-process global shortcut service.
• Introduce workbench.action.focusWindow (using FocusMode.Force) to support runCommands compositions for commands that need the window raised first.

Show a summary per file

File	Description
src/vs/workbench/workbench.desktop.main.ts	Loads the new system-wide keybindings renderer contribution in the desktop workbench entrypoint.
src/vs/workbench/test/electron-browser/workbenchTestServices.ts	Extends the test native host service with a stub for syncing system-wide keybindings.
src/vs/workbench/services/keybinding/test/browser/keybindingIO.test.ts	Adds tests for reading/writing/round-tripping the systemWide flag.
src/vs/workbench/services/keybinding/test/browser/keybindingEditing.test.ts	Adds a test ensuring editing preserves systemWide on unrelated entries.
src/vs/workbench/services/keybinding/common/keybindingIO.ts	Parses systemWide from user keybindings and writes it back only when true.
src/vs/workbench/services/keybinding/browser/keybindingService.ts	Threads systemWide into ResolvedKeybindingItem and exposes schema support in keybindings.json.
src/vs/workbench/electron-browser/window.ts	Adds a systemWideKeybinding run-action path that preserves positional args (no { from } sentinel).
src/vs/workbench/electron-browser/desktop.contribution.ts	Registers the new workbench.action.focusWindow action on desktop.
src/vs/workbench/electron-browser/actions/windowActions.ts	Implements FocusWindowAction using IHostService.focus(..., FocusMode.Force).
src/vs/workbench/contrib/keybindings/test/electron-browser/systemWideKeybindings.test.ts	Adds unit tests for renderer-side selection/dedupe/unsupported reporting.
src/vs/workbench/contrib/keybindings/electron-browser/systemWideKeybindings.contribution.ts	Implements the renderer contribution: gating setting, one-time confirmation, warnings, and nativeHost sync.
src/vs/platform/window/common/window.ts	Extends run-action request origin union to include systemWideKeybinding.
src/vs/platform/native/electron-main/nativeHostMainService.ts	Adds an IPC entrypoint to update per-window system-wide bindings via the new main service.
src/vs/platform/native/common/native.ts	Defines native DTOs + native host API for syncing system-wide keybindings.
src/vs/platform/keybinding/common/resolvedKeybindingItem.ts	Adds systemWide onto resolved keybinding items with a default of false.
src/vs/platform/keybinding/common/keybinding.ts	Extends IUserFriendlyKeybinding to include optional systemWide.
src/vs/platform/globalKeybindings/test/electron-main/globalKeybindingsMainService.test.ts	Adds main-process unit tests for registration, conflict resolution, routing, and teardown.
src/vs/platform/globalKeybindings/electron-main/globalKeybindingsMainService.ts	Introduces GlobalKeybindingsMainService to own Electron globalShortcut registration and route triggers to windows.
src/vs/code/electron-main/app.ts	Registers the new main-process global keybindings service and injects Electron’s globalShortcut.
src/vs/main.ts	Enables Electron’s Wayland global shortcuts portal feature flag on Linux.

Review details

• Files reviewed: 20/20 changed files
• Comments generated: 3
• Review effort level: Low

[vs-code-engineering]

📬 CODENOTIFY

The following users are being notified based on files changed in this PR:

@deepak1556

Matched files:

• src/vs/code/electron-main/app.ts