How to Get Support for CodexBar: A Privacy-Preserving Troubleshooting Guide

To get support for CodexBar, gather your app version and resolved configuration via CLI commands, check for lingering processes using pgrep, document any Keychain prompts with redacted screenshots, and submit a GitHub issue following the checklist in docs/keychain-prompts.md without exposing API keys or passwords.

This guide explains how to get support for CodexBar, an open-source macOS utility maintained in the steipete/CodexBar repository. When you encounter issues—whether persistent Keychain authentication prompts or configuration validation errors—the project provides a structured support workflow that enables maintainers to reproduce and diagnose problems while ensuring your sensitive credentials remain private.

Gather System Context and Version Information

The first step in requesting CodexBar support is capturing your current environment details. Open Terminal and run the following commands to output diagnostic data:

codexbar --version               # prints the app version (e.g., v5.7.2)

codexbar config dump --pretty    # shows the resolved config file (redacted values are omitted)

Record your macOS version by running sw_vers and note your installation source—whether you installed via Homebrew cask, direct GitHub release, or Sparkle update. This information helps maintainers correlate your issue with specific release artifacts listed in CHANGELOG.md and dependencies defined in Package.swift.

Identify Prompt Sources and Lingering Processes

If you are experiencing unwanted Keychain or "Safe Storage" prompts, consult the repository's Keychain prompts documentation at docs/keychain-prompts.md. This file explains the exact prompt text semantics and how to safely report them.

Before opening an issue, verify that no stray CodexBar processes remain active—a common cause of issues after uninstall:

pgrep -fl 'CodexBar|CodexBarCLI'      # list lingering processes

Additionally, check your filesystem for multiple app copies that might be launching simultaneously. Common locations include /Applications/CodexBar.app, the Homebrew cellar path, and Sparkle update directories. Finally, confirm whether the app remains listed in System Settings → General → Login Items, as orphaned entries can trigger background process conflicts.

Create a GitHub Support Issue

When you are ready to file an issue in the steipete/CodexBar repository, follow the "What to include in a support issue" checklist detailed in docs/keychain-prompts.md. Your report should typically contain:

• CodexBar version and installation source
• macOS version (sw_vers output)
• Results of the pgrep command indicating whether any CodexBar processes remain active
• Login Items status (whether the app is still listed in System Settings)
• Screenshot of any Keychain prompt (with secret values redacted)

Critical privacy note: Never paste passwords, cookie headers, OAuth tokens, API keys, or raw Keychain item values into the GitHub issue. While the codexbar config dump --pretty command automatically filters sensitive data, always review screenshots to ensure credentials are obscured.

Debug Commands and Isolation Techniques

For advanced troubleshooting, CodexBar provides CLI commands to inspect provider configurations and validate your setup:

# Show enabled providers and authentication methods

codexbar config providers --json --pretty

# Validate config file syntax after manual edits

codexbar config validate

If you suspect a provider-specific authentication issue involves the Keychain, isolate the problem by temporarily disabling Keychain access:

1. Open CodexBar → Settings → Advanced
2. Enable Disable Keychain access
3. Relaunch the app

This procedure determines whether the issue stems from the Keychain integration layer implemented in the app or from the provider's own API endpoints, as documented in docs/cli-configuration.md.

Summary

• Capture version info using codexbar --version and codexbar config dump --pretty before reporting issues.
• Check for conflicts by running pgrep -fl 'CodexBar|CodexBarCLI' and verifying Login Items in System Settings.
• Follow the checklist in docs/keychain-prompts.md when submitting GitHub issues.
• Protect your credentials by never sharing API keys, passwords, or Keychain values; use screenshots with redacted secrets.
• Isolate Keychain issues via Settings → Advanced → Disable Keychain access and validate configuration with codexbar config validate.

Frequently Asked Questions

How do I check if CodexBar processes are still running after uninstalling?

Run pgrep -fl 'CodexBar|CodexBarCLI' in Terminal to list any lingering processes. If output appears, terminate those processes via Activity Monitor or kill commands. Also check System Settings → General → Login Items to ensure no orphaned entries remain, as these can cause background conflicts even after the app is removed from /Applications.

What information should I redact before submitting a CodexBar support screenshot?

Remove or blur any visible passwords, API keys, OAuth tokens, cookie headers, or Keychain item values from your screenshots. While the codexbar config dump --pretty command automatically filters sensitive data, manual screenshots of Keychain prompts or terminal output may expose credentials if not reviewed carefully.

Where can I find the configuration validation commands for CodexBar?

The CLI configuration reference is located in docs/cli-configuration.md within the repository. This document details the codexbar config validate command for checking file syntax, codexbar config providers --json --pretty for inspecting provider setups, and codexbar config dump --pretty for reviewing resolved settings without exposing secrets.

How do I temporarily disable Keychain access to isolate authentication issues?

Navigate to CodexBar → Settings → Advanced and enable Disable Keychain access, then relaunch the application. This setting prevents CodexBar from reading or writing to the macOS Keychain, allowing you to determine whether authentication failures originate from the Keychain integration layer or the provider's API configuration itself.

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