# Bluetooth Debug

> This skill should be used when the user asks to "debug bluetooth", "bluetooth not working", "check bluetooth", "airpods not connecting", "bluetooth devices", or mentions pairing issues. Collects Bluetooth state on macOS and writes a JSON result to ~/.mac-guardian/data/.

- Skill: `dennisonbertram/bluetooth-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dennisonbertram/bluetooth-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dennisonbertram/bluetooth-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dennisonbertram (https://skillmd.com/u/dennisonbertram)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dennisonbertram/bluetooth-debug

---


# bluetooth-debug

Reports on the Bluetooth subsystem: controller power state, paired devices, connected devices, battery levels where available, and recent log events.

## When to invoke

Trigger on phrases like: "debug bluetooth", "bluetooth not working", "check bluetooth", "airpods not connecting", "bluetooth devices".

## Primary source

`system_profiler SPBluetoothDataType -json 2>/dev/null`.

Parse the resulting JSON with `jq` when available, otherwise with grep/awk. Key fields of interest:

- `controller_properties.controller_state` (On / Off)
- `controller_properties.controller_address`
- `device_connected` (array of currently connected devices)
- `device_not_connected` (array of paired but disconnected devices)

For each device, extract:

- `device_name` (or first key if unnamed)
- `device_address`
- `device_batteryLevelMain` / `device_batteryLevelLeft` / `device_batteryLevelRight` / `device_batteryLevelCase`
- `device_firmwareVersion`
- `device_productID` / `device_vendorID`

## Severity

- Controller off: `warn` with summary "Bluetooth is off."
- Controller on, any connected device battery < 20%: `warn` per device.
- Controller on, otherwise: `ok`.

## Recent events

`log show --style compact --last 2h --predicate 'subsystem CONTAINS "bluetooth"' 2>/dev/null | tail -40`.

Truncate and include in `raw.log_tail`. Skip gracefully on no output.

## Output contract

Standard envelope. Write to `~/.mac-guardian/data/bluetooth-debug-<ISOdate>.json`.

Summary example: "Controller on, 3 paired (2 connected). AirPods Pro 14% battery."

## Handoff

- On direct invocation: `bash ${CLAUDE_PLUGIN_ROOT}/scripts/render-single.sh bluetooth-debug`.
- When invoked by `daily-health-report`, return JSON path only.

## Safety

- Read-only. Never unpair devices, never toggle Bluetooth.
- Do not request `sudo`.
- If `system_profiler` is not installed (very unusual), emit an `info` finding explaining the missing tool and exit cleanly.