LazyQMK

Keyboard Layout Editor for QMK Firmware

LazyQMK is a keyboard layout editor for QMK firmware, available in both terminal (TUI) and web-based interfaces. Design keymaps, manage layers, organize with colors and categories, and compile firmware—whether you prefer the terminal or the browser.

---

<table> <tr> <td width="50%"> <img src="docs/LazyQMK.png" alt="LazyQMK Terminal UI"> <p align="center"><em>Terminal UI (TUI)</em></p> </td> <td width="50%"> <img src="docs/LazyQMK_Web_Dark.png" alt="LazyQMK Web Interface"> <p align="center"><em>Web Interface</em></p> </td> </tr> </table>

✨ Two Interfaces, Same Power

Choose Your Workflow:

• lazyqmk - Terminal UI (TUI) for keyboard enthusiasts who live in the terminal
• lazyqmk web - Web-based editor for a modern browser experience

Both interfaces provide full feature parity: visual keyboard preview, layer management, firmware generation, and compilation.

💡 Motivation

I created LazyQMK because I wanted to edit my keyboard firmware for my Keebart Corne Choc Pro directly without diving into code every time I needed to tweak a keymap. At the same time, I wanted to support complex coloring of layers and individual keys for better visual organization.

This led me to add custom code to my QMK fork and implement visual layer-aware coloring in a terminal UI editor. Why a TUI? Because I love having small, focused utilities in the terminal—like lazygit and neovim. LazyQMK follows that philosophy: stay in the terminal, work efficiently, and keep it simple.

You can find my current layout as an example in the examples folder.

[!IMPORTANT] Project Status: This is an experimental project testing how far AI-guided coding can go, so expect some rough edges! It's been mostly tested on my Corne Choc Pro, and I can't guarantee it'll work smoothly with other keyboards. The codebase may be unstable or break with other keyboards. That said, if you're interested in helping make this more robust, broaden hardware support, or refine functionality, contributions and support from the community are highly appreciated. PRs and feedback are very welcome!.

📦 Installation

[!IMPORTANT] Custom QMK Fork Required: LazyQMK requires a custom QMK firmware fork for full functionality, especially LED/RGB lighting support. Using the official QMK firmware will result in limited features.

Homebrew (macOS/Linux) - Recommended

brew install Radialarray/lazyqmk/lazyqmk

Or tap first, then install:

brew tap Radialarray/lazyqmk
brew install lazyqmk

Pre-built Binary + Custom QMK Fork

[!TIP] Starting with v0.13.0, lazyqmk includes both TUI and web interfaces in a single binary. Use lazyqmk for TUI or lazyqmk web to start the web server.

Step 1: Download and install LazyQMK for your platform

<details> <summary><b>Linux (x86_64)</b></summary>

wget https://github.com/Radialarray/LazyQMK/releases/latest/download/lazyqmk-linux-x86_64.zip
unzip lazyqmk-linux-x86_64.zip
chmod +x lazyqmk
sudo mv lazyqmk /usr/local/bin/

</details> <details> <summary><b>Linux (ARM64)</b></summary>

wget https://github.com/Radialarray/LazyQMK/releases/latest/download/lazyqmk-linux-aarch64.zip
unzip lazyqmk-linux-aarch64.zip
chmod +x lazyqmk
sudo mv lazyqmk /usr/local/bin/

</details> <details> <summary><b>macOS (Apple Silicon)</b></summary>

wget https://github.com/Radialarray/LazyQMK/releases/latest/download/lazyqmk-macos-aarch64.zip
unzip lazyqmk-macos-aarch64.zip
chmod +x lazyqmk
sudo mv lazyqmk /usr/local/bin/

⚠️ macOS Security Note: The first time you run lazyqmk, macOS will block it because the binary isn't signed.

To allow it:

1. macOS will show a security warning when you try to run lazyqmk
2. Go to System Settings → Privacy & Security
3. Click "Allow Anyway" next to the LazyQMK message
4. Run lazyqmk again and click "Open" in the dialog

</details> <details> <summary><b>Windows (x86_64)</b></summary>

curl -L -o lazyqmk-windows-x86_64.zip https://github.com/Radialarray/LazyQMK/releases/latest/download/lazyqmk-windows-x86_64.zip
Expand-Archive lazyqmk-windows-x86_64.zip -DestinationPath .
# Move lazyqmk.exe to a directory in your PATH (or run from current directory)

</details>

Or download manually from the releases page.

Step 2: Clone the custom QMK firmware fork

# Clone custom QMK firmware fork (with LED/RGB support + submodules)
git clone --recurse-submodules https://github.com/Radialarray/qmk_firmware.git ~/qmk_firmware

Step 3: Launch LazyQMK and configure

lazyqmk

The onboarding wizard will ask for:

• QMK Firmware Path: Path to the custom fork you just cloned
  • Linux: /home/YOUR_USERNAME/qmk_firmware
  • macOS: /Users/YOUR_USERNAME/qmk_firmware
  • Windows: C:\Users\YOUR_USERNAME\qmk_firmware
• Keyboard: Your keyboard name (e.g., crkbd/rev1 for Corne)
• Layout Variant: Your physical layout (e.g., LAYOUT_split_3x6_3)

Step 4: Verify Your Setup

After installation, verify that all required tools are present:

lazyqmk doctor

This checks your QMK CLI, build toolchains, and firmware directory. If any tools are missing, install them and run lazyqmk doctor again. For details, see QUICKSTART.md.

That's it! You're ready to start editing your layout.

🌐 Web Editor

New in v0.13.0: LazyQMK now includes a web-based editor with full feature parity to the TUI!

Quick Start - Web Interface

# Install LazyQMK (see Installation section above)
# Then start the web server:
lazyqmk web

# Open your browser to http://localhost:3001

The lazyqmk web subcommand provides:

• REST API - Backend for layout management and firmware operations
• Web UI - Modern browser-based editor (embedded, no separate installation needed)
• Single Binary - Frontend is embedded at compile time for easy deployment

Web Editor Features

• 📝 Visual keyboard layout editor - Drag-and-drop keycode assignment
• 🎨 Layer management - Create, delete, and organize layers with color coding
• 🔨 Firmware generation - Generate QMK keymap files (JSON + C code)
• 🏗️ Firmware building - Compile firmware and download artifacts (.uf2/.hex/.bin)
• 📊 Real-time build logs - Live streaming compilation output with syntax highlighting
• 📦 Build history - Track all firmware builds with timestamps and checksums
• 🚫 Build cancellation - Stop long-running compilations instantly
• 🧹 Automatic cleanup - Old build artifacts are cleaned up automatically (7 days, 50 max)
• 🌙 Dark mode - Respects system theme preferences
• ⌨️ Keyboard shortcuts - TUI-like shortcuts for power users
• 📱 Responsive design - Works on desktop, tablet, and mobile

Configuration Options

# Custom port
lazyqmk web --port 8080

# Custom host (bind to all network interfaces for LAN/remote access)
lazyqmk web --host 0.0.0.0

# Combine options
lazyqmk web --host 0.0.0.0 --port 8080

When to Use Web vs TUI

Use the Web Editor (lazyqmk web) when:

• You prefer a graphical interface with mouse interaction
• You want to share access with others on your network
• You're working on a device without terminal access
• You need to download firmware files directly from the browser

Use the TUI (lazyqmk) when:

• You live in the terminal and prefer keyboard-only workflows
• You want minimal resource usage (no web server overhead)
• You're editing layouts over SSH
• You prefer tools like lazygit and neovim

Both interfaces use the same binary and share the same configuration!

Troubleshooting

Web Editor Not Updating After Rebuild:

If you've updated LazyQMK but the web interface still shows the old version, your browser may be caching the old frontend files. Force a cache refresh:

• Chrome/Firefox/Edge: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
• Safari: Cmd+Option+R (macOS)

Alternatively, clear your browser's cache completely:

• Chrome: Settings → Privacy → Clear browsing data → Cached images and files
• Firefox: Settings → Privacy → Clear Data → Cached Web Content
• Safari: Safari → Clear History → All History

Deployment

For production deployment (systemd, Docker, reverse proxy), see docs/WEB_DEPLOYMENT.md.

Development

Want to contribute to the web frontend? See web/README.md for development setup:

cd web
npm install
npm run dev:web  # Starts backend (port 3001) + Vite dev server (port 5173) with hot-reload

✨ Features

Core Capabilities

• Visual Layout Editor - See your keyboard geometry as you edit with accurate physical positioning
• Multi-Layer Support - Create and manage unlimited QMK layers with easy tab-based navigation
• Smart Color System - Four-level priority system (key → key category → layer category → layer default)
• Category Organization - Group keys by function (navigation, symbols, modifiers, etc.)
• Searchable Keycode Picker - Fuzzy search through 600+ QMK keycodes with instant filtering
• Language-Specific Keycodes - Support for german keycodes

Firmware Integration

• Direct QMK Integration - Uses custom QMK firmware fork with LED/RGB lighting support
• Background Compilation - Build firmware without blocking the UI
• Live Build Progress - Real-time compilation output and error reporting
• Idle Effect Screensaver - Configurable RGB screensaver that triggers after keyboard inactivity (customizable timeout, duration, and animation effect)

Developer-Friendly

• Human-Readable Markdown - Layouts stored as .md files with YAML frontmatter
• Version Control Ready - Plain text format perfect for git or a dotfile manager like [chezmoi](https://github.com/twpayne/ch