macOS · ZMK
Keyboard Overlay icon

See your layers.
Lenny's ZMK Keyboard Overlay

A macOS menu bar utility that shows a live on-screen overlay of your ZMK keyboard layout whenever you switch layers.

Get Started
Keyboard Overlay in action showing a Corne split keyboard layout with modifier keys and shortcuts

Features

It's a small utility to help you type.

KeymapOverlay reads your ZMK keymap and talks directly to your keyboard's firmware to know exactly which layer you're on.

Live Layer Detection

Your keyboard reports its active layer state over HID. The overlay appears automatically when you leave the base layer.

Reads Your Keymap

Point it at your .keymap file. It parses layer names, bindings, and custom annotations — no manual config needed.

Custom Annotations

Add custom icons and labels to keys with inline comments in your keymap. Uses SF Symbols for a native macOS look.

Liquid Glass Overlay

Translucent, draggable overlay. Looks pretty good.

Auto Updates

Built-in Sparkle updater keeps the app current. Watches your keymap file for changes too — edit and see results instantly.

Menu Bar Native

Lives in your menu bar. Shows connection status, lets you toggle the overlay, and opens settings with one click.

v1.0

Current Release

This is version 1.0

Corne Layout

Currently supports the Corne (3×6+3) split keyboard layout. More layouts are coming soon.

Tested on nice!nano v2

The ZMK module has been tested on the nice!nano v2 controller. It will likely work on other ZMK-compatible controllers, but hasn't been verified yet.

macOS 26+

Requires macOS 26 (Tahoe) or later.

Get Started

A fairly simple install.

The overlay needs to talk to your keyboard. A small ZMK module sends layer state over HID, and the macOS app listens and renders the overlay.

1

Add the ZMK Module

Firmware
Step 1 — Install the module

From the root of your ZMK config repo, run:

Terminal 
bash -c "$(curl -fsSL https://raw.githubusercontent.com/lennyitb/zmk-layer-report/main/install.sh)"

This updates your west.yml and board .conf file automatically. For split keyboards, the installer will ask which .conf to use — pick your main half (e.g. corne_left.conf).

Having trouble? Check the zmk-layer-report repo for manual installation steps and troubleshooting.
Step 2 — Build & flash

Build your firmware as usual. The module is pulled in automatically by west. Flash the resulting .uf2 to your main half.

2

Install the App

macOS
Step 1 — Download

Grab the latest release from GitHub:

Download for macOS Release notes
Step 2 — Open & configure

Open KeymapOverlay.app from your Applications folder. The Settings window will appear on first launch.

Click Browse and select your ZMK .keymap file. The app parses it automatically to understand your layers and key bindings.

Step 3 — You're done

Switch to a non-base layer on your keyboard. The overlay appears with your key labels, color-coded by type. Drag it wherever you like — position and scale are saved between sessions.