kbgone

name

kbgone

description

Locate, install, configure, and troubleshoot kbgone — the macOS menu bar app that disables the built-in MacBook keyboard while an external keyboard is connected. Use when the user asks to stop/disable/turn off their laptop's internal or built-in keyboard, mentions keys being pressed by a closed lid or a keyboard resting on the laptop, asks about kbgone specifically, or reports that kbgone is installed but not blocking.

kbgone

Menu bar app that swallows key events from the built-in keyboard while an external keyboard is in use.

Repo: https://github.com/jasonkneen/kbgone

Is it already installed?

ls -d /Applications/kbgone.app 2>/dev/null && echo installed
pgrep -lf 'kbgone.app/Contents/MacOS/kbgone' || echo "not running"

Install

Prefer the signed DMG from the latest release:

gh release download --repo jasonkneen/kbgone --pattern '*.dmg' --dir /tmp
hdiutil attach /tmp/kbgone-*.dmg -nobrowse -quiet
cp -R "/Volumes/kbgone/kbgone.app" /Applications/
hdiutil detach "/Volumes/kbgone" -quiet
open /Applications/kbgone.app

The DMG is Developer ID signed, notarized and stapled, so it opens with no Gatekeeper prompt. If a build ever isn't notarized, first launch needs right-click → Open, or xattr -dr com.apple.quarantine /Applications/kbgone.app.

From source instead:

git clone https://github.com/jasonkneen/kbgone && cd kbgone
./Scripts/build-app.sh && cp -R build/kbgone.app /Applications/
open /Applications/kbgone.app

Grant permission

kbgone needs Accessibility — there is no way to filter key events without it. The app prompts on first launch and retries every 2 seconds, so no restart is needed. Open the pane directly:

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"

How it decides what to block

A device only becomes a trigger once it has produced a real key press. This matters: wireless mouse dongles and various USB gadgets enumerate a keyboard HID interface, and treating mere presence as a trigger would leave the internal keyboard permanently dead because a mouse is plugged in.

So: connect the external keyboard, press one key, and the internal keyboard goes quiet from then on. The device is remembered by vendor/product ID and triggers immediately on future connects. Devices can also be ticked/unticked by hand in the menu.

Diagnose

/Applications/kbgone.app/Contents/MacOS/kbgone --list

  SERVICE ID  KIND      TRIGGER  TRANSPORT            NAME
  4301695967  built-in  —        FIFO · 0000:0000     Apple Internal Keyboard / Trackpad
  4301877443  external  yes      Bluetooth LE         NuPhy Air75 V2-1
  4301825759  external  unseen   USB · 3554:f549      2.4G Dual Mode Mouse

• KIND must show exactly one built-in. If none, device identification failed on this hardware and nothing will ever be blocked.
• TRIGGER must be yes for the external keyboard. unseen means it has never produced a keystroke — press a key on it.

Troubleshooting

Menu says BLOCKED but the keyboard still types. The sender ID in CGEvent field 87 is not matching the built-in keyboard's registry ID. This is the known historical bug: field 87 carries the full 64-bit IORegistryEntryID, and any 32-bit truncation makes every comparison fail. Check for masking or %d formatting in HIDKeyboards.swift.

Nothing blocks and the menu shows a permission warning. Accessibility is not granted. If it was granted before and the app was rebuilt, the signature changed and TCC treats it as a new app:

tccutil reset Accessibility com.jkneen.kbgone
open /Applications/kbgone.app

Internal keyboard stays dead. Quit kbgone from the menu bar — the block exists only while the process runs, so quitting always restores it. Force quit works too:

pkill -f 'kbgone.app/Contents/MacOS/kbgone'

High CPU. Check whether it is actually kbgone before blaming it:

top -l 2 -o cpu -n 6 -stats pid,cpu,command | tail -8

If WindowServer, SystemUIServer and several menu bar apps are all high, the usual cause is a customised accessibility pointer, which makes every cursor set re-render a bitmap system-wide:

defaults read com.apple.universalaccess | grep -iE 'cursorIsCustomized|mouseDriverCursorSize'

Reset it in System Settings → Accessibility → Display → Pointer.

Limits worth stating up front

• Requires Accessibility permission.
• Only applies inside the user session — the internal keyboard works normally at the FileVault/login window. Deliberate, so nobody locks themselves out.
• Touch ID and the power button are not key events and are unaffected.
• There is no supported way to truly unload the internal keyboard driver on modern macOS. Anything claiming otherwise (kext unloading, AppleUSBTopCase tricks) is obsolete. Do not suggest it.
• Persistent hidutil key remapping is a deliberate non-goal: its changes survive a crash and can strand the user with a dead keyboard until reboot.