CLI tool
pqrs-org/KE-complex_modifications avatar
pqrs-org/KE-complex_modifications

KE-complex_modifications: the rule repository behind the Karabiner-Elements import site

Karabiner-Elements complex_modifications rules. For example, the "Emacs key bindings" package includes several rule sets for different use cases.

1,485 stars1,166 forksJavaScriptUnlicense

At a glance

What is it?
KE-complex_modifications is the Unlicense repository of complex_modifications rules for Karabiner-Elements, published through a distribution site. This analysis covers its three rule formats, the 16.2.0 compatibility cutoff, the build output paths and the pull request workflow.
Who is it for?
Use this repository if you want a ready rule to import into Karabiner-Elements or if you want to publish your own rule through a pull request. Do not expect it to teach the manipulator syntax or to give you a version to pin, because the reference manual lives on the Karabiner-Elements site and the repository has no GitHub releases.
Can I use it commercially?
Yes. Unlicense is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pqrs-org/KE-complex_modifications1,485 ★ · +9
Star history
Repository2026-08-022026-11-15
pqrs-org/KE-complex_modifications1.5k1.5k

9 Stars in the last 105 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Rules arrive in three file shapes, and only one of them reaches users

A contributor can submit a rule in any of three forms. The first is a JSON ruleset with title and rules, placed under public/json. The second is a JSON file holding one rule, meaning a description and a manipulators array, also under public/json. The third is a JavaScript file under public/js whose final expression returns one rule. The distribution side is simpler than the input side. A single JSON rule is replaced by its ruleset form at the same distribution path, so only one distributed JSON file exists per rule. The build maps public/json/example.json to dist/json/example.json and public/js/example.js to dist/js/example.js. For JavaScript sources, the generated ruleset JSON is written next to the source as dist/js/example.ruleset.json. The consequence for a contributor is that what you write is not necessarily what a user downloads. If you submit a single rule, the file that people import is the converted ruleset, and any comparison against your original has to account for that wrapping.

Karabiner-Elements 16.2.0 is the line between direct import and converted import

Karabiner-Elements 16.2.0 and later can import single rule JSON and JavaScript directly. Versions up to 16.1.0 cannot, so the build also converts those sources into the title and rules ruleset format, using the rule's description as the ruleset title. This conversion is the reason the repository can accept the shorter formats at all without leaving older installations behind. It also has a cost for JavaScript rules. The distribution site's import menu offers two actions, Import JavaScript code and Import JSON compatible with Karabiner-Elements 16.1.0 or earlier, and it can display the generated JSON with Show compatible JSON or copy its URL with Copy compatible JSON URL. Single JSON rules get no such pair of actions. The site imports the converted file directly and does not provide a separate compatible JSON action for them. If you maintain machines on mixed Karabiner-Elements versions, the choice of which menu item to use depends on the version installed on each machine, and choosing wrongly gives you an import that the older app cannot read.

A JSON ruleset bundles rules so users can switch pieces on and off

The ruleset format exists for packages with several related behaviors. The example used throughout the repository is Emacs key bindings, where separate rules cover different use cases, so a user enables the control-key set without taking the option-key set. Each element under rules is a single rule as Complex Modifications defines it, with a description and a manipulators array. Titles and descriptions in the sample carry a revision marker in the form (rev XXX), for example Emacs key bindings [control+keys] (rev XXX). A maintainers field accepts GitHub usernames, such as tekezo in the sample, and the distribution site links those names to their accounts. That attribution is the only metadata the sample shows at ruleset level. The limit to know about is the boundary between formats: JSON ruleset objects containing title and rules are not supported under public/js. If your rules need helper functions and also need bundling, you cannot get both in one file, because JavaScript sources must return a single rule and bundling requires the JSON ruleset form.

A single JSON rule is the smallest thing you can contribute

When a package only needs one behavior, the object that would normally sit inside rules can be saved directly. The sample is a rule that turns caps lock into escape:

json
{
    "description": "Change caps_lock to escape",
    "manipulators": [
        {
            "type": "basic",
            "from": { "key_code": "caps_lock" },
            "to": [{ "key_code": "escape" }]
        }
    ]
}

Optional attribution fields such as maintainers and author can be placed in the same object, and the build moves them to the ruleset level. The from block names the physical key by key_code and the to array lists what is sent. Nothing in this file says how modifiers, conditions or multiple outputs are expressed. For those, the manipulator definition page on the Karabiner-Elements site is the reference, along with its page of typical complex_modifications examples. The practical effect is that this repository is a place to put a rule you already know how to write, not a place to learn the syntax.

JavaScript rules must be ECMAScript 5.1 and return a single value from the last line

JavaScript is offered for rules that repeat the same definition many times, because helper functions can live in the same file. The sample remaps h, j, k and l to the arrow keys through a makeManipulator helper:

js
// JavaScript must be written in ECMAScript 5.1.

function main() {
  return {
    description: 'Change h/j/k/l to arrow keys',
    manipulators: [
      makeManipulator('h', 'left_arrow'),
      makeManipulator('j', 'down_arrow'),
      makeManipulator('k', 'up_arrow'),
      makeManipulator('l', 'right_arrow'),
    ],
  }
}

function makeManipulator(from, to) {
  return {
    type: 'basic',
    from: { key_code: from },
    to: [{ key_code: to }],
  }
}

main()

Two rules in that file are easy to miss. The build uses the value of the last JavaScript expression, which is why main() is called on the final line, and standard output from the script is ignored, so console style debugging shows nothing. The ECMAScript 5.1 requirement means you write older syntax, with function declarations and no newer language features. When you register such a file in public/groups.json, the path is js/example.js.

The dist.json index holds metadata for search and leaves manipulators in the rule files

The build also produces a dist.json index. It carries lightweight metadata used for display and search on the distribution site, while the full manipulators stay in the distributed JSON files and are not duplicated in the index. This split keeps the index small, since a site listing many packages does not need every key mapping to render a search result. It also means that a rule file and its index entry are two separate outputs, so a change to a rule's description or attribution only shows up after the build regenerates both. The Makefile in the repository root forwards four targets to the core directory: all, rebuild, update-dist and preview-server, each run as make -C core with the matching target name. The core directory is declared in .gitmodules, which explains why the clone steps in the contribution guide include a submodule update. If you only want to read or copy a rule, you do not need any of this. If you want to see how your file will appear before opening a pull request, preview-server is the target whose name points at that purpose.

Adding a rule means a fork, a shallow clone with a submodule, and a branch

The contribution path starts with forking the repository on GitHub. The clone is shallow and pulls in the submodule in the same session:

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

Then create a branch:

shell
git switch -c my-settings

Put a JSON file into public/json or a JavaScript file into public/js. A JSON file can hold a full ruleset or a single rule, and a JavaScript file must return a single rule. Existing generator files in src/json are still supported, but their names must end in .json.js, and the generated JSON is written to public/json as before. Placement in a category is optional. To add your rules to a particular category, add an entry to public/groups.json:

json5
{
    "path": "json/your_awesome_configuration.json", // required
    "extra_description_path": "extra_descriptions/your_awesome_configuration.html" // optional
},

The path is required and the extra_description_path pointing at an HTML file is optional. The steps shown stop at that point, so what review a pull request receives is not something this guide tells you.

There are no releases to pin, and the repository carries rules only

The repository is not archived and its last push was on 23 October 2026, but it publishes no GitHub releases. That has a direct effect on how you consume it. There is no tagged version to lock, so a rule you imported last month and the same rule imported today may differ, and the revision markers inside titles such as (rev XXX) are the only version signal a rule carries. If you need a stable copy, take the file from dist and keep it in your own configuration. The project also does not contain Karabiner-Elements itself. It is a collection of rule files, a build and a distribution site, and the behavior of an imported rule on your keyboard depends on the app version you run and on the manipulator syntax that version accepts. The license is the Unlicense, so you can copy, change and republish any rule without asking. Because the rules are plain JSON or short JavaScript, auditing a rule before enabling it takes minutes, and for anything that remaps keys such as caps lock or the modifier keys, reading the file first is a sensible habit.

Editorial conclusion

Use this repository if you want a ready rule to import into Karabiner-Elements or if you want to publish your own rule through a pull request. Do not expect it to teach the manipulator syntax or to give you a version to pin, because the reference manual lives on the Karabiner-Elements site and the repository has no GitHub releases.

Frequently asked questions

What is Karabiner-Elements?

Karabiner-Elements is the application that consumes the rule files in this repository. The repository supplies complex_modifications rules for it and a distribution site at ke-complex-modifications.pqrs.org to import them from.

How to remap keys with karabiner elements?

Write or pick a complex_modifications rule with a from key and a to key, such as the sample that changes caps_lock to escape, then import it from the distribution site. Karabiner-Elements 16.2.0 and later can import single rule JSON and JavaScript directly.

Which language can I write KE-complex_modifications rules in?

Rules can be JSON files under public/json or JavaScript files under public/js. JavaScript must be written in ECMAScript 5.1 and its last expression must return a single rule.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pqrs-org-ke-complex-modifications.svg)](https://hysenlabs.com/projects/pqrs-org-ke-complex-modifications)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pqrs-org-ke-complex-modifications.svg)](https://hysenlabs.com/projects/pqrs-org-ke-complex-modifications)

Was this useful?