A simple macOS menubar application to control your Bluetooth earbuds. It allows you to quickly connect and disconnect your earbuds directly from the menubar, with visual status indication.
- Lives in your menubar with visual connection status (✓ connected, × disconnected)
- One-click connect/disconnect
- Pick your target device from a list of paired Bluetooth devices
- Battery level for the selected device, in the menubar and the status line
- Optional notifications on connect, disconnect, and low battery
- Optional launch at login
- Lightweight and native macOS experience
The easiest way is to grab a prebuilt release:
- Download the latest
MacBuds-vX.Y.Z.zipfrom the Releases page. - Unzip and drag
MacBuds.appto/Applications. - Because the app isn't code-signed, the first launch needs a right-click → Open to bypass Gatekeeper. After the first launch, it opens normally from the menubar.
The first launch may prompt for Bluetooth permission. Grant it so MacBuds can list paired devices and trigger connect/disconnect.
- Click the menubar icon and choose Select Device.
- Pick your earbuds (or any paired Bluetooth device) from the list.
- Use Connect / Disconnect to toggle the connection. The icon and status line update automatically.
To switch devices later, just choose Select Device again. Clear Selected Device resets the selection.
Open the Notifications submenu to toggle:
- Notify on connect
- Notify on disconnect
- Notify on low battery (fires once each as the level crosses 20% and 10%)
When the selected device is connected and reports a battery level, MacBuds shows it next to the menubar icon and in the status line, refreshing once a minute.
The level comes from IOBluetoothDevice, the same source macOS's own Bluetooth
settings pane uses. The selector isn't in the public headers, so MacBuds probes
for it at runtime and simply omits the percentage if a future macOS drops it.
Devices that don't report a level — and any disconnected device — show no
percentage rather than a wrong one.
To have MacBuds start automatically when you log in:
- Click the menubar icon
- Toggle "Launch at Login"
Prerequisites:
- macOS
- Go 1.26 or later (matches
go.mod) - Xcode Command Line Tools (for cgo + the
IOBluetoothframework headers)
git clone https://github.com/nilicule/macbuds.git
cd macbuds
go mod tidy
go build -o macbuds
./macbudsDev builds run from a raw binary (not a .app) may have Bluetooth access attributed to the terminal app rather than MacBuds — the simplest realistic dev loop is to run the workflow-built .app for end-to-end testing.
Release artifacts (packaged .app zips) are produced automatically by the GitHub Actions workflow at .github/workflows/release.yml whenever a GitHub Release is published.
This project is licensed under the GNU General Public License v3.0 - see LICENSE file for details.
GPL-3.0 is a copyleft license that requires anyone who distributes your code or a derivative work to make the source code available under the same terms. This ensures that modifications and larger works based on your code must also be free and open source.