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.