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.