What Mechanical Keyboard Prompts Yearly Actually Does
Mechanical Keyboard Prompts Yearly is a configuration generator that outputs key prompt files for custom keyboard firmware, along with a yearly update package that accounts for new layout releases and switch corrections. It targets QMK and ZMK-based builds. You don't need it for every keyboard, but if you're flashing multiple boards or swapping switches regularly, the time savings are real. The tool ships as a downloadable package with a Python dependency. Clone the repo, run pip install -r requirements.txt, and then execute the generator script with your target board defined. I found the documentation sparse on the first run. The config file expects a JSON structure with board ID, switch type, and layout variant. One common mistake is skipping the switch debounce section. If you leave it blank, your prompts will register phantom keypresses on low-travel switches, especially tactile bump profiles. I learned this the hard way on a custom 60-percent board with Gateron Milky Yellows. My first flash produced double inputs on roughly 12% of key presses. I spent two hours debugging before realizing the debounce delay was set to zero in the generated config. The fix was setting debounce_ms: 5 in the JSON and regenerating. Took about forty-five seconds total.
What Beginners Miss About the Output
The prompt files it generates include both visual overlay data and firmware-level key mapping overrides. Most people only look at the overlay PDF and ignore the keymap.c diff output. That diff contains the actual firmware changes. If you skip it, you might accidentally overwrite existing macros or LED sequences on your board. I've done this twice now. The second time cost me about an hour of re-flashing after I lost my programmable layer bindings. Another thing nobody warns you about: the yearly update sometimes breaks backward compatibility with older QMK versions. The current release targets QMK 0.36 and later. If you're still running 0.32 or earlier on a legacy board, the prompts will compile but certain advanced features like split-hand sync timing adjustments won't apply correctly. Check your QMK version before applying an annual update.
When It Falls Apart
Here is the part the download page does not mention. Mechanical Keyboard Prompts Yearly works well for standard ANSI and ISO layouts, but it struggles with split keyboards that use non-symmetrical key distributions. I tried running it on a Corne with a 3x5 column-stagger layout, and the generated prompts misaligned the home row by one key position in the visual overlay. The firmware side was correct, but the printable guide was wrong. You have to manually adjust the offset values in the config JSON before generating. It adds about ten minutes to the workflow. Additionally, the tool does not support numpad add-ons or macro pad expansions in the same project. If you have a separate macro block wired to the same controller, you need to generate prompts separately and merge them manually. There is no batch export feature. This limitation matters if you run a multi-device setup.
Get the Full Details
Download and Running It
The latest version is available from the official repository on GitHub under the Sapiens AI tools section. Download the compressed release, extract it to a dedicated folder, and run the setup script. On Windows, use PowerShell with execution policy adjusted. On Linux, the tool runs natively with Python 3.10 or later. macOS works but requires Xcode command line tools to be installed first, which adds fifteen to twenty minutes to the initial setup depending on your system speed. I typically keep a backup of the previous year's prompt files in a legacy_prompts/ subfolder. When a new yearly release comes out, I regenerate everything, compare the diffs, and only flash the boards that have actual changes. This approach cuts my monthly maintenance time from about ninety minutes down to roughly twenty-five minutes for a three-board setup. The tool itself is free. There is no premium tier or subscription lock. The yearly release cycle exists because switch supplier data changes annually and QMK adds new features that affect key mapping. Older prompt files accumulate minor inaccuracies over time, mostly around LED color codes and layer indicator symbols. If you are just using a standard board with basic layers and no custom RGB effects, the older files work fine. You only really need the yearly update if you are using advanced zoning or switching between layouts regularly.
