Help
Everything from first install to fine-tuning. Still stuck? Contact us or open a GitHub issue.
Install (2 minutes)
- Download Bonk.dmg and open it from your Downloads.
- Drag Bonk into Applications — the window shows both side by side.
- First launch: right-click Bonk.app → Open → Open. This is only needed once.
Requirements: an Apple Silicon MacBook (M1 or later) on macOS 13+ (verified on Sequoia and Tahoe). Intel Macs and desktops have no accelerometer, and a few laptop models don't expose it. Not sure? Run:
/Applications/Bonk.app/Contents/MacOS/Bonk --probe — listens for 5 seconds
and tells you whether your Mac's sensor streams data.
About the “unidentified developer” warning
Bonk isn't notarized by Apple yet (that requires a paid developer account). The warning doesn't mean the app is unsafe — it means Apple hasn't scanned it. The full source code is public on GitHub, and you can build it yourself with one command. Right-click → Open bypasses the warning once, permanently. If macOS instead claims the app “is damaged”, run this in Terminal:
xattr -cr /Applications/Bonk.app
Permissions
Bonk needs exactly one permission, in System Settings → Privacy & Security:
- Accessibility — lets Bonk press keyboard shortcuts on your behalf (lock screen, tab switching, your custom shortcuts) and notice when you're typing so those vibrations are ignored. Without it, knocks are detected but most actions silently do nothing.
Reading the accelerometer itself needs no permission. The settings window shows a live banner if Accessibility is missing.
Getting knocks to feel right
- Knock to Calibrate — in Settings, click it and knock 3× at your natural strength. The threshold is set to half your softest knock.
- Test mode — detects and logs knocks without firing any action, so you can tune risk-free.
- Detector status line — under the live waveform, it tells you exactly why the last knock did or didn't count (typing pause, cooldown, vibration, …).
- Knock near the trackpad — it's closest to the sensor.
Troubleshooting
| Problem | Fix |
|---|---|
| Warning icon in the menu bar | The sensor sent no data — likely an Intel Mac, a desktop, or one of the few models without the sensor. Run the probe command above to confirm, and make sure you're on the latest Bonk release. |
| Knocks detected but nothing happens | Grant Accessibility (Privacy & Security → Accessibility). Also check that Test mode is off and detection isn't paused. |
| Missed knocks | Run Knock to Calibrate, or lower the sensitivity threshold slider. Watch the detector status line to see what's filtering them. |
| False triggers | Raise the threshold or extend the cooldown. Setting objects down hard on the desk can look like a knock. |
| Double knocks register as two singles | Increase the knock window in Settings (how long Bonk waits for a follow-up knock). |
Deep debugging: Bonk logs every action to ~/Library/Logs/Bonk.log.
FAQ
Does it work on Intel Macs, desktops, or older macOS?
Bonk works on Apple Silicon MacBooks on macOS 13+ (verified on Sequoia and Tahoe). Intel Macs and desktops have no accelerometer, and a few laptop models reportedly don't expose it (e.g. the 2020 M1 MacBook Pro) — the probe command above gives your Mac a definitive yes or no in 5 seconds.
Does it drain the battery?
No. Bonk reads a low-power sensor the system already runs; idle CPU use is negligible.
Does any data leave my Mac?
No analytics, ever. The only network request is an optional daily version check against GitHub (toggleable in Settings). See Privacy.
Can different apps have different knock actions?
Yes — add per-app rules in Settings. A double knock can accept an AI suggestion in your editor and skip a track in your music app.