Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

Build Status License


complex_modifications for Karabiner-Elements.

Add rules

  1. Put a JSON generator file (.rb, .erb or .js) into src/json. (Or put a .json file directly into public/json directly.)

  2. (Optional) Update public/groups.json if you want to add your rules into specific category.

    Add the following entry into groups.json.

        "path": "json/your_awesome_configuration.json", // required
        "extra_description_path": "extra_descriptions/your_awesome_configuration.html" // optional
  3. Run make command on Terminal.
    If you've a generator file into src/json, formatted json file will be auto generated in the public/json/your_awesome_configuration.json.


complex_modifications documents

Testing complex_modifications webpage on local server

public/index.html does not work properly if you open it via file://....
Launch a local web server by make server in terminal and open http://localhost:8000.
(You can quit the local web server by the control-c shortcut in terminal.)
Before run make server, make sure you've run make command to auto generate public/build/dist.json file.

Karabiner-Elements cannot import the json from the local web server due to the no https connection between local web server.
Please import the json via file copy. (See Test your own rules.)

Testing your own rules

  1. Copy a json file to ~/.config/karabiner/assets/complex_modifications.

    cp public/json/your_awesome_configuration.json ~/.config/karabiner/assets/complex_modifications
  2. Import rules from Karabiner-Elements Preferences. Karabiner-Elements Preferences > Complex Modifications > Rules > Add rule

How to publish your own rules

If you want to publish your own rules into complex_modification repository, follow this step.

  1. Fork this repository to your github account.
  2. Update or add new rules by following Add rules section. Don't forget to run make
  3. Stage modified files (git add) and commit it (git commit)

    NOTE : The make command will auto generate public/build/dist.json file. But do not stage public/build/dist.json file.
    (public/build/dist.json file is already ignored by .gitignore)

  4. Push to your forked repository.
  5. Click "New Pull Request" button, then the maintainer will review your commit.

Karabiner-Elements Usage

Import file from another site

  1. Put a json file to your site.
  2. Make a link karabiner://karabiner/assets/complex_modifications/import?url=<JSON_URL>.
  3. Open the link from web browser.

Updating the web application

Note: You don't need to update the web application if you just want to add new json.

If you want to modify the web application, the source code is in src/react. Follow the instruction in src/react/