KeySwitch User Manual

Quick start

Open KeySwitch and select Bind app.
Search for and select an app. You do not need to enter its executable path.
Select the shortcut recorder and press a combination such as Alt + W.
Choose Toggle or Always activate, then save.

You can also add several apps at once from the app list, taskbar, or currently running apps.

While recording, KeySwitch checks before saving whether the shortcut belongs to another app binding, is reserved, or is already used by another program. A conflict identifies the assigned app or occupancy source and keeps the previous shortcut unchanged.

Switching behavior

A shortcut immediately launches, activates, or toggles its target; you do not need to release Alt, Ctrl, Shift, or Win first. KeySwitch never joins the target application's input thread; after the modifiers are released it only clears residual menu state for the current target and does not switch the window again.

Multiple windows of the current app

Enable or disable it from the prominent Switch windows of the current app card on the first General screen. The card shows the shortcut and scope directly. It is enabled by default and pauses with the global hotkey master switch.
Press `Alt + `` to cycle through valid windows of the foreground app without creating an app binding.
Windows follow a stable most-recently-used order. Completing a cycle returns to the first window and never hides the app.
Current desktop includes only normal main windows on this desktop. Across desktops includes every desktop and first activates a remote window on its original desktop, moving it to the current desktop only if activation fails.
Both scopes exclude developer tools, popups, tool windows, and auxiliary windows. Scope changes apply immediately and persist across restarts.
Nothing happens when only one valid window exists. A selected minimized window is restored and activated.
This feature never launches or hides an app and does not change window position, size, or maximized state. It follows the Enable global hotkeys setting.
`Alt + `` is reserved by KeySwitch and cannot be assigned to an individual app.

Toggle

One-window apps are hidden when active and restored with the same shortcut.
Multi-window apps cycle in most-recently-used order, then hide all valid windows at the end of the cycle.
For apps with a D3D input host and a tray companion, KeySwitch selects a safe Toggle path by window framework. Chromium top-level windows let the app hide and wake itself, while Qt shells keep the original handle and use a full window restore instead of a normal show operation.
KeySwitch does not move or resize windows or change their normal geometry.
If every app window is minimized, the shortcut restores the most recently used window.

Always activate

Starts the app when it is not running.
Activates the most recently used valid window when the app is running.
Repeated shortcuts do not intentionally hide the window.

Virtual desktops

Each binding has its own desktop scope:

Follow app switches only windows on the current desktop. When none exist, the app decides whether to reuse or create a window.
Reuse globally finds windows across desktops and moves the selected window to the current desktop.
Current desktop only uses windows on the current desktop and sends a new-window launch request when none exist. Apps such as VS Code can use --new-window.

KeySwitch does not bypass an app's own single-instance policy.

App updates

For WindowsApps and MSIX apps, KeySwitch uses Package Family and AUMID identity to repair obsolete version paths. Updating an app normally does not require rebinding its shortcut.

Appearance, language, and general settings

Appearance supports system, light, and dark themes, accent colors, and compact layout.
General settings include global hotkeys, startup, close-to-tray behavior, the switching overlay, and the tray icon.
Display language can follow Windows or be set to Simplified Chinese, Traditional Chinese, English, Japanese, Korean, French, German, Spanish, Brazilian Portuguese, or Russian. Changes apply immediately and are saved automatically.
The interface and installer are fully localized in all ten languages. The full manual is currently maintained in Chinese and English; non-Chinese interfaces open this English manual.

Usage

Usage records total invocations, the last seven days, and per-app shares. Data stays on this device. KeySwitch does not record normal keyboard input or window content.

License and trial

The About page combines product information, licensing, help, diagnostics, and privacy. Its license area shows the current plan, status, benefits, account, license or trial expiration, and device limit without showing remaining offline days or an offline deadline.
Free includes up to 5 app bindings, standard desktop mode, and 7-day usage. Version 0.23.3 is in entitlement preview mode, so exceeding Free benefits shows a notice without disabling existing shortcuts or configuration.
Each email account can claim one 14-day Pro trial in the license portal. The current client recognizes Pro benefits for unlimited bindings, advanced virtual desktops, and full usage. Configuration backup, profiles, rules, and sync are planned and are not yet available.
Sign in to the portal with an email code, generate a one-time activation code valid for 10 minutes, then activate it in the client. Each account has only one valid activation code at a time; generating a new code from any Trial or Pro license immediately replaces every unused code. A license allows 3 devices by default.
The client refreshes every 24 hours while online. While an offline license remains valid, the client continues using the latest signed benefits and shows the normal Active status; it does not display an offline-grace label, remaining days, or a deadline.
The activation-code area is shown only while the client is not activated. It disappears after activation and returns after deactivation. The license service address is built into the client and has no editable UI or user setting.
Deactivate a device in the client or on the portal's Devices page before moving to another device. Payment, pricing, and web purchasing are not connected yet; administrators currently issue Pro licenses.
If an administrator lowers the device limit, the most recently connected devices retain access first. Older devices beyond the limit show Device limit on their next refresh; shortcuts and configuration are not deleted.
Administrators can search for an ordinary user on the portal's Admin page and select Impersonate. A persistent banner shows both the target account and original administrator, and only ordinary user features are available until Return to administrator is selected. Starting, stopping, and write requests made while impersonating are audited; administrator accounts cannot impersonate one another.
Production license services require HTTPS. Plain HTTP is accepted only for local localhost and 127.0.0.1 development.
If the local license file is damaged or cannot be verified, the License page shows Verification failed and does not grant Pro benefits. Activate again with a newly generated portal code to recover; existing shortcuts and app configuration are preserved.
Frequent sign-in, activation, or refresh requests may be temporarily rate limited. Wait one minute before retrying instead of submitting repeatedly.

Troubleshooting

A shortcut does not respond

Confirm that the binding and global hotkeys are enabled.
Check whether another program owns the same shortcut.
Open diagnostics from General settings and inspect the matching HOTKEY, LOOKUP, ACTIVATE, or ERROR entry.

An updated app no longer starts

KeySwitch repairs stable app identity on the first shortcut invocation. If it still fails, refresh the app cache and inspect PACKAGE_IDENTITY_REPAIRED or the related error.

An app opens on multiple virtual desktops

Set that app to Reuse globally. Existing duplicate windows are not closed automatically, but subsequent shortcuts reuse a matching window.

A window cannot be clicked after Toggle

For apps with a D3D input host and a tray companion, KeySwitch selects a safe restore path so a normal show operation cannot break input routing. Chromium top-level windows manage their own hide and restore sequence. Embedded Chromium hosted by a Qt shell keeps the original handle and uses a full window restore to rebuild its input state. If an older KeySwitch version has already left the process unclickable, fully exit and reopen that app once. Subsequent Toggle cycles should respond to the first click after restore. If the issue persists, keep the app open and inspect the diagnostics before changing the binding.

Local data

Settings: %APPDATA%\KeySwitch\settings.json
Cache: %LOCALAPPDATA%\KeySwitch\Cache
Diagnostics: %LOCALAPPDATA%\KeySwitch\switch.log
Local license: %APPDATA%\KeySwitch\license.dat (encrypted with DPAPI for the current Windows account)
Installation: %LOCALAPPDATA%\Programs\KeySwitch\Active

Uninstalling KeySwitch does not automatically delete user settings or usage data.