How to Report a Bug in PI Desktop: Complete Guide to Built-in GitHub Integration

PI Desktop provides a built-in feedback mechanism that automatically captures your system environment and opens a pre-filled GitHub issue template when you click "Report a problem" in Settings → Info.

When you need to report a bug in PI Desktop, the application provides a streamlined, Main process-managed workflow that eliminates manual data entry. This Electron-based application (vastsa/PI-Desktop) automatically gathers version details, operating system, and architecture information to ensure every submission contains the context developers need for reproduction.

Reporting a Bug Through the PI Desktop Interface

The most direct way to report a bug in PI Desktop is through the Settings menu. Navigate to Settings → Info and click the Report a problem button. This triggers the Main process to collect runtime data and redirect your default browser to GitHub's issue creator with all fields pre-populated.

Technical Architecture of the Bug Reporting System

According to the docs/spec/06-delivery/03-ai-development-workflow.md specification, PI Desktop implements a Main-owned GitHub issue feedback pattern. This design keeps the feedback intake under strict control of Electron's Main process, preventing renderer-side manipulation of destination URLs and ensuring data integrity.

The workflow relies on three core functions exported from packages/shared/src/github-feedback.ts:

• osLabelForFeedback – Maps process.platform values to human-readable OS labels
• formatFeedbackEnvironment – Combines version, platform, architecture, protocol version, and host version into a structured string
• buildBugReportUrl – Constructs the GitHub URL using the bug_report.yml template with query parameters

Automatic Environment Capture

When you initiate a report, PI Desktop gathers the following diagnostic metadata:

• Application version
• Operating system platform and architecture
• Protocol version
• Host component version

This data is formatted into a standardized environment string that appears in the GitHub issue template, ensuring developers can reproduce bugs across different platforms.

GitHub Template Integration

The target template resides at .github/ISSUE_TEMPLATE/bug_report.yml. The buildBugReportUrl function appends URL parameters including app-version, os, and environment to pre-fill this template. Electron's shell.openExternal then launches your browser to this constructed URL, presenting a ready-to-submit issue form.

Programmatically Creating Bug Reports

Developers and advanced users can generate bug report URLs programmatically using the same utilities that power the UI. This is useful for building custom feedback tools or documentation:

import { buildBugReportUrl, osLabelForFeedback, formatFeedbackEnvironment } from '../packages/shared/src/github-feedback';
import { shell } from 'electron';

const feedbackInfo = {
  version: '0.13.3',
  platform: process.platform,
  arch: process.arch,
  protocolVersion: 12,
  hostVersion: '0.13.3'
};

const bugUrl = buildBugReportUrl(feedbackInfo);
shell.openExternal(bugUrl);

To retrieve the raw URL without opening a browser—for example, to display it in logs or documentation—call the function directly:

console.log(buildBugReportUrl({
  version: '0.13.3',
  platform: 'darwin',
  arch: 'arm64',
  protocolVersion: 12,
  hostVersion: '0.13.3'
}));
// Outputs: https://github.com/vastsa/PI-Desktop/issues/new?template=bug_report.yml&app-version=0.13.3&os=macOS&environment=PI-Desktop%200.13.3%20·%20darwin%20arm64%20·%20protocol%2012%20·%20host%200.13.3

Summary

• PI Desktop's bug reporting is accessible via Settings → Info → Report a problem
• The system automatically captures version, OS, architecture, protocol, and host data
• The workflow is controlled by Electron's Main process for security, as specified in docs/spec/06-delivery/03-ai-development-workflow.md
• Helper functions in packages/shared/src/github-feedback.ts handle URL construction and environment formatting
• Reports use the .github/ISSUE_TEMPLATE/bug_report.yml template for consistent structure

Frequently Asked Questions

Where is the "Report a problem" button located in PI Desktop?

The Report a problem button is located in Settings → Info. Clicking it initiates the Main process workflow that opens a pre-filled GitHub issue template in your default browser.

What system information is automatically included when reporting a bug in PI Desktop?

The report automatically includes your app version, operating system (platform and architecture), protocol version, and host version. These values are formatted by the formatFeedbackEnvironment function in packages/shared/src/github-feedback.ts to ensure developers have complete reproduction context.

Can I generate a bug report URL without clicking the UI button?

Yes. Import buildBugReportUrl from packages/shared/src/github-feedback.ts and pass an object containing your version, platform, arch, protocolVersion, and hostVersion. This returns a GitHub URL that you can open manually or display in documentation.

Why is the bug reporting logic handled by the Main process in PI Desktop?

The Main process ownership, documented in docs/spec/06-delivery/03-ai-development-workflow.md, prevents renderer-side code from manipulating the destination URL or feedback data. This security model ensures that bug reports cannot be intercepted or modified by potentially compromised renderer processes, maintaining the integrity of the feedback channel.

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