Where to Report Bugs for CodexBar: The Complete GitHub Issues Guide

Report CodexBar bugs through the GitHub Issues tracker by creating a new issue, applying the bug label, and following the guidelines in docs/ISSUE_LABELING.md.

CodexBar is a menu bar application for tracking AI API usage across multiple providers. When you encounter crashes, parsing errors, or authentication failures, knowing exactly where to report bugs for CodexBar ensures maintainers can reproduce and fix issues quickly. The project uses GitHub Issues as its centralized bug tracking system, with specific labeling conventions defined in the repository documentation.

GitHub Issues Is the Official Bug Tracker

The steipete/CodexBar repository uses GitHub Issues as the single source of truth for all defect reports. Whether you experience usage parsing failures, platform-specific crashes, or provider authentication errors, every bug report belongs in the Issues section of the repository.

According to the docs/ISSUE_LABELING.md file, the project defines a bug as "broken behavior, crash, mismatch, false negative, bad parsing, auth failure". This definition helps you categorize issues correctly when filing reports.

Step-by-Step Bug Reporting Process

Follow these steps to submit an effective bug report that maintainers can act on immediately.

1. Create a New Issue

Navigate to the CodexBar Issues page and click the New issue button. This creates a dedicated thread for maintainers to triage, discuss, and resolve the problem.

2. Apply the Bug Label

Select the bug label when creating the issue. The docs/ISSUE_LABELING.md file explicitly defines this label for tracking defects including crashes and authentication failures. Proper labeling allows the team to sort and prioritize real defects separately from feature requests or questions.

3. Write a Clear Description

Include specific details in your report:

• The affected provider (e.g., "OpenAI usage parsing fails")
• Platform version information (macOS 14+, Swift 6.2+)
• Exact steps to reproduce the error

This information enables developers to locate the relevant code path in files like docs/providers.md and reproduce the issue locally.

4. Attach Redacted Logs

Include screenshots or log excerpts that demonstrate the problem. The README.md contains a privacy note reminding users to never post raw API keys, tokens, or passwords. Always redact sensitive credentials before attaching debug information.

5. Link Related Documentation

If the bug is specific to a particular AI provider, link to the official provider documentation. This context helps maintainers understand expected behavior versus actual behavior.

Reporting Bugs from the Command Line

You can automate bug reporting using the GitHub CLI without opening a browser. Install the CLI via Homebrew (brew install gh), then create an issue directly from your terminal:

# Create a bug report using GitHub CLI

gh issue create \
  --repo steipete/CodexBar \
  --title "OpenAI usage parsing returns incorrect credits" \
  --body "Steps to reproduce: ...\n\nEnvironment: macOS 14, Swift 6.2, CodexBar v2.3.1\n\n(Logs attached, credentials redacted)" \
  --label bug

This method automatically applies the bug label and routes the issue to the correct repository.

Key Files and Documentation

Understanding these files helps you write better bug reports:

• README.md — Contains general project overview and privacy warnings about credential safety.
• docs/ISSUE_LABELING.md — Defines the bug label and provides detailed filing instructions.
• docs/providers.md — Lists supported providers; useful when reporting provider-specific issues.
• .github/ISSUE_TEMPLATE/bug_report.yml — If present, pre-populates the issue body with required fields.

Summary

• Report all CodexBar bugs through the GitHub Issues tracker.
• Apply the bug label as defined in docs/ISSUE_LABELING.md for crashes and parsing errors.
• Include environment details, reproduction steps, and redacted logs in your report.
• Never include API keys or tokens in bug reports, per the README.md security guidelines.
• Use the GitHub CLI to create issues programmatically with the --label bug flag.

Frequently Asked Questions

Where do I report bugs for CodexBar?

Report bugs in the steipete/CodexBar GitHub Issues tracker. This is the centralized location where maintainers triage defects, request additional information, and link related pull requests.

What information should I include in a CodexBar bug report?

Include the affected provider name (e.g., OpenAI, Anthropic), your macOS and Swift versions, steps to reproduce the issue, and any relevant logs or screenshots. Ensure you redact all API keys and authentication tokens before sharing debug information.

Can I report bugs without using the GitHub web interface?

Yes. Use the GitHub CLI (gh) to create issues from the command line. Run gh issue create --repo steipete/CodexBar --title "Your title" --label bug to submit reports directly from your terminal.

How do I protect sensitive data when reporting a bug?

Always remove API keys, tokens, and passwords from logs and screenshots before attaching them to an issue. The README.md file specifically warns against posting credentials, as these could compromise your accounts if exposed in public GitHub issues.

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