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

> Report CodexBar bugs effectively using the GitHub Issues tracker. Learn how to submit bug reports and get faster resolutions by following our comprehensive guide.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-07

---

**Report CodexBar bugs through the [GitHub Issues tracker](https://github.com/steipete/CodexBar/issues) by creating a new issue, applying the `bug` label, and following the guidelines in [`docs/ISSUE_LABELING.md`](https://github.com/steipete/CodexBar/blob/main/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](https://github.com/steipete/CodexBar/issues) of the repository.

According to the [`docs/ISSUE_LABELING.md`](https://github.com/steipete/CodexBar/blob/main/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](https://github.com/steipete/CodexBar/issues) 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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/docs/providers.md) and reproduce the issue locally.

### 4. Attach Redacted Logs

Include screenshots or log excerpts that demonstrate the problem. The [`README.md`](https://github.com/steipete/CodexBar/blob/main/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:

```bash

# 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`](https://github.com/steipete/CodexBar/blob/main/README.md) — Contains general project overview and privacy warnings about credential safety.
- [`docs/ISSUE_LABELING.md`](https://github.com/steipete/CodexBar/blob/main/docs/ISSUE_LABELING.md) — Defines the `bug` label and provides detailed filing instructions.
- [`docs/providers.md`](https://github.com/steipete/CodexBar/blob/main/docs/providers.md) — Lists supported providers; useful when reporting provider-specific issues.
- [`.github/ISSUE_TEMPLATE/bug_report.yml`](https://github.com/steipete/CodexBar/blob/main/.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](https://github.com/steipete/CodexBar/issues).
- Apply the `bug` label as defined in [`docs/ISSUE_LABELING.md`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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](https://github.com/steipete/CodexBar/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`](https://github.com/steipete/CodexBar/blob/main/README.md) file specifically warns against posting credentials, as these could compromise your accounts if exposed in public GitHub issues.