Setup Guide

Get Keyboard Helper running in a few minutes.

1. Download

Grab the latest release for your platform from the GitHub releases page. Builds are available for macOS (Apple Silicon & Intel), Windows, and Linux.

1. Download the appropriate archive for your OS.
2. On macOS: open the .dmg and drag Keyboard Layout to Applications.
3. On Windows: run the .msi installer.
4. On Linux: extract the archive and run the binary.

2. First launch

Launch the app. A transparent overlay appears showing the default QWERTY layout. Start typing — keys will highlight in real-time.

Closing the window hides it to the system tray. Restore it from the tray icon menu.

3. Configuration

Create ~/.keyri.json to customize the app. The file is optional — without it the app loads all built-in layouts and defaults to QWERTY.

Select a default layout

{
  "defaultLayout": "corne",
  "layouts": {
    "corne": true,
    "qwerty": true
  }
}

Load a custom layout file

{
  "defaultLayout": "my-layout",
  "layouts": {
    "my-layout": "/home/you/keyboards/my-layout.json"
  }
}

Layout files are JSON — copy one of the built-in layouts from the repo (src/layout_corne.json) as a starting point.

Global toggle hotkey

Configure a system-wide hotkey to show or hide the app from the tray. Press it once to restore, press it again to hide.

{
  "toggleHotkey": "Shift+Meta+K"
}

Supported modifiers: Shift, Meta / Cmd, Ctrl, Alt / Option. Single letters are accepted (K → KeyK). For other keys use the rdev key name directly (e.g. F1).

4. CLI toggle flag

You can also toggle the app by launching it with the --toggle flag. If the app is already running, this shows or hides the window rather than opening a second instance.

/Applications/Keyboard\ Layout.app/Contents/MacOS/keyboard-app --toggle

Useful for binding to external hotkey managers like Raycast, BetterTouchTool, or Shortcuts.app.

5. Build from source

Prerequisites: Node.js LTS, Rust toolchain, and Tauri v2 platform deps.

git clone https://github.com/maxistar/keyboard_helper.git
cd keyboard_helper
npm install
npm run tauri dev    # dev window
npm run tauri build  # release bundle