How to Report a Bug in OpenLogi: A Complete Guide to Effective Issue Reporting

To report a bug in OpenLogi, use the structured GitHub issue template at .github/ISSUE_TEMPLATE/bug_report.yml and include device details, version information, and a diagnostics dump generated via the GUI's "Copy Diagnostics" feature or CLI debug logging.

OpenLogi relies on the HID++ protocol to communicate with Logitech hardware, making precise device and connection details essential for reproducible bug reports. The project provides a dedicated GitHub issue template that automates labeling and guides reporters through required fields. Following the official reporting workflow ensures maintainers can triage and diagnose issues efficiently.

Using the Official Bug Report Template

The fastest way to submit a valid bug report is to start from the template at .github/ISSUE_TEMPLATE/bug_report.yml in the AprilNEA/OpenLogi repository. This YAML-formatted template automatically applies the type: bug label and a needs: triage tag, routing your issue to the correct workflow filled with structured fields rather than free-form text.

Pre-Flight Checklist Before Reporting

Before creating a new issue, complete the checklist embedded in the template:

• Search existing issues to avoid duplicates.
• Update to the latest release (or test against a recent master build).
• Quit Logitech Options+—only one application may own a HID++ receiver at a time.

Missing any of these steps often results in bugs being marked "impossible to reproduce" according to the template's opening note.

Required Information for HID++ Debugging

Core Metadata Fields

The template requires specific fields that pinpoint hardware and software context:

• Component—specify whether the bug affects the GUI, CLI, or both.
• OpenLogi version—retrieve this from the GUI's About window or via openlogi --version.
• Operating system and OS version/architecture (macOS is the primary supported platform).
• Device model—e.g., "MX Master 3S + Logi Bolt receiver".
• Connection type—Logi Bolt, Bluetooth-direct, wired USB, or other.

Selecting Affected Areas

Choose all relevant categories from the multi-select field, such as Button remapping, DPI control, SmartShift, or Menu bar / tray. This categorization routes the issue to maintainers with specific domain knowledge.

Capturing Diagnostic Data

Providing a diagnostics dump gives maintainers a privacy-filtered snapshot of versions, capabilities, and internal state, dramatically speeding up diagnosis.

GUI Method

1. Open the About window (menu → OpenLogi → About).
2. Click Copy Diagnostics.
3. Paste the clipboard contents into the "Diagnostics report" textarea of the issue form.

CLI Method

Use the following commands to gather version, device list, and debug logs:

# Show the installed OpenLogi version

openlogi --version

# List connected devices and pairing state

openlogi list

# Run a command with verbose logging for the "Logs" field

OPENLOGI_LOG=debug openlogi list

Include the output of openlogi list to show receiver/device IDs and pairing state, as referenced in docs/USAGE.md.

macOS Permission Verification

If you are on macOS, verify system permissions before submitting. The template includes a macOS permissions section where you must confirm that Accessibility and Input Monitoring checkboxes are correctly set for OpenLogi. Missing permissions are a common source of "bugs" that are actually configuration issues.

Structuring the Bug Description

After filling in the metadata fields:

1. Describe the problem—write a clear, concise narrative of what happened versus what you expected.
2. Supply reproducible steps—enumerate the exact actions that trigger the bug, numbered sequentially.
3. Attach logs—paste the output from OPENLOGI_LOG=debug openlogi <command> or the GUI diagnostics into the Logs field.

Once all required fields are populated, click Submit new issue. The maintainers will triage it automatically, and you’ll receive a reference number for future discussion.

Summary

• Use the template: Start every bug report from .github/ISSUE_TEMPLATE/bug_report.yml to ensure proper labeling and structure.
• Include device specifics: HID++ protocol debugging requires exact device models, connection types, and OpenLogi versions.
• Attach diagnostics: Use About → Copy Diagnostics in the GUI or run OPENLOGI_LOG=debug openlogi list in the CLI to capture state snapshots.
• Check permissions: On macOS, confirm Accessibility and Input Monitoring rights before reporting.
• Verify uniqueness: Search existing issues and test against the latest master build to avoid duplicates.

Frequently Asked Questions

Where is the bug report template located in the OpenLogi repository?

The bug report template is located at .github/ISSUE_TEMPLATE/bug_report.yml in the AprilNEA/OpenLogi repository. This file defines the structured form that appears when you select "Bug report" from the GitHub issue creation menu, automatically applying the type: bug and needs: triage labels.

Why does OpenLogi require device connection type in bug reports?

OpenLogi communicates with Logitech hardware using the HID++ protocol, and behavior varies significantly between connection methods like Logi Bolt, Bluetooth-direct, and wired USB. The connection type determines how the software initializes the device handle and parses feature reports, so omitting this detail often makes bugs impossible to reproduce.

How do I generate debug logs from the OpenLogi CLI?

Set the environment variable OPENLOGI_LOG=debug before running any command. For example, execute OPENLOGI_LOG=debug openlogi list to capture verbose output showing protocol handshakes and device enumeration. Paste this output into the Logs field of the issue template.

What should I do if I also use Logitech Options+?

Quit Logitech Options+ completely before testing or reporting bugs. Only one application may own the HID++ receiver at a time; running both simultaneously causes device access conflicts that appear as OpenLogi bugs but are actually resource contention issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}