Keymap Editor: a WYSIWYG front end for ZMK keymaps you commit back to GitHub

A hosted editor for the ZMK keymap file, not a firmware tool

ZMK keymaps are files of keycode bindings, layers, conditional layers, combos and macros, and reading them means remembering a vocabulary of keycode names and the exact shape of each construct. Keymap Editor exists to remove that reading step: it loads a keymap and shows it as a keyboard you can click on.

The scope boundary is stated early and repeated later. Actual firmware builds are outside the scope of the project, so if you are editing local keymap data you are assumed to have a local ZMK development environment or another way of running builds. The app produces a correct keymap; it does not produce a firmware binary, and it does not know how your bootloader is wired.

The README is also blunt about what the app is not: it says simplifying keymap editing is one of the goals but that the tool is not a substitute for understanding ZMK. That is an unusual admission from a project whose whole value proposition is convenience, and it is fair. A graphical editor hides the file format rather than teaching it, and a keymap that stops compiling is much easier to fix when you know which construct is wrong.

The fastest way to evaluate it is the built-in demo: the app ships with a keymap-editor-demo-crkbd repository so you can load a real Corne keymap before configuring your own.

Three keymap sources: GitHub, clipboard, and a Chromium-only file system

Where the keymap comes from decides everything else about how you work, and there are three sources.

The GitHub integration is the interesting one. You grant the app access to your public or private zmk-config repositories, it reads the keymap, and edits are committed back to the repository. The README frames the payoff precisely: you never leave the app to download and flash firmware, because the artefact of editing is a commit.

The clipboard source is the offline path. You paste the contents of a .keymap file into the editor and copy the result back out. It works anywhere, including a browser with no GitHub connection at all.

The third source, FileSystem, uses web file APIs to read and write selected .keymap files in place. The README attaches an asterisk to that entry and the footnote is unambiguous: file system web APIs are currently only supported in Chromium-based browsers. Firefox and Safari users are limited to clipboard or GitHub.

That single asterisk is worth noticing more than it looks. A tool that reads and writes your keymap file directly is the nicest workflow available, and it is the one you cannot rely on across browsers.

What the UI actually models: layers, combos, macros and behaviors

The feature list is short enough to read as an inventory of ZMK constructs the editor has a dedicated view for. WYSIWYG editing covers the main keymap screen; multiple keymaps are first-class rather than a copy-paste. Conditional layers have their own support, which matters because conditional layer bindings are where a keymap file becomes hard to read by eye.

Combos and macros each get an editing view, and the macro editor goes beyond simple sequences: the README calls out support for creating and using parameterized macros. That is the feature most worth checking against your own keymap, since parameterized macros are exactly the part of the format that is unpleasant to hand-write.

Behavior editing is creation and re-configuration, meaning the app can emit behavior bindings rather than only move them around. Rotary encoders are supported, with the encoder screen as part of the layout rather than a config file you edit separately.

Two items on the list are about the application rather than the keymap: dark mode, and the multiple keymap sources already covered. Everything else maps to something in the ZMK format, which is a good sign for the editor's central claim that it is a front end rather than a separate model.

Auto-generated layouts are a starting point, and the author says so

For a keyboard ZMK supports, the editor can generate the layout for you, covering most keyboards available in the ZMK repository. That is a large convenience: nobody enjoys transcribing a full key matrix into position notation.

The footnotes qualify it in two ways. The generated layouts are meant as a starting-off point and may need customization. And the author writes that they own exactly one keyboard and do not know all the layouts, which is an unusually blunt statement of the confidence level behind a feature.

Both footnotes are reasonable rather than alarming, provided you read them as scope. A generated layout tells you where the keys are; it cannot tell you what a knob on that board is wired to, whether a particular position is a rotary encoder or a key on that revision, or which layers a designer intended. The wiki page on automatic layout generation is linked for people who want to define layouts themselves, so the extension path exists for the cases where the generated one is wrong.

The practical test is cheap: load your board, compare the generated layout against the silkscreen in front of you, and fix what differs before you start moving keys around.

The server side: Express, websockets and a GitHub token path

Even a browser app needs a backend here, and the repository shows one. The root package is keymap-editor at version 1.0.0 with index.js as the entry point and an api/ directory for server code, plus an app/ directory that carries its own dependencies, installed by a postinstall step that runs npm install inside app.

The dependency list explains the shape of the service: express at 4.17.1 and body-parser at 1.19.0 for HTTP, express-ws at 4.0.0 for websockets, cors at 2.8.5 and morgan at 1.10.0 for cross-origin and request logging, axios at 0.21.4 for outbound calls, jsonwebtoken at 8.5.1 for tokens, dotenv at 10.0.0 for configuration and lodash for utility work. A .env.template and a Procfile sit at the top level, which is the conventional layout for a service that was originally deployed somewhere with simple process management.

Two scripts matter for running it yourself, the start script and the dev script, the second being the switch for serving the front end locally instead of the built assets. There is also a running-locally.md at the top level, so a local setup is documented rather than reverse-engineered.

The websocket dependency is the interesting one for understanding the editor's feel: live updates to a keymap are cheaper to push than to re-request, and the GitHub write-back then happens as an explicit save rather than on every keystroke.

Trying the editor before you commit a keyboard to it

The fastest evaluation path is the hosted app plus its bundled demo. Open the Keymap Editor, load the keymap-editor-demo-crkbd repository, and click through the views for layers, combos and macros with a keymap you do not care about. Nothing you do there touches a real repository, so the risk is zero and the information is real: you learn whether the graphical model matches how you think about your layers.

Once that is settled, the second step is a keymap of your own, still on the clipboard path. Paste a .keymap file into the editor, change something small such as one binding or a macro parameter, and copy the result back over your file. Run your existing build. That round trip tells you two things at once: whether the editor preserves constructs you rely on, and whether its output diffs cleanly against a file you have been maintaining by hand. A tool that reformats everything gives you an unreviewable diff, and you find that out here rather than in a commit.

Only after that is worth wiring up the GitHub integration. Grant access to a repository, make a change, and inspect the commit the app produces, because that commit is the artefact you will be reviewing on every future edit.

For running the published code yourself, the repository ships running-locally.md alongside a .env.template, and the root package exposes a start script for the server plus a dev script that enables a development front end.npm start npm run dev ```

Remember that installing the root package also installs a second dependency set inside the app directory, because the postinstall script changes into app and runs npm install there. A clone that starts with missing modules usually means that step did not run.

The adoption cost: unpublished source and a placeholder test script

The most important paragraph in the README is a note near the top. This repository was last touched on 2026-08-27, so treat what is here as a snapshot rather than a moving target. Source code updates are no longer shared here. The author states that development has happened on and off since August 2020, that more recent source changes have not been published, and that this is not expected to change. A wiki page on source code updates is linked for the details, and old-readme.md preserves the original instructions for anyone who still wants to run the published code.

That is the honest version of the adoption question. The hosted app is the maintained artefact. The repository is a snapshot, and a fork is not a starting point for contributing upstream, because upstream work happens somewhere you cannot see.

The repository metadata adds a smaller inconsistency worth knowing about. The README says the code is available under the MIT licence and that the collection of ZMK keycodes comes from ZMK documentation under MIT as well, while package.json declares ISC. For a project with no commercial pressure that reads as an oversight rather than a licensing dispute, but it is the kind of mismatch that matters if you copy code out of it.

The test script is the second signal. npm test is defined as echo "Error: no test specified" followed by exit 1, so there is no suite to run and no coverage to trust. That is consistent with a snapshot repository, and it means evaluating the code means reading it.

Editorial conclusion

Adopt the hosted Keymap Editor if you write ZMK keymaps and your pain is the textual side of the format: remembering keycode names, macro syntax and conditional layer bindings. It is genuinely good at that, and the GitHub integration means you never leave the browser to flash firmware. Do not adopt it as a platform to extend, because the README states that recent source changes are not published, that this is not expected to change, and that the maintained code lives outside this repository, with old-readme.md kept for the original instructions. Verify three things before you commit your keyboard to it. First, that your keymap can live in a GitHub repository the app can reach, since that is the write path, not an export. Second, whether you need the FileSystem source, which works only in Chromium-based browsers, or whether the clipboard route is enough. Third, what happens when the hosted app is unavailable, since your keymap stays in git and the editor is the only thing you lose. If you are evaluating the code rather than the tool, note that the package.json declares an ISC licence while the README describes MIT, and that the test script is a placeholder that exits non-zero, so there is no suite to run, while the root package itself still reads version 1.0.0.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nickcoutsos/keymap-editor on GitHub
4. Project website
5. README