KeyWeave
KeyWeave device-specific hidutil key remapping generator for macOS
Paste output from hidutil list --ndjson --matching keyboard to build a device-specific key remap locally in your browser. KeyWeave discards serial-number fields and does not upload the device list.
How device-specific hidutil key remapping works
macOS represents keyboard inputs as HID usage values. A remap pairs one source usage with one destination usage inside UserKeyMapping. The difficult part is not the pair itself; it is making sure the property reaches the intended keyboard service. KeyWeave reads the device records you paste, lets you choose one keyboard, and generates a --matching object alongside the mapping. Nothing is read directly from the computer.
The preview includes a temporary test command and a device-specific reset command. Both are plain text until you copy them into Terminal. This separation makes the generated result inspectable before it changes input behavior and keeps the reset target aligned with the test target.
Choose reliable keyboard matching fields
VendorID and ProductID are the normal starting point for a hardware match. They are stable enough to distinguish many external keyboards from the built-in keyboard, but two physical devices can share the same pair. KeyWeave checks the devices present in the pasted list. When that pair collides and LocationID is available, the generated match includes LocationID and labels the result as location-specific.
A location-specific mapping may need to be regenerated after moving a keyboard to another port or dock. Product names are shown to help selection, but they are not inserted into the matching dictionary. Serial-number fields are discarded before devices enter application state, as described in the privacy explanation.
Test a remap before installing persistence
Start with a simple one-to-one standard key mapping and run only the temporary test command. Confirm the physical source key, the resulting destination key, and the behavior of every keyboard that should remain unchanged. Keep the generated reset command visible while testing so an uncomfortable modifier swap can be undone without rebuilding the command.
KeyWeave warns about self-maps, repeated sources or destinations, and cycles such as Caps Lock to Control combined with Control to Caps Lock. A cycle can be intentional, but the warning makes that behavior explicit. Consumer controls and Fn or Globe usages are marked experimental because their reported usages and results vary by keyboard firmware and macOS release.
Create and validate a reversible LaunchAgent
The generated LaunchAgent plist repeats the reviewed hidutil command at login. KeyWeave also generates separate steps to lint the downloaded plist, bootstrap it in the current graphical user session, inspect the loaded agent, read the active UserKeyMapping, and kickstart only after review. These are instructions, not actions performed by the webpage.
The uninstall sequence uses launchctl bootout, resets the selected device, and removes only the named KeyWeave plist. It does not delete unrelated LaunchAgents. Review the path and label before pasting any lifecycle step. The terms of use summarize the operator’s responsibility for testing and recovery.
Supported mappings and deliberate limits
KeyWeave is built for one physical key mapping to one destination usage. It covers common modifier, navigation, function, and editing keys plus a small experimental set of media and Fn usages. It does not build chords, macros, tap-hold layers, per-application profiles, mouse mappings, or conditional rules. A dedicated remapping application is more appropriate when those behaviors are required.
The tool cannot confirm that a keyboard is still attached, that a pasted device record is current, or that macOS accepted a command. Validation text can inspect configuration state, but only the person at the Mac can verify real key behavior. See About KeyWeave for the product scope and its local-only parsing boundary.
Troubleshoot a mapping that does not respond
First run hidutil list --ndjson --matching keyboard again and compare the current VendorID, ProductID, and—when used—LocationID with the generated match. If a dock or port changed, select the current device record and regenerate. Next, test a standard key pair to separate a matching problem from an experimental Consumer or Fn usage problem.
If a temporary mapping works but disappears after login, lint the saved plist, inspect the agent with launchctl print, and compare the program arguments with the current preview. If behavior is uncertain, boot out the agent and use the device-specific reset before changing anything else. KeyWeave never treats a generated command as proof that hardware validation succeeded.