HyperKey PowerToys Command Palette Extension

A PowerToys Command Palette extension that adds HyperKey functionality to Windows. It allows you to use your CapsLock key as a powerful modifier key that simulates holding down Ctrl + Shift + Alt + Win.

---

Features

• HyperKey Modifier: Hold the configured modifier key and press any other key to trigger shortcuts bound to the remapped chord.
• Customizable Modifier Key: Choose the activation key from standard options like Caps Lock, Left/Right Ctrl, Left/Right Shift, Left/Right Alt, Left/Right Win, function keys F1 through F12, or None (effectively disabled).
• Include Shift Key Option: Toggle whether the simulated modifier chord includes the Shift key.
• Quick Press (Original Function): Press and release the modifier key quickly (within 300 ms) to toggle or trigger its original function (e.g., toggling capitalization lock for Caps Lock, or sending a standard keypress for other keys).
• Dynamic Command Palette Toggle: A single "Activate/Deactivate HyperKey" command within the PowerToys Command Palette manages the hook.
• Isolated Hook Process: Runs in a dedicated background STA thread within the extension COM out-of-process server, keeping the PowerToys process clean and responsive.
• Zero Orphaned Hooks: The keyboard hook is automatically unregistered upon extension disposal or unloading.

---

Configuration & Settings

You can configure HyperKey settings directly within the PowerToys Command Palette extension settings manager:

• Modifier Key: Choose which key acts as the HyperKey.
  • Options include: None (effectively disabled), Caps Lock (⇪) (default), standard modifiers (Ctrl, Shift, Alt, Win for left/right keys), and function keys (F1 through F12).
  • Fallback: If settings are empty, Caps Lock is selected.
• Include shift key: Toggles whether the simulated modifier chord includes the Shift key (emulates Ctrl + Shift + Alt + Win when enabled, or Ctrl + Alt + Win when disabled).
  • Default: Enabled (true).

---

How It Works

Architecture

The extension is built on top of the Microsoft Command Palette Extensions SDK and runs as an out-of-process WinRT COM server.

┌─────────────────────────────────┐
│     PowerToys Command Palette   │
└────────────────┬────────────────┘
                 │ (WinRT COM IPC)
┌────────────────▼────────────────┐
│   HyperKey COM Server Process   │
│  ┌───────────────────────────┐  │
│  │    Extension Page & UI    │  │
│  └───────────────────────────┘  │
│  ┌───────────────────────────┐  │
│  │   HyperKey Hook Thread    │  │
│  │   - WH_KEYBOARD_LL        │  │
│  │   - STA Message Pump      │  │
│  └───────────────────────────┘  │
└─────────────────────────────────┘

Low-Level Hook (WH_KEYBOARD_LL)

1. Activation: When "Activate HyperKey" is invoked, the extension starts a dedicated background thread configured with a Win32 message loop (GetMessage) and registers a low-level keyboard hook.
2. Press Interception: When CapsLock is pressed down, the hook swallows the keypress, records the start time, and uses SendInput to simulate key downs for Left Ctrl, Left Shift, Left Win, and Left Alt.
3. Release Interception: When CapsLock is released, the hook releases the simulated modifier keys. If the press duration was under 300 ms and no other keys were pressed, a simulated Caps Lock key cycle (down/up) is sent to toggle standard capitalization lock.
4. Recursion Prevention: Simulated keystrokes sent by the extension are flagged with a unique signature in dwExtraInfo. The hook intercepts these and passes them along directly to avoid recursive loops.

---

Getting Started

Prerequisites

• Windows 10 or 11
• .NET 10 SDK
• PowerToys (with Command Palette enabled)

Build and Run

1. Open the solution in Visual Studio or your preferred C# IDE, or use the .NET CLI:

   dotnet build

2. To compile and generate MSIX packages for publish/sideloading (both x64 and ARM64 configurations), run the provided PowerShell script from the root folder:

   .\buildForPublish.ps1

3. Build and deploy the project. (To register the COM server, ensure the MSIX package is deployed or run in development mode).
4. Open the Command Palette in PowerToys.
5. Search for and select "Reload Command Palette extensions".
6. Locate the "HyperKey for CommandPallete" page to activate the hook.