btsnoop-analyzer

Analyze Bluetooth btsnoop/HCI traces into structured protocol diagnostics.

2|Updated Mar 10, 2026
One-click install
npx skills add https://github.com/Vudentz/btsnoop-analyzer --skill btsnoop-analyzer
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: btsnoop-analyzer
Source: https://github.com/Vudentz/btsnoop-analyzer/tree/main
Command: npx skills add https://github.com/Vudentz/btsnoop-analyzer --skill btsnoop-analyzer

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Automates in-depth analysis of Bluetooth btsnoop/HCI traces to detect protocol errors, annotate key frames, and produce a structured diagnostic report for debugging connection, pairing, and streaming issues.

Core Features & Use Cases

  • Five-step deterministic pipeline: detection, prefiltering, annotation, diagnostics, and optional LLM-powered analysis.
  • Focus-aware analysis: auto-detects or accepts user focus (A2DP, LE Audio, HFP, SMP, L2CAP, advertising, etc.) and loads relevant annotators and docs.
  • Privacy and CI integration: optional MAC anonymization, local btmon decoding, and a reusable GitHub Action for posting results as issue comments.
  • Use cases: debug audio streaming disconnects, troubleshoot pairing failures, verify GATT discovery flows, analyze L2CAP/channel issues, and assess advertising/coexistence effects.

Quick Start

Provide a trace URL or local decoded trace and request analysis; the skill will decode (with btmon), optionally anonymize, run the pipeline, and produce a structured diagnostic report.

Frequently Asked Questions about btsnoop-analyzer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I analyze a Bluetooth btsnoop trace to debug audio streaming disconnects?

To analyze a Bluetooth btsnoop trace, you can run a five-step deterministic pipeline that detects protocol errors, annotates key frames, and generates a structured diagnostic report for audio streaming disconnects. It requires btmon for decoding and Python 3 to execute the pipeline.

What is the best way to troubleshoot Bluetooth pairing failures from an HCI trace?

Troubleshooting Bluetooth pairing failures from an HCI trace involves applying focus-aware analysis to protocols like SMP. The pipeline prefilters relevant frames, annotates key events, and optionally uses an LLM to produce a structured diagnostic report explaining the failure.

Can I run btsnoop trace analysis locally without sending data to an LLM provider?

Yes, you can run btsnoop trace analysis entirely locally without LLM provider credentials. The skill supports local-only operation using btmon for decoding and Python 3 for the deterministic pipeline, while offering optional LLM integration only for final report generation.

Does this Bluetooth trace analyzer support CI integration and MAC address anonymization?

Yes, the Bluetooth trace analyzer supports CI integration through a reusable GitHub Action that posts diagnostic results as issue comments. It also includes optional MAC address anonymization to protect privacy during protocol analysis.

How do I verify a GATT discovery flow using a decoded btmon trace?

To verify a GATT discovery flow, provide a decoded btmon trace and request analysis with a GATT focus. The pipeline applies relevant annotators and documentation to assess the L2CAP channels and GATT discovery flow, outputting a structured diagnostic report.

Why does my Bluetooth LE Audio connection drop, and how can trace analysis help?

Bluetooth LE Audio connection drops can be diagnosed by analyzing the btsnoop trace for protocol errors and disconnection indicators. The pipeline applies focus-aware annotators to LE Audio frames, generating a structured report to identify the root cause of the streaming issue.