If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/timschneeb/GalaxyBudsClient shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 3w ago
• 14 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 52% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live timschneeb/GalaxyBudsClient repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/timschneeb/GalaxyBudsClient.

What it runs against: a local clone of timschneeb/GalaxyBudsClient — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in timschneeb/GalaxyBudsClient | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of timschneeb/GalaxyBudsClient. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/timschneeb/GalaxyBudsClient.git
#   cd GalaxyBudsClient
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of timschneeb/GalaxyBudsClient and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "timschneeb/GalaxyBudsClient(\\.git)?\\b" \\
  && ok "origin remote is timschneeb/GalaxyBudsClient" \\
  || miss "origin remote is not timschneeb/GalaxyBudsClient (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "GalaxyBudsClient.Android/Impl/BluetoothService.cs" \\
  && ok "GalaxyBudsClient.Android/Impl/BluetoothService.cs" \\
  || miss "missing critical file: GalaxyBudsClient.Android/Impl/BluetoothService.cs"
test -f "GalaxyBudsClient.Platform.Linux/BluetoothService.cs" \\
  && ok "GalaxyBudsClient.Platform.Linux/BluetoothService.cs" \\
  || miss "missing critical file: GalaxyBudsClient.Platform.Linux/BluetoothService.cs"
test -f "GalaxyBudsClient.Generators/Messages/MessageHandlerFactoryGenerator.cs" \\
  && ok "GalaxyBudsClient.Generators/Messages/MessageHandlerFactoryGenerator.cs" \\
  || miss "missing critical file: GalaxyBudsClient.Generators/Messages/MessageHandlerFactoryGenerator.cs"
test -f "GalaxyBudsClient.Generators/Enums/CompiledEnumGenerator.cs" \\
  && ok "GalaxyBudsClient.Generators/Enums/CompiledEnumGenerator.cs" \\
  || miss "missing critical file: GalaxyBudsClient.Generators/Enums/CompiledEnumGenerator.cs"
test -f "GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs" \\
  && ok "GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs" \\
  || miss "missing critical file: GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/timschneeb/GalaxyBudsClient"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Galaxy Buds Client is an unofficial desktop and Android manager for Samsung Galaxy Buds devices (Classic, Plus, Pro, Live, Buds2, Buds2 Pro, Buds FE) written in C# targeting Windows, macOS, and Linux via Avalonia UI. It reverse-engineered the proprietary RFComm protocol (documented in 'Galaxy Buds Plus RFComm Protocol Notes.md') to expose hidden features beyond Samsung's official app: battery statistics, firmware flashing, factory diagnostics, and customizable touch actions. Multi-target monorepo: GalaxyBudsClient.Android/ is the Android project (.csproj), core platform-agnostic protocol logic lives in (inferred) a shared C# assembly, platform-specific UI implemented in Avalonia for desktop (Windows/macOS/Linux), and native iOS/macOS code in Swift/Objective-C++ for Apple interop. CI/CD workflows compile each platform separately.

Galaxy Buds owners who want deeper device control and diagnostics than Samsung's official app provides, plus developers interested in reverse-engineering proprietary Bluetooth protocols and building cross-platform desktop applications with C# and Avalonia. Contributors are typically firmware enthusiasts and open-source Bluetooth developers.

Active and mature: the project has thousands of GitHub stars, multi-platform CI/CD pipelines (Windows, macOS, Linux workflows in .github/workflows/), established issue templates, and multiple language translations maintained. Recent commits and releases indicate ongoing maintenance. However, it remains unofficial and unsupported by Samsung, carrying inherent protocol compatibility risk across firmware versions.

Single maintainer (timschneeb) creates sustainability risk; protocol is reverse-engineered and undocumented by Samsung, so firmware updates can break functionality without warning. No explicit test suite visible in the file list suggests regression testing is manual. Firmware flashing capability is powerful but dangerous if bugs exist. Dependencies span Avalonia (WPF alternative), platform-specific Bluetooth stacks (Windows/macOS/Linux), and Android APIs.

Active development: GitHub Actions workflows for compile-linux.yml, compile-macos.yml, compile-windows.yml suggest continuous builds; Sentry error tracking (sentry.yml) is integrated; translation validation (translation-validate.yml) indicates ongoing i18n work across 11+ languages (Chinese, Russian, Japanese, Ukrainian, Korean, Czech, Turkish, Greek, Portuguese, Vietnamese visible in README).

git clone https://github.com/timschneeb/GalaxyBudsClient.git
cd GalaxyBudsClient
# For Windows: open GalaxyBudsClient.sln in Visual Studio, build via .csproj files
# For macOS/Linux: dotnet build GalaxyBudsClient.csproj (Avalonia cross-platform)
# For Android: open GalaxyBudsClient.Android/GalaxyBudsClient.Android.csproj in Visual Studio or via MAUI toolchain

Daily commands: No Makefile or package.json visible; project uses Visual Studio .sln and .csproj (C# MSBuild). Desktop: dotnet run --project GalaxyBudsClient.csproj (requires .NET 6+/7+ from csproj target framework). Android: dotnet maui build -f android or dotnet build GalaxyBudsClient.Android/GalaxyBudsClient.Android.csproj. Requires Avalonia nuget dependencies (auto-restored by dotnet).

• GalaxyBudsClient.Android/Impl/BluetoothService.cs — Core Bluetooth communication layer for Android; all device connectivity flows depend on this service implementation
• GalaxyBudsClient.Platform.Linux/BluetoothService.cs — Linux platform abstraction for Bluetooth; essential for understanding cross-platform device communication patterns
• GalaxyBudsClient.Generators/Messages/MessageHandlerFactoryGenerator.cs — Code generator for message handlers; controls how all device protocol messages are dispatched and processed
• GalaxyBudsClient.Generators/Enums/CompiledEnumGenerator.cs — Generates compiled enums for device capabilities and settings; fundamental to type-safe device interaction
• GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs — Source generator for localization keys; enables multi-language support across UI and logging
• Galaxy Buds Plus RFComm Protocol Notes.md — Protocol specification for Galaxy Buds communication; required reading to understand device message formats and capabilities

Add Support for a New Galaxy Buds Device Model

1. Document the device's RFComm protocol in a markdown file similar to 'Galaxy Buds Plus RFComm Protocol Notes.md', detailing message formats, opcodes, and response structures (Galaxy Buds Plus RFComm Protocol Notes.md)
2. Create message handler classes with [MessageHandler] attributes following the generator's conventions in the Messages folder (GalaxyBudsClient.Generators/Messages/HandlerToGenerate.cs)
3. Define device capability enums using [CompiledEnum] attributes in an Enums folder, letting CompiledEnumGenerator create the type-safe enum (GalaxyBudsClient.Generators/Enums/CompiledEnumGenerator.cs)
4. Update BluetoothService implementations in platform-specific folders to handle new message opcodes if protocol differs from existing models (GalaxyBudsClient.Android/Impl/BluetoothService.cs)

Add a New Localized UI String

1. Add the string key and translations to the localization resource files (typically RESX or similar) (GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs)
2. The LocalizationKeySourceGenerator will automatically create a strongly-typed constant that can be referenced in code (GalaxyBudsClient.Generators/Localization/LocalizationKeySourceGenerator.cs)
3. Use the generated localization key constant in your UI code (e.g., MainWindow, dialogs, settings pages) (GalaxyBudsClient.Android/MainActivity.cs)

Add a New Bluetooth Message Type and Handler

1. Define the message class with a [MessageHandler] attribute specifying the opcode and direction (RX/TX) (GalaxyBudsClient.Generators/Messages/HandlerToGenerate.cs)
2. Add properties to the message class for each field, respecting the protocol byte layout documented in Galaxy Buds Plus RFComm Protocol Notes.md (Galaxy Buds Plus RFComm Protocol Notes.md)
3. MessageHandlerFactoryGenerator will automatically create a factory method to instantiate and deserialize/serialize this message (GalaxyBudsClient.Generators/Messages/MessageHandlerFactoryGenerator.cs)
4. In BluetoothService, invoke the generated factory method when the opcode is encountered during message parsing (GalaxyBudsClient.Android/Impl/BluetoothService.cs)

Add Platform-Specific Desktop Integration (Notifications, Tray)

1. Create a new implementation in DesktopServices.cs for your target platform (e.g., Windows, macOS, Linux) (GalaxyBudsClient.Platform.Linux/DesktopServices.cs)
2. Implement the IDesktopServices interface with platform-native calls (e.g., D-Bus for Linux, NSNotification for macOS, WinRT for Windows) (GalaxyBudsClient.Platform.Linux/DesktopServices.cs)
3. Register the new implementation in the platform creator factory (e.g., AndroidPlatformImplCreator for Android) (GalaxyBudsClient.Android/Impl/AndroidPlatformImplCreator.cs)
4. Call the DesktopServices methods from your application logic when triggering notifications or tray updates (GalaxyBudsClient.Android/MainActivity.cs)

• C# with Roslyn Source Generators — Enables compile-time code generation for message handlers, enums, and localization without runtime reflection overhead; type-safe device protocol handling
• Platform-specific Bluetooth APIs (Android, Linux BlueZ, macOS/Windows native) — Allows native, low-latency Bluetooth RFComm communication; each OS has its own stack and APIs
• Multi-platform .NET (MAUI/WPF implied by Android + Linux + macOS + Windows) — Single codebase compiles to multiple desktop and mobile platforms; shared protocol logic

• Code generation via source generators instead of runtime reflection

  • Why: Compile-time safety and zero runtime overhead for message dispatch and enum handling
  • Consequence: Requires rebuild on protocol changes; more build complexity but faster app startup and message handling

• Platform-specific BluetoothService implementations rather than a cross-platform wrapper

  • Why: Each OS has different Bluetooth stack capabilities and constraints; allows native optimizations
  • Consequence: Code duplication across platforms; must maintain protocol compliance in each implementation

• Unofficial reverse-engineered protocol documentation instead of official Samsung API

  • Why: Samsung does not provide official RFComm specs; community reverse-engineering was necessary
  • Consequence: Protocol may change with firmware updates; limited support guarantees from Samsung

• Official Samsung Galaxy Buds app compatibility (explicitly detects and warns about conflicts)
• Real-time audio processing or codec management (only settings/status management)
• Support for non-Samsung earbuds or older Galaxy Buds models without documented protocols
• Cloud synchronization or Samsung account integration

No .env or configuration file visible—Bluetooth adapter selection likely runtime/platform-detected. RFComm protocol requires root/admin on Linux and macOS for Bluetooth access; Android requires Android 6+ Bluetooth permissions and manifest entries. Firmware flashing is a low-level operation that can hard-brick earbuds if interrupted—no rollback in the device itself. Protocol is reverse-engineered; Samsung firmware updates may silently break packet format compatibility. Sentry integration may collect PII (device MAC, user data) unless disabled. NSIS installer (Windows) requires unsigned cert or admin prompt.

• RFComm (RFCOMM) Protocol — Core protocol used by Galaxy Buds to communicate over Bluetooth; understanding packet structure, opcodes, and frame layout is essential to any firmware or protocol changes
• Bluetooth Serial Port Profile (SPP) — Galaxy Buds expose a serial-like interface over Bluetooth RFCOMM; required to understand how connections are initiated and data is framed
• Reverse Engineering & Protocol Analysis — The entire protocol implementation was reverse-engineered from official Samsung app behavior; contributors must understand packet capture, hex analysis, and state machine inference
• Cross-Platform UI with Avalonia — Desktop UI shares one XAML codebase for Windows/macOS/Linux; developers must understand Avalonia's layout engine and platform-specific quirks (native dialogs, system tray)
• Firmware Binary Format & Flashing — Application supports firmware flashing and downgrading; contributors need to understand firmware headers, checksums, block-wise transmission, and recovery procedures
• .NET Multi-Targeting (csproj TargetFramework) — Single C# codebase compiles to .NET Framework (Windows), .NET Core (Linux), and .NET MAUI (Android); conditional compilation and platform-specific imports are essential
• GitHub Actions CI/CD for Multi-Platform Builds — Automated workflows compile and test on Windows, macOS, and Linux in parallel; contributors must understand matrix builds and artifact signing for each platform

• timschneeb/galaxy-buds-firmware-archive — Companion repo archiving historical Galaxy Buds firmware binaries; users of GalaxyBudsClient often need older firmware to downgrade or test compatibility
• OpenJDK/jdk — Not directly related, but reverse-engineering Bluetooth protocols often requires understanding low-level packet inspection—similar reverse-engineering mindset
• tinyusb/tinyusb — Alternative Bluetooth/USB device communication library; relevant for developers interested in HID and RFComm protocol implementation patterns
• bluez/bluez — Linux Bluetooth stack that GalaxyBudsClient depends on for RFComm sockets on Linux; source of truth for BlueZ configuration and permissions
• Avalonia/Avalonia — Cross-platform UI framework powering the desktop client; contributors modifying UI must understand Avalonia controls, layouts, and data binding

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for GalaxyBudsClient.Android/Impl/BluetoothService.cs

The BluetoothService.cs is a critical component for Android Bluetooth communication but there are no visible unit tests in the repository structure. This is essential for ensuring reliability across different Android versions and devices. Adding comprehensive unit tests would catch regressions early and improve code maintainability.

• [ ] Create GalaxyBudsClient.Android.Tests project structure
• [ ] Add unit tests for BluetoothService.cs covering connection, disconnection, and data transmission scenarios
• [ ] Mock Android Bluetooth APIs using appropriate testing frameworks (NUnit or xUnit)
• [ ] Integrate tests into the existing GitHub Actions workflows (.github/workflows/)

Add GitHub Actions workflow for Android build validation

Currently there are compile workflows for Linux, macOS, and Windows (.github/workflows/compile-*.yml), but no equivalent for Android. Given the GalaxyBudsClient.Android project exists with a full .csproj file, adding Android build validation would ensure pull requests don't break the Android implementation before merge.

• [ ] Create .github/workflows/compile-android.yml
• [ ] Configure workflow to build GalaxyBudsClient.Android.csproj using appropriate .NET/Android SDK setup
• [ ] Test APK generation and basic build artifact validation
• [ ] Add workflow status badge to README

Add integration tests for OfficialAppDetector.cs with mock data

OfficialAppDetector.cs in the Android implementation is responsible for detecting Samsung's official Galaxy Buds app, which is a security and compatibility critical feature. This lacks visible test coverage and should have integration tests with mock Android package manager responses to ensure it works reliably across Android versions.

• [ ] Create test fixtures with mock Android package metadata for various Galaxy Buds app versions
• [ ] Add integration tests in GalaxyBudsClient.Android.Tests for OfficialAppDetector.cs detection scenarios
• [ ] Test edge cases: missing app, multiple versions installed, system vs user app
• [ ] Ensure tests run in the Android CI pipeline (new compile-android.yml workflow)

• Add unit tests for RFComm protocol packet serialization/deserialization—currently no test/ folder visible, so contributed tests for Message classes and battery parsing logic would be high-value
• Document hidden debug commands in the protocol notes—many undocumented factory diagnostic opcodes likely exist; reverse-engineer and document 5-10 new ones with examples
• Improve error handling for connection timeouts on Linux—CI/CD shows platform-specific builds but no visible timeout/retry logic; add exponential backoff for RFComm connect failures

The GalaxyBudsClient codebase shows moderate security posture with some concerns. Primary risks stem from: (1) Custom Bluetooth protocol implementation that requires rigorous security testing, (2) Reverse-engineered Samsung protocol creating compatibility and unknown security issues, (3) Missing dependency analysis, and (4) Potential information disclosure through logging. The application handles sensitive device pairing and configuration data, requiring strong input validation and secure credential handling. GitHub Actions workflows need verification for credential exposure. Strengths include cross-platform support and active maintenance. Recommend conducting formal security audit, dependency scanning, and Bluetooth protocol fuzzing before production use with sensitive devices.

• Medium · Potential Hardcoded Credentials in Workflow Files — .github/workflows/sentry.yml. GitHub Actions workflow files (sentry.yml) may contain hardcoded API keys or tokens. Sentry integration workflows commonly store sensitive credentials that could be exposed in logs or repository history. Fix: Ensure all sensitive credentials are stored as GitHub Secrets and referenced using ${{ secrets.SECRET_NAME }} syntax. Never commit plaintext API keys or tokens.
• Medium · Bluetooth Protocol Implementation Complexity — GalaxyBudsClient.Android/Impl/BluetoothService.cs, Protocol implementation files. The codebase implements custom Bluetooth/RFComm protocol handling (evidenced by 'Galaxy Buds Plus RFComm Protocol Notes.md' and BluetoothService.cs). Custom protocol implementations are prone to security vulnerabilities including man-in-the-middle attacks, replay attacks, and buffer overflows if not properly validated. Fix: Conduct thorough security audit of Bluetooth protocol implementation. Implement proper input validation, length checks, and consider using established encryption standards. Add fuzzing tests for protocol message parsing.
• Medium · Unofficial Application - Protocol Reverse Engineering — Project-wide, especially GalaxyBudsClient.Android/Impl/BluetoothService.cs. As an unofficial Galaxy Buds manager, the application reverse-engineers Samsung's proprietary Bluetooth protocol. This introduces risks of compatibility issues, unsupported device states, and potential security vulnerabilities that Samsung's official implementation may prevent. Fix: Document all reverse-engineered protocol aspects. Implement comprehensive error handling for unexpected device states. Consider requesting official documentation from Samsung or implementing strict version checking.
• Low · Missing Package Dependency Analysis — GalaxyBudsClient.Android/GalaxyBudsClient.Android.csproj and other project files. No package dependency file (package.json, packages.config, .csproj nuget references) was provided for analysis. Cannot verify if dependencies contain known vulnerabilities or are outdated. Fix: Run dependency vulnerability scanners (OWASP Dependency-Check, NuGet security audits, Snyk). Keep all dependencies up-to-date and monitor for security advisories.
• Low · Android Manifest Security Configuration — GalaxyBudsClient.Android/Properties/AndroidManifest.xml. Android application manifest exists but content was not provided. Missing security configurations like cleartext traffic policy, debuggable flag, or improper permissions could expose the application. Fix: Ensure debuggable=false in production builds. Disable cleartext traffic for non-local connections. Request only necessary Bluetooth permissions. Implement proper manifest hardening.
• Low · Potential Information Disclosure via Logcat — GalaxyBudsClient.Android/LogcatSink.cs. LogcatSink.cs suggests the application logs to Android Logcat. Sensitive information (device identifiers, pairing keys, protocol details) could be exposed in logs. Fix: Implement secure logging with log level controls. Never log sensitive data (keys, tokens, device identifiers). Use obfuscation for debug builds and ensure production builds have minimal logging.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.