KE-complex_modifications: the shared rule library behind Karabiner-Elements

What KE-complex_modifications actually is, and who it is for

Karabiner-Elements can rewrite key events on macOS, but the rules that describe those rewrites have to come from somewhere. KE-complex_modifications is that somewhere: a repository of complex_modifications JSON, plus a build pipeline that turns generator scripts into the JSON files users import. The README describes the repository as bundling multiple rules into a single file so users can pick and enable what they need, and uses the Emacs key bindings package as the example of a file that contains several rule sets for different use cases.

The audience is narrow and specific. You need a Mac, you need Karabiner-Elements installed, and you need to be comfortable editing files and running make. Someone who only wants to swap two keys is not the target reader; the repository assumes you understand the difference between a rule and a manipulator, and that you can read JSON well enough to spot a malformed key_code. The distribution site at ke-complex-modifications.pqrs.org exists so that non-contributors can browse and enable rules without cloning anything, which is the part most users will actually touch.

How the JSON bundles and the generator build fit together

Every distributed file follows one shape. A top-level title, an optional maintainers array, and a rules array where each element is a single rule as defined in Complex Modifications. The README notes that listing GitHub usernames in maintainers makes the distribution site link to those accounts automatically, which is the only piece of contributor metadata the schema carries.

On the build side, the repository keeps two directories that matter. Generator files written in JavaScript go into src/json, and the generated or hand-written JSON lands in public/json. Running make all validates the files and, when a generator is present, produces the JSON in public/json. That split is the design decision worth noticing: the repository treats JSON as a build artifact rather than only as source, so a rule set that is tedious to write by hand can be generated, while a small rule can still be dropped straight into public/json.

Categories are handled separately in public/groups.json, where an entry pairs a path with an optional extra_description_path. That indirection is why a rule can exist in public/json and still be invisible on the site until groups.json points at it.

Installing KE-complex_modifications and testing your first rule

There is no package to install. The README's contribution flow is the closest thing to a setup guide, and it starts with a fork and a shallow clone that also pulls submodules. Replace the account placeholder with your own GitHub username.

git clone --depth 1 https://github.com/{your_account}/KE-complex_modifications.git
cd KE-complex_modifications
git submodule update --init --recursive --depth 1
git switch -c my-settings

After creating the branch, put a .js generator into src/json, or place a .json file directly into public/json. Then validate everything with make all. The README shows the failure output this produces, an error naming the file, the rule revision, and the offending entry, for example an unknown key_code such as "space". Fix the file until no errors appear.

make all

To try the rule in Karabiner-Elements itself, copy the generated file into the assets directory and import it from the app.

cp public/json/your_awesome_configuration.json ~/.config/karabiner/assets/complex_modifications

The README states that you then import rules from Karabiner-Elements Settings > Complex Modifications > Rules > Add rule. If you want to check how the rule looks on the distribution site before opening a pull request, make preview-server starts a local server and the README points you at http://localhost:8000. Note that HTML extra descriptions are not hot reloaded; the README says you must reload the page after editing.

Where the repository stops helping you

The most obvious limitation is platform. Karabiner-Elements is a macOS project, and nothing in this repository addresses Windows or Linux. If your team is mixed, this is not a shared configuration layer; it is a Mac-only one.

The second limitation is diagnostic. make all catches schema errors such as an unknown key_code, but the README does not describe any check that a rule behaves as intended on real hardware. A rule that validates can still conflict with another enabled rule, and the repository offers no conflict detection. The README is equally silent on rollback: there is no documented command to undo an imported rule set beyond removing it in the Karabiner-Elements interface. Treat the validation step as a syntax gate, not a correctness gate.

The third limitation is the build's dependency on a submodule. The clone instructions include git submodule update --init --recursive, and the sync section ends with an update submodules step. Skip either and the build can fail for reasons that have nothing to do with your JSON.

Finally, the README does not document versioning policy for the (rev XXX) suffix that appears in titles and descriptions. Contributors appear to bump it manually, which means a rule's revision number is a convention rather than something the tooling enforces.

Alternatives: hand-written Karabiner JSON versus a rule library

The real alternative is not another repository. It is writing complex_modifications directly into your Karabiner-Elements configuration without going through this project at all. The difference in approach is ownership: a personal configuration lives in one place and needs no build step, no submodule, and no pull request, but it also gets no validation beyond what Karabiner-Elements itself accepts, and no one else maintains it.

Choosing this repository means accepting a fork-and-PR workflow in exchange for shared review and a distribution site. The README's own contribution steps make the trade explicit: clone, branch, add a file, run make all, copy to the assets directory, test in the app, commit, push, open a pull request. If your rule is a private shortcut for one machine, that pipeline is more process than the rule deserves. If you want the rule to reach other users through ke-complex-modifications.pqrs.org, the pipeline is the point.

Maintenance, licensing and the cost of keeping a fork current

The repository carries the Unlicense, which places the code in the public domain. For anyone reusing rule JSON in their own projects, that removes the attribution and copyleft questions that a GPL or MIT project would raise. It does not, however, say anything about the Karabiner-Elements application itself, which is a separate project with its own terms; check that separately if you are redistributing anything beyond the rule files.

Upgrade cost is mostly the cost of staying in sync with upstream. The README documents the exact sequence for a fork: add the upstream remote once, then on each sync switch to main, fetch with --all --prune --prune-tags, reset hard to upstream/main, and update submodules. That reset is destructive to local commits on main, which is why the documented workflow puts your work on a branch such as my-settings rather than on main.

Because no last push date is available for this repository, there is no basis for a statement about how frequently it changes. Plan for the sync commands above rather than assuming a cadence.

Editorial conclusion

Adopt it if you already run Karabiner-Elements on macOS and want to enable rule sets from the distribution site or submit your own through a pull request. Do not adopt it if you expect a GUI editor for keyboard remapping, or if you are on Windows, where the repository offers nothing. Before relying on a rule, copy the JSON into ~/.config/karabiner/assets/complex_modifications, import it from Karabiner-Elements Settings > Complex Modifications > Rules > Add rule, and confirm that every key_code you depend on validates under make all.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository