explaingit

ts1/bleunlock

3,796SwiftAudience · generalComplexity · 2/5Setup · easy

TLDR

BLEUnlock is a free Mac menu-bar app that automatically locks your computer when your iPhone or Apple Watch leaves Bluetooth range, and unlocks it when you return, no password typing required.

Mindmap

mindmap
  root((BLEUnlock))
    What it does
      Auto lock on leave
      Auto unlock on return
      Wake display on approach
    Setup
      Bluetooth access
      Accessibility permission
      Keychain access
    Features
      Custom scripts on events
      Pause media on lock
      Signal threshold control
    Tech
      Swift
      Bluetooth LE
      macOS Keychain
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Automatically lock your Mac whenever you leave your desk with your iPhone or Apple Watch in your pocket.

USE CASE 2

Unlock your Mac without touching a keyboard the moment you walk back into Bluetooth range.

USE CASE 3

Run a custom shell script every time your Mac locks or unlocks, for example, to pause Spotify or log an event.

Tech stack

SwiftBluetooth LEmacOS Keychain

Getting it running

Difficulty · easy Time to first run · 5min

Requires granting Bluetooth, Accessibility, and Keychain permissions in macOS System Settings before the app can lock or unlock the screen.

Distributed free of charge directly from GitHub, no App Store listing. Check the repository for the specific license terms.

In plain English

BLEUnlock is a free Mac utility that automatically locks and unlocks your computer based on whether your iPhone, Apple Watch, or another Bluetooth device is nearby. The idea is that when you walk away from your desk with your phone in your pocket, your Mac locks itself. When you return and your phone is close again, it unlocks without requiring you to type a password. The app sits in the menu bar and works by monitoring the Bluetooth signal strength of a paired device. You can configure how close the device needs to be before it triggers a lock or unlock, and how long to wait before locking after the signal disappears (to avoid false triggers if you briefly step away). There is also an option to wake the display from sleep automatically when your device approaches. A few other behaviors can be turned on: the app can pause music or video when you lock and resume it when you return, it can turn off the screen when locking, and it can run a custom script whenever a lock or unlock event happens. Your login password is stored in the Mac's Keychain, which is the system's secure password storage. Setup requires granting a few permissions: Bluetooth access, Accessibility (so the app can interact with the lock screen to type your password), and Keychain access. The README includes troubleshooting steps for common problems, such as the device not appearing in the scan list or Bluetooth conflicts with keyboards and mice. One technical note the README covers is MAC address stability. Bluetooth Low Energy devices sometimes change their identifier periodically for privacy reasons. Apple devices signed into the same Apple ID as the Mac resolve to a stable identifier, which is why iPhones and Apple Watches work reliably. Non-Apple devices with rotating addresses may not work. Installation is available through Homebrew or by downloading directly from the GitHub releases page. The app is distributed for free and is not on the Mac App Store.

Copy-paste prompts

Prompt 1
My iPhone doesn't appear in the BLEUnlock device scan list. How do I fix Bluetooth discovery on macOS?
Prompt 2
How do I write a shell script that BLEUnlock runs automatically every time my Mac locks?
Prompt 3
My Mac keeps locking even when I'm sitting at my desk. How do I adjust the signal-strength threshold in BLEUnlock to stop false triggers?
Prompt 4
How do I install BLEUnlock on my Mac using Homebrew?
Prompt 5
BLEUnlock stopped auto-unlocking after a macOS update. How do I reset its Accessibility and Keychain permissions?
Open on GitHub → Explain another repo

← ts1 on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.