blunt 🔵

A little tool that keeps your computer awake when a specified Bluetooth device is nearby. Think of it like a digital leash for your system.

What it does

• Detects if a specific personal Bluetooth device (like your phone or watch) is nearby
• Prevents your computer from going to sleep while that device is in range
• Runs quietly in the background as a daemon

Dependencies

You'll need these installed on your system:

• Go 1.21+ - to build it
• bluez-utils - for hcitool and l2ping (the Bluetooth magic)
• systemd - for systemd-inhibit (the "don't sleep" magic)

On Arch:

sudo pacman -S bluez-utils

On Ubuntu/Debian:

sudo apt install bluez

On Fedora:

sudo dnf install bluez

Quick Install

go install github.com/weop/blunt@latest
blunt -i  # copy to ~/.local/bin and set up systemd service

Building

go build -o blunt .

Or just:

go build .

Installation

The easiest way:

./blunt -i
# or
./blunt --install

This will:

1. Copy blunt to ~/.local/bin/
2. If systemd user services are available, ask if you want to install it as a user service
3. Enable the service (but not start it automatically)

After installing, make sure ~/.local/bin is in your PATH:

export PATH="$PATH:$HOME/.local/bin"

Then configure your device and start the service:

blunt  # configure your device
systemctl --user start blunt  # start the daemon

Uninstall

blunt -u
# or
blunt --uninstall

This will remove the binary, systemd service, and optionally your configuration.

Usage

First time setup

Run it without any flags to pick your "unlock" device:

./blunt

It'll scan for nearby Bluetooth devices, show you a list, and ask you to pick one. This gets saved to ~/.blunt so you don't have to do it again.

Manually adding a device

If scanning doesn't find your device, you can add it by hand. Edit (or create) ~/.blunt and set the MAC address directly:

{
  "device_mac": "AA:BB:CC:DD:EE:FF",
  "device_name": "My Phone"
}

Replace AA:BB:CC:DD:EE:FF with your phone's Bluetooth MAC address.

Finding your phone's Bluetooth MAC address

• Android: Settings → About Phone → Status → Bluetooth address
• iPhone: Settings → General → About → Bluetooth

Start the daemon

./blunt -d

This runs it in the background. If you haven't set up a device yet, it'll complain and tell you to run ./blunt first.

Check if it's working

./blunt status

Shows your configured device and whether the daemon is running.

Stop the daemon

./blunt stop

Kills the background process. Your computer will go back to normal sleep behavior.

How it works

• Config lives at ~/.blunt (it's just JSON, you can edit it by hand if you want)
• The daemon checks every few seconds (default: 5s) if your device is in range
• Uses hcitool con to check active connections, or l2ping to ping the device
• Uses systemd-inhibit to prevent system sleep AND idle (screen lock)

Will this prevent my screen locker?

Yes, if your screen locker uses systemd/logind for idle detection. blunt takes an idle inhibition lock which tells the system "this session is not idle" - preventing screen lockers from triggering.

If your screen locker doesn't use systemd (pure Wayland idle protocols), you might need to configure it separately to check for the presence of blunt or use a wrapper script.

Troubleshooting

"hcitool not found" - Install bluez-utils (see Dependencies)

Device not showing up during setup - Make sure your phone/earbuds/whatever are in pairing/discoverable mode. Or just enter the MAC address manually - you can find it in your phone's Bluetooth settings.

Daemon says device is absent but it's right there - Bluetooth can be finicky. Try moving the device closer or increasing the check interval in the config.

"Can't create socket: Operation not permitted" - l2ping needs special permissions. The tool will still work using hcitool con to detect connected devices, but l2ping provides faster detection for devices that aren't actively connected. To enable it:

sudo setcap cap_net_raw+eip /usr/bin/l2ping

Device shows as "not reachable" in status - Make sure Bluetooth is enabled on your phone and it's not in airplane mode. The device doesn't need to be discoverable, just have Bluetooth on.

License

Do whatever you want with it.