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

> Get expert support for CodexBar by gathering app details, checking processes, and documenting Keychain prompts. Submit a privacy-preserving GitHub issue quickly.

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

---

**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`](https://github.com/steipete/CodexBar/blob/main/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:

```bash
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`](https://github.com/steipete/CodexBar/blob/main/CHANGELOG.md) and dependencies defined in [`Package.swift`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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:

```bash
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`](https://github.com/steipete/CodexBar/blob/main/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:

```bash

# 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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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`](https://github.com/steipete/CodexBar/blob/main/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.