karabiner-windows-mode gives a Mac the Ctrl and Alt keys Windows users expect

What the ruleset does and why Jsonnet

The project is a Karabiner-Elements complex ruleset whose purpose is to make using macOS friendlier by enabling common keyboard functionality used in Linux and Windows. The interesting engineering decision is the tool it is written in. It is powered by Jsonnet, and the README explains the benefit as allowing the main files that need to be interacted with, the .jsonnet and .libsonnet files, to be much shorter and far more readable. That matters more here than in an ordinary project. A Karabiner complex modification is a long JSON document listing input keys, output keys and conditions, and hand-writing one is tedious and error-prone. Generating it from a configuration language means the mapping tables in the README and the generated JSON cannot drift apart, because the JSON is rendered from the source rather than maintained by hand. The repository layout shows both halves side by side, with a jsonnet directory holding the sources, a json directory holding the rendered output, a Makefile, and the LICENSE.txt file.

Installing it from one URL

Installation is a single URL. You copy it into your browser window and Karabiner-Elements should ask to install the file.

karabiner://karabiner/assets/complex_modifications/import?url=https://raw.githubusercontent.com/rux616/karabiner-windows-mode/main/json/windows_shortcuts.json

The import points at the rendered JSON in the json directory of the main branch, which means you are installing the committed output rather than compiling anything locally. The karabiner scheme tells Karabiner-Elements which file to fetch and to ask for confirmation, so the flow is the same one you use for any other community complex modification. The source project is licensed under the Unlicense, which is a public-domain dedication rather than a conventional permissive licence with an explicit grant, and the primary language of the repository is Jsonnet. There are no GitHub releases, so the main branch is the distribution channel and the last push was on 2026-08-29.

The applications where the rules deliberately step aside

This is the part of the README that changes how you should read the rest of it. There are applications, such as hypervisors, IDEs, remote desktops and terminal emulators, that should receive raw inputs and handle them themselves. Almost all shortcuts no longer apply to these applications, and as a result the notes no longer specify that a specific shortcut does not apply to the excepted applications, since that is now the default state. Instead the notes say when a shortcut still applies. The generally excepted applications are listed in full. For hypervisors that is Oracle VirtualBox VMs, not the VirtualBox manager application, Parallels, and VMware Fusion. For IDEs it is GNU Emacs in its GUI form, all JetBrains products, Microsoft VSCode including Insiders, VSCodium, Sublime Text and Zed. For remote desktops it is the Chrome Remote Desktop app version rather than the in-browser one, Citrix XenAppViewer and Microsoft Remote Desktop Connection. For terminal emulators it is Alacritty, Hyper, iTerm2, Kitty, Terminal, WezTerm and Ghostty.

How shortcuts are named and which browsers are handled

The README explains the naming convention Karabiner-Elements uses for these shortcuts, which follows the pattern of key, then modifiers if any, then special notes if any. That is what makes the tables readable rather than a wall of key codes. There is also a separate list of web browsers, which is worth noticing because browsers are not in the excepted applications list. The browsers covered are Apple Safari, Brave Browser, Google Chrome, Microsoft Edge, Mozilla Firefox and Mozilla Firefox Nightly. The distinction matters when you are deciding whether a rule will interfere with a text field, since a browser is exactly where the shortcuts are likely to be wanted rather than avoided, while a terminal emulator is where they must not be rewritten.

The navigation and command mappings

The shortcut tables are the substance of the project, and they fall into groups. The navigation group covers the keys Windows and Linux users reach for. Home becomes Left Arrow with Command, Ctrl+Home becomes Up Arrow with Command, Shift+Home becomes Left Arrow with Command+Shift and Ctrl+Shift+Home becomes Up Arrow with Command+Shift. End mirrors that with Right Arrow and Down Arrow. Ctrl+Left Arrow and Ctrl+Right Arrow become Option+Left and Option+Right, with the Shift variants adding Shift, which is the macOS behaviour for word-wise text motion that most other platforms give you without a modifier. The command group is smaller: Ctrl+Backspace becomes Option+Backspace, Ctrl+Delete becomes Option+Delete, and Ctrl+Enter and Ctrl+Shift+Enter become Command+Enter and Command+Shift+Enter, which is how a Windows user expects a newline to behave. The Insert key gets two mappings, Ctrl+Insert to C with Command and Shift+Insert to V with Command, which is the paste-and-copy pair Windows users have in their fingers, and the table notes that only one of the two variants should be used, with the Ctrl variant marked as working in terminal emulators.

Modifier remapping and the build pipeline

The modifier group contains a single entry: the Win key with no modifiers produces Spotlight, and the note says it works in excepted applications. That is a small but opinionated choice, since it means the Windows key becomes a search key rather than being passed through. The build system is a Makefile with four targets, and the default runs check and format. The check target renders the Jsonnet sources to /dev/null, so it verifies that the sources compile and that the rendering does not fail, and the format target runs the project's jsonnet formatting script. There is also a render target that writes the output into the json directory, which is the directory the install URL points at. That means the checked-in JSON is a build product, and the render step is how it is regenerated, which is a cleaner arrangement than editing rendered files by hand. The scripts themselves live under .github/scripts, and the repository also carries a .vscode directory and an .editorconfig.

Where this ruleset is the wrong choice

Three limits. The first is that the rules are aggressive by design, and Karabiner-Elements is a system-wide input remapper, so a rule that fights an application can make it unusable rather than merely different. The exception list is the mitigation, but it is a hand-maintained list, and the README does not describe how it is verified, so an application that starts capturing keys differently after an update can break the rules without warning. The second is that installing from a URL means tracking the main branch, with no versioned tags and no release history in the repository, so you cannot pin a known-good version through the standard import URL. The third is that the ruleset only covers the key groups it lists. The visible tables cover navigation keys, command keys and modifier keys, with further sections for alphanumeric, punctuation and function keys, but the point stands that anything not in a table is untouched, so a shortcut you expected to be remapped may simply not be. For a user who wants a single obvious change, such as making Home and End behave like a PC, editing a small local Karabiner configuration is less machinery than importing a whole ruleset.

Editorial conclusion

Adopt karabiner-windows-mode if you move between macOS and Windows or Linux daily and want the Windows muscle memory on a Mac. Skip it if you are settled with the macOS layout or if you type in hypervisors, IDEs, remote desktops or terminal emulators, since those applications are excluded by default. Before you import it, read the exception list, because the rules deliberately step aside there and only a few shortcuts are marked as still applying.

Frequently asked questions

Official sources

1. Issues
2. License: Unlicense
3. README
4. rux616/karabiner-windows-mode on GitHub