A local keyboard manager for the ZSA Voyager, built for macOS.
View your layers, remap keys, set up RGB effects, track key usage and build QMK firmware without leaving the app. Keyjitsu can read your existing Oryx layout; edits and firmware builds stay on your computer. No account or background daemon.
Download for macOS (Apple Silicon) · Install and update · Build from source
Keyjitsu is still in beta. The Voyager is the only keyboard tested so far, and macOS is the primary supported platform. Linux and Windows builds are experimental. Quit Keymapp before connecting to Keyjitsu: the raw HID channel can only be used by one app at a time.
Key usage by layer or across the whole keyboard, with a ranking and CSV export.
Set an effect for key presses or create an RGB sequence. FX Studio is experimental.
Two recordings from a physical Voyager. The first shows a key-press lighting effect; the second shows a longer RGB animation. The recordings show lighting on the actual keyboard.
Key-press effect
RGB animation
A transparent layer reference that stays above your other windows and can ignore mouse input.
Start Keyjitsu from Applications or run keyjitsu in Terminal. Use profiles to save different keyboard setups and switch between them.
- Layout editor. Your layout with Oryx legends and live key feedback. Click a key to edit its four slots (tap, hold, double tap, tap+hold), pick keycodes from an Oryx-style picker, set a per-key glow color and an on-press effect, then hit Build & flash. Firmware is compiled locally, and double-tap or tap+hold become generated QMK tap dances. Staged edits survive restarts (shown as pending) until you build.
- Heatmap. Per-layer or summed press counts, a ranking, and CSV export.
- Minimap. A transparent overlay that shows the current layer's keys, so you can glance at what a layer does without leaving what you are doing. It appears when you switch layers (and can stay up the whole time you are on a non-base layer), floats click-through over everything; on macOS you can choose any monitor, and can be summoned by holding a key or chord on the Voyager.
- FX Studio (experimental). Build and test RGB effects: built-in constant and press effects, plus a step sequencer for your own (paint keys, duplicate a step, nudge it around the board, loop). Apply to the whole board, or per key from the editor's on-press slot. Board RGB survives restarts.
- Performance (experimental). keyjitsu samples its own CPU, tagged by what it was doing.
- Autolayer. Switch layers by the frontmost app, matched on the bundle id.
- Settings. Local QMK toolchain status and firmware build, the keyboard guard, start-at-login, the update check, and a shortcut library (a reference list of ~160 common shortcuts to borrow from, with your own entries and hideable built-ins).
The connection auto-reconnects on unplug, replug, and after flashing.
Oryx is ZSA's web-based layout editor; Keymapp is its desktop companion. Keyjitsu is an independent alternative for the Voyager. It reads an Oryx layout, lets you edit it locally, and can compile and flash firmware using the ZSA QMK fork.
Changes made in Keyjitsu are not sent back to Oryx. If you flash firmware from Oryx again, it replaces the layout previously built by Keyjitsu. The firmware state notes explain how Keyjitsu keeps track of this.
The CLI covers the core device, layout, heatmap, RGB, build and flash workflows. A few commands:
| Command | What it does |
|---|---|
keyjitsu list |
List connected ZSA keyboards |
keyjitsu status |
Connection, protocol/firmware version, active layer |
keyjitsu live |
Full-screen TUI live view (legends, heatmap overlay, layer browsing) |
keyjitsu layout |
Print every layer with legends (--layer N, --json, --url, --refresh) |
keyjitsu watch |
Stream key/layer events (--json for scripting) |
keyjitsu heatmap show/reset |
Render or clear collected stats |
keyjitsu layer set/unset N |
Switch layers from scripts |
keyjitsu rgb set/all/release |
Per-key or whole-board RGB |
keyjitsu build-local |
Compile firmware locally (--set "L,POS=KC_X", --dance "L,POS=TAP,HOLD,DOUBLE,TAPHOLD") |
keyjitsu flash <file|url> |
Flash a .bin or an Oryx URL (--latest for the newest revision) |
keyjitsu guard |
Disable the built-in Mac keyboard while a ZSA board is connected (Ctrl+C restores) |
Add --serial <substr> to pick one of several keyboards.
On macOS, see QMK setup and troubleshooting. The guide covers a fresh Mac, ARM GCC, the ZSA firmware25 checkout and recent Homebrew tap-trust errors.
You can check the local prerequisites without changing anything:
scripts/check-qmk-macos.shFirmware builds use the zsa/qmk_firmware fork, a working qmk CLI and arm-none-eabi-gcc. The compiler and firmware checkout are separate from installing Keyjitsu itself.
Settings shows a green "Ready" pill once the toolchain is in place. A build
fetches your layout's generated source from Oryx once (cached, offline
afterwards), patches the keymap with your staged edits, generates any tap
dances, compiles with qmk, and flashes over the Voyager's bootloader. No ZSA
account needed.
Your edits live in that local firmware, not in Oryx. keyjitsu only reads your base layout from Oryx (anonymously). A Keyjitsu-built firmware carries a compact state id in the firmware serial, so after reconnect or app restart Live reconstructs the exact Keyjitsu-authored state reported by the keyboard instead of treating the last saved app config as device truth. It never writes back to the portal. So remapping here does not carry over to Oryx, and re-flashing from Oryx later would overwrite your Keyjitsu changes.
There is an important limitation in ZSA's current Oryx raw-HID protocol:
stock Oryx firmware does not expose the complete keymap back to the desktop
app. The keyboard can report runtime information and its firmware identity
(layout-hash/revision-hash), but there is no supported HID command that
returns every key assignment, layer definition, combo, and persistent RGB
setting from the compiled firmware.
For stock Oryx firmware, keyjitsu can use the hash/revision reported by the
physical keyboard to load the matching Oryx layout. That is a reconstruction
from Oryx data selected by the device's own revision id; it is not a full
keymap extracted from the firmware image itself.
Keyjitsu-built firmware adds its own compact state id to the firmware serial. That lets keyjitsu reconstruct the exact Keyjitsu-authored additions from its matching local firmware-state record. It still does not make stock Oryx firmware suddenly readable as a complete keymap.
For the least surprising workflow, use either Oryx or keyjitsu as the main place where you author a keyboard configuration.
- If you edit and flash in Oryx, treat that Oryx revision as the source of truth. Keyjitsu can recognize the revision reported by the keyboard and load the corresponding Oryx layout.
- If you edit and flash in keyjitsu, treat the Keyjitsu firmware state as the source of truth. Those local-only edits are not written back to Oryx.
- Re-flashing from Oryx overwrites Keyjitsu-only firmware changes.
- Re-flashing from keyjitsu does not update your Oryx layout.
- Switching between the two workflows is possible, but save the configuration you want to keep before flashing and expect the two representations to diverge unless you deliberately synchronize them.
Live/device status should always be driven by the currently connected keyboard's identity. A saved layout or restore point must never silently replace what Live claims is on the physical keyboard.
- Protocol. ZSA's open Oryx raw-HID protocol v4 (32-byte reports, usage
page
0xFF60), as published in zsa/qmk_modules. - Layout state. Stock Oryx firmware identifies itself as
hash/revision. Keyjitsu-built firmware extends that identity with a local state id. The base revision is fetched from the Oryx GraphQL API and the exact Keyjitsu changes are reconstructed from the matching local firmware-state record. - Flashing. Uses ZSA's own open-source zapp
(
zapp-core, MIT + Commons Clause) for the DFU/Ignition bootloaders and dual STM32+GD32 images. You press the reset button, then keyjitsu waits and flashes. - Guard. Remaps the built-in keyboard's keys to no-ops with
hidutil(no special permission needed). It can't lock you out: the built-in comes back around the lock screen and after any reboot, and is restored on toggle-off, disconnect, and quit. Engaged only while a ZSA keyboard is present. keyjitsu verifies with hidutil itself that the remap actually applied (rather than trusting a successful exit code), and Settings has a "Test the guard" button that listens system-wide for a moment to confirm no key press gets through. On some Macs, hidutil's remap reaches the keyboard's "Service" HID layer but not a separate raw "Device" layer that can still deliver key presses: run the test on your own Mac if you plan to rely on the guard, and don't treat it as absolute. - Storage. State is kept in the platform data directory returned by the OS (
~/Library/Application Support/keyjitsu/on macOS, the corresponding user data directory on Linux/Windows):config.json,profiles/*.json,firmware-states/*.json, heatmap stats, and cached layouts/sources. Settings can export those portable items to a bounded ZIP and restore them on a controlled restart; conflicting local files are preserved, while unrelated logs, recordings and signing material are excluded. Before a first real layout has been cached, the GUI displays ZSA's official Voyager default layout (E5AmY/B495Jd) as a bundled offline fallback; it is never flashed automatically and a connected keyboard always replaces it with its own layout.
For macOS on Apple Silicon, select the latest Signed macOS prerelease
from GitHub Releases.
Download the DMG and drag Keyjitsu.app into Applications. These dedicated
macOS packages are Developer ID signed, notarized by Apple and verified by
Gatekeeper. Each release also contains a ZIP and SHA256SUMS.txt.
Starting with 0.10.0-beta.5, Settings checks signed macOS prereleases in addition to the normal version history. If a newer signed build is available, select Download and verify update. The app checks the GitHub SHA-256, Developer ID identity, bundle ID, and Apple notarization, then offers Install update and restart. It never replaces the app without your confirmation. The updater preserves settings, profiles, heatmaps, and firmware data, and attempts to roll back if activation fails. Installing in a folder without write permission requires a manual DMG install.
One-time migration: versions through beta.4 used an update checker that missed beta releases. Install a recent signed DMG manually once. Versions from beta.5 onward can detect signed macOS prereleases in Settings.
The cross-platform workflow still produces ad-hoc signed macOS development artifacts. Use the Signed macOS downloads for normal installation. Linux and Windows releases are experimental.
You need Rust. The QMK toolchain is only needed for local firmware builds.
cargo install --git https://github.com/martinezooo/keyjitsuRun keyjitsu for the GUI or keyjitsu list for the CLI.
For the macOS app bundle:
git clone https://github.com/martinezooo/keyjitsu
cd keyjitsu
scripts/bundle.sh --installA plain cargo build --release builds the desktop/CLI binary on supported desktop targets. Linux needs the normal hidapi/udev development packages at build time and udev access to the Voyager HID device at runtime.
macOS remains the primary hardware-tested target. Guard and Autolayer are macOS-only. Peek works on all desktop targets, but multi-monitor enumeration is currently macOS-specific; Windows/Linux use the current-display fallback until native monitor enumeration is validated.
keyjitsu has no accounts, no telemetry, and no background services. It talks to exactly two places on the network, and both are easy to find in the source:
oryx.zsa.io: an anonymous, read-only fetch of your layout (for the legends), cached on disk after the first time. Local firmware builds fetch the layout's generated source the same way, once. It never writes to Oryx.api.github.com: a bounded list of release metadata, once at startup (Settings can disable this) and on demand. With your explicit permission, the macOS updater downloads a verified signed ZIP fromgithub.com(which can redirect to GitHub's asset CDN). No telemetry or silent updates.
On macOS, the keyboard guard uses the system hidutil tool. Persistent files live in the platform user data directory selected by the directories crate; the app does not write system-wide state.
Quit the app, then:
rm -rf /Applications/Keyjitsu.app
rm -f ~/Library/LaunchAgents/com.keyjitsu.gui.plist # only if start-at-login was on
rm -rf ~/Library/Application\ Support/keyjitsu # settings, profiles, cachesIf the guard was on and the app was force-killed, a reboot restores the built-in keyboard, and so does this command:
hidutil property --matching '{"Product":"Apple Internal Keyboard / Trackpad"}' --set '{"UserKeyMapping":[]}'Keyjitsu is a free personal project. Bug reports and practical feedback are welcome. If you want to support development, there is GitHub Sponsors and Ko-fi.
Keyjitsu stands on open work from ZSA and the QMK community, and on the Rust ecosystem. It does not reimplement what those projects already do well.
- ZSA. The Voyager itself, the open Oryx raw-HID protocol
(zsa/qmk_modules) that keyjitsu speaks,
the public read-only Oryx layout API it reads anonymously, and the open-source
zapp flasher (
zapp-core), which keyjitsu links for the actual firmware flashing rather than rolling its own. - QMK. Local builds use the standard QMK toolchain and
ZSA's
qmk_firmwarefork. The generated tap dances follow QMK's own idiom. - Rust crates. eframe / egui for the GUI,
ratatui and crossterm for the TUI,
hidapi for USB HID, plus serde, ureq,
clap, anyhow, zip, ctrlc, directories, and objc2 / core-foundation on macOS.
See
Cargo.tomlfor the full list and versions.
The protocol is implemented from ZSA's public spec, and layout data comes through the public Oryx API. Keyjitsu is an independent project, not affiliated with or endorsed by ZSA.
MIT (see LICENSE). Firmware flashing links ZSA's zapp-core, which
is MIT + Commons Clause (no reselling its functionality), so keep that in mind
if you redistribute. The bundled symbol font is Noto Sans Symbols 2
(SIL OFL 1.1).





