zmk-buddy 0.1.2
A live keymap visualization tool for ZMK keyboards.
Requires Python: <3.15,>=3.12

# ZMK Buddy

A live keymap visualization tool for ZMK keyboards, built on top of [keymap-drawer](https://github.com/caksoylar/keymap-drawer).

## Features

- Live visualization of keyboard key presses
- Overlay display with configurable transparency
- Support for ZMK keymap YAML files
- Global keyboard monitoring (requires appropriate permissions)
- **Learning Mode**: Tracks your typing accuracy to help you learn touch typing

## Learning Mode

ZMK Buddy includes a learning feature to help you master touch typing without looking at the keyboard:

- **Accuracy Tracking**: Monitors each keypress and guesses at errors (i.e. it saw you press backspace after a key)
- **Progress Persistence**: Statistics are saved to your local data directory and persist between sessions
- **Visual Feedback**: Keys you've mastered are significantly dimmed, encouraging you to rely on muscle memory
- **Progress Summary**: Shows your overall learning progress at startup

### How It Works

1. Each key starts with a score of 0%
2. Each time you type a key, it's tracked as "pending"
3. If you press another key (not backspace), the pending key is marked as **correct** (+1% to score)
4. If you press backspace, the pending key is marked as **incorrect** (-5% to score)
5. Once a key's score exceeds 80%, it's considered "learned" and dimmed in the display (to make it harder for you to 'cheat' by looking at the on-screen keyboard)
6. If accuracy falls below 80% the visible key reappears as a hint to help you find it

## Installation

```bash
pipx install zmk-buddy
```

## Usage

```bash
zmk-buddy --keymap keymap.yaml
```

You will want to use the keymap.yaml file generated by [keymap-drawer](https://github.com/caksoylar/keymap-drawer).  This is how we know where/how to draw keys and what the layer options are.

Some ZMK keyboard builds auto generate keymap.yaml automatically, otherwise see the keymap-drawer documentation for how to generate one for your keyboard/layout.  You can either use their command line tool or their webapp to generate this yaml file.

If you do not specify a keymap a placeholder example keymap is used, which is probably not what you want.

### Options

- `-d, --debug`: Enable debug logging
- `-k, --keymap <file>`: Load a custom keymap YAML file

### Controls

- FIXME to cycle through layers
- FIXME to exit
- Drag the window to reposition it

## Requirements

- Python 3.12+

### Platform Support

ZMK Buddy supports global keyboard monitoring across all major platforms:

| Platform | Backend | Notes |
|----------|---------|-------|
| **Linux** | evdev (preferred) | Requires user to be in `input` group |
| **Windows** | pynput | 'should' work, but untested by me - let me know how it goes for you? |
| **macOS** | pynput | May require Accessibility permissions in System Preferences (also untested) |

### Linux Permissions

For global keyboard monitoring on Linux, your user needs access to `/dev/input/event*` devices. Add your user to the `input` group:

```bash
sudo usermod -aG input $USER
```

Then log out and back in for the change to take effect.

## License

Copyright 2026 Kevin Hester, kevinh@geeksville.com
GPL V3 [license](LICENSE)