Metadata-Version: 2.4
Name: zmk-buddy
Version: 0.1.1
Summary: A live keymap visualization tool for ZMK keyboards.
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Author: Kevin Hester
Author-email: kevinh@geeksville.com
Requires-Python: >=3.12,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: dev
Requires-Dist: black ; extra == "dev"
Requires-Dist: bleak (>=0.22.0)
Requires-Dist: evdev (>=1.7) ; sys_platform == "linux"
Requires-Dist: keymap-drawer (>=0.22.1)
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: platformdirs (>=4.0)
Requires-Dist: pylint ; extra == "dev"
Requires-Dist: pynput (>=1.7)
Requires-Dist: pyside6 (>=6.10.1)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: types-pyyaml ; extra == "dev"
Project-URL: Homepage, https://github.com/geeksville/zmk-buddy
Project-URL: Repository, https://github.com/geeksville/zmk-buddy
Project-URL: issues, https://github.com/geeksville/zmk-buddy/issues
Description-Content-Type: text/markdown

# 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 time you type a key, it's tracked as "pending"
2. If you press another key (not backspace), the pending key is marked as **correct**
3. If you press backspace, the pending key is marked as **incorrect**
4. Once a key reaches 90% accuracy over at least 100 presses, it's considered "learned" and dimmed in the display

## 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

- Press **y** to cycle through layers
- Press **x** 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)
