Turn a cheap Bluetooth mini keyboard into a one-touch AI shortcut pad using Karabiner-Elements—device-scoped remaps…
Join developers getting comprehensive guides, code examples, optimization tips, and time-saving prompts to accelerate their development workflow.
No spam. Unsubscribe anytime.
A cheap Bluetooth mini keyboard, the free Karabiner-Elements app, and about 30 minutes of configuration are enough to build a dedicated shortcut pad for dictation and AI coding tools on a Mac. The approach works even when the keyboard ships with no Mac software at all: as long as macOS recognizes its buttons as ordinary keystrokes, Karabiner can intercept those keystrokes on a per-device basis and remap them into whatever shortcuts your AI tools already use, without touching how those same letters behave on your built-in keyboard.
I picked up a six-button mini keyboard for around €25 with exactly this in mind. Out of the box it had no configuration software and simply typed letters when pressed. I used Karabiner-Elements to turn four of those buttons into direct shortcuts for Cursor, Claude, Codex, and native macOS Dictation. This guide walks through the exact setup, including the device-matching step that keeps the remapped letters from also changing on your MacBook's own keyboard.
The mini keyboard does not need official Mac support or bundled software. macOS only needs to recognize its buttons as standard keyboard events, and Karabiner takes it from there.
Here is how the four lower buttons ended up mapped:
Karabiner replaces these letters with the assigned shortcuts only when they arrive from the mini keyboard specifically. The same letters typed on the MacBook's built-in keyboard keep working exactly as they always have.
Pair the device first, through System Settings → Bluetooth.
Once it's connected, open a plain text editor and press every button on the keypad, noting exactly what each one types. My device produced plain letters with no special codes: the two top buttons typed D and A, the middle row typed E and B, and the bottom row typed F and C.
Cheap mini keyboards commonly present themselves to macOS as ordinary keyboards rather than as true programmable macro pads. That's completely fine for this project; Karabiner works from whatever raw keystrokes the device already sends.
Download and install Karabiner-Elements from the link above. During installation, macOS will prompt for a few permissions:
Grant all three. Karabiner can display and edit rules without them, but it needs Input Monitoring and the driver extension to actually intercept keystrokes before they reach the rest of the system.
If Karabiner shows "Waiting for a connection to the IOKit service," check System Settings → General → Login Items & Extensions → Driver Extensions and confirm the Karabiner virtual HID driver is enabled there. Restarting the Karabiner background services, or in some cases restarting the Mac entirely, is sometimes necessary right after the first install.
Open Karabiner-EventViewer, included with the Karabiner-Elements install, and press a button on the mini keyboard. EventViewer will show:
My keyboard identified itself as product MINI-KEYBOARD, vendor ID 1452, product ID 556. Your device will almost certainly report different numbers, so pull your own values from EventViewer rather than reusing these.
This device-specific matching step matters more than it might look. Without it, a rule that remaps the F key would remap F everywhere, including on your MacBook's built-in keyboard, not just on the mini keypad.
In Karabiner-Elements, open the Devices tab, find the mini keyboard in the list, and enable Modify events for it.
Some inexpensive keypads register themselves with macOS as both a keyboard and a pointing device simultaneously. If Karabiner detects button presses in EventViewer but your rules never fire, check that event modification is enabled for the full composite device, not just the keyboard portion of it. My device needed identifiers matching this shape:
// File: identifiers used to match the composite device
{
"is_keyboard": true,
"is_pointing_device": true,
"product_id": 556,
"vendor_id": 1452
}
Karabiner can turn one physical button press into any combination of keys, including modifier combinations your applications wouldn't otherwise let you trigger from a single key.
Before writing any Karabiner rules, test each target shortcut manually on the MacBook keyboard first. Confirming that Control+M actually opens the right panel in Cursor, or that Command+D actually triggers the intended Claude action, saves time over debugging the shortcut and the Karabiner rule at once. Once a shortcut is confirmed working manually, the mapping table above becomes the spec for the rule itself.
Karabiner rules live in the app's Complex Modifications editor, but the underlying format is JSON, which makes it easy to write directly. Here is the complete rule for the four buttons on my device:
Each manipulator follows the same shape: a device_if condition scoped to the exact vendor and product ID from Step 3, a from key code matching the raw letter the button sends, and a to block defining the actual shortcut to emit. The device_if condition is what keeps this rule from affecting your MacBook keyboard at all. Replace the vendor ID, product ID, input key codes, and output shortcuts with the values that match your own hardware and applications, then import the rule through Karabiner-Elements' Complex Modifications tab.
Work through each button one at a time rather than testing all four at once:
If a button keeps typing its original letter instead of triggering the shortcut, check Karabiner's log for whether it describes the device as grabbed. Karabiner-EventViewer detecting button presses is a separate thing from Karabiner actually capturing the device; a rule only takes effect once the device is grabbed.
Does the mini keyboard need to advertise itself as a programmable macro pad? No. Karabiner works from whatever raw keyboard events macOS already receives from the device. A keypad that simply types plain letters is enough as a starting point.
Why remap by vendor ID and product ID instead of just the key code? Matching only the key code would remap that letter everywhere, including on the built-in MacBook keyboard. Scoping each rule to the mini keyboard's specific vendor and product ID keeps the remapping isolated to that one device.
What if Karabiner shows the button press in EventViewer but the rule never fires? Check the Devices tab and confirm Modify Events is enabled for the mini keyboard. Composite devices that register as both a keyboard and a pointing device sometimes need this toggle set explicitly before rules apply.
Can one button trigger more than a simple two-key shortcut?
Yes. The to array in a Karabiner manipulator accepts any key code plus any combination of modifiers, so a single button press can reproduce shortcuts your applications only expose through multi-key combinations.
What happens if I switch which AI tool a button controls later?
Editing the rule's to block for that manipulator and reimporting it is all that's needed. The mapping lives entirely in the JSON rule, not on the hardware, so reassigning a button takes a few minutes.
A €25 mini keyboard combined with Karabiner-Elements produces a genuinely useful AI shortcut pad: one-touch dictation, dedicated buttons for Cursor, Claude, and Codex, and mappings that stay entirely under your own control rather than a vendor's software. The device-matching step in the Complex Modification is what makes it safe to remap ordinary letters without disturbing your regular typing, and the same JSON rule can be edited in minutes whenever your toolset changes. The buttons that control Codex, Claude, and Cursor today can just as easily control a different editor, assistant, or automation tool tomorrow.
Let me know in the comments if you have questions, and subscribe for more practical development guides.
Thanks, Matija
| Button | Output | Purpose |
|---|
| Middle-left (E) | Control + M | Open Cursor |
| Middle-right (B) | Dictation media key | Native macOS Dictation |
| Bottom-left (F) | Fn + Control + Shift + D | Codex dictation |
| Bottom-right (C) | Command + D | Claude |