ViableOverlay

A native macOS menu bar app that shows your active keyboard layer and a live layout overlay for Viable QMK keyboards.

Features

• Floating HUD overlay — displays the full keyboard layout with keycap labels for the current layer
• Live key highlighting — physically pressed keys light up in real time
• Zero configuration — the keyboard definition and keymap are downloaded directly from the keyboard over USB; no config files needed

Requirements

• macOS 14 (Sonoma) or later
• A keyboard running the Viable QMK firmware, connected via USB

Installation

Download

Grab the latest ViableOverlay.zip from the Releases page, unzip it, and move ViableOverlay.app to your Applications folder.

Note: The app is not code-signed. Before launching, clear the quarantine attribute:

xattr -c ViableOverlay.app

Build from Source

Requires Swift 5.9+ (included with Xcode 15+). No Xcode project needed — the app is built entirely with Swift Package Manager.

# Run in development mode
swift run

# Build a release .app bundle
make app
open ViableOverlay.app

Usage

1. Launch the app — a keyboard icon appears in your menu bar.
2. Click the icon to open the popover with connection status and controls.
3. Toggle Show HUD to display the floating keyboard overlay.
4. The overlay updates automatically as you switch layers and press keys.
5. Drag the overlay to reposition it, or click it to dismiss.

License

MIT — Copyright (c) 2026 Matt Westlake