How to Set Up OAuth for AI Providers in CodexBar: A Complete Configuration Guide

CodexBar automatically manages OAuth authentication for Codex, Claude, Gemini, and Vertex AI through provider-specific credential stores that read JSON configuration files, interact with the macOS Keychain, and delegate to official CLIs to refresh tokens before they expire.

CodexBar is a macOS menu bar application that aggregates usage metrics and billing information from multiple AI providers. Setting up OAuth for AI providers in CodexBar requires understanding how the app discovers existing credentials, validates token freshness, and orchestrates secure storage. This guide walks through the authentication flow as implemented in the steipete/CodexBar repository, covering manual CLI setup, automatic refresh mechanisms, and programmatic access patterns.

How CodexBar Discovers and Loads OAuth Credentials

When CodexBar launches, each provider implementation checks for existing authentication through a cascading discovery process. The credential stores prioritize environment variables, then fall back to provider-specific JSON files in the home directory.

For Codex (OpenAI), the CodexOAuthCredentialsStore.load method in Sources/CodexBarCore/Providers/Codex/CodexOAuth/CodexOAuthCredentials.swift (lines 65-78) parses ~/.codex/auth.json created by the official codex CLI.

For Claude (Anthropic), ClaudeOAuthCredentialsStore.loadFromEnvironment in Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthCredentials.swift (lines 92-98) first checks for the CODEXBAR_CLAUDE_OAUTH_TOKEN environment variable, then reads ~/.claude/.credentials.json.

Provider-Specific Setup Instructions

Codex (OpenAI-Compatible)

The Codex provider integrates with OpenAI's authentication system. To configure:

1. Install and authenticate the official Codex CLI:

   codex login

2. This creates ~/.codex/auth.json containing your access token and refresh metadata.

3. CodexBar automatically detects this file on launch via CodexOAuthCredentialsStore.load.

4. The app monitors the needsRefresh property (defined in CodexOAuthCredentials.swift, lines 31-35), which triggers when tokens are older than eight days.

Claude (Anthropic)

Anthropic's Claude integration supports both CLI-generated and environment-based credentials:

1. Run the Claude CLI authentication:

   claude login

2. This writes credentials to ~/.claude/.credentials.json.

3. Alternatively, set the environment variable before launching CodexBar:

   export CODEXBAR_CLAUDE_OAUTH_TOKEN=$(cat ~/.claude/.credentials.json | jq -r '.tokens.access_token')

When refresh is required, ClaudeOAuthDelegatedRefreshCoordinator contacts https://platform.claude.com/v1/oauth/token using the client ID defined in defaultOAuthClientID, while ClaudeOAuthRefreshFailureGate in ClaudeOAuthRefreshFailureGate.swift handles failure scenarios.

Gemini (Google)

Gemini follows the same OAuthCredentialsStore pattern as Codex but points to Google's token endpoints. Credentials are stored under ~/.config/gemini and managed by GeminiOAuthUsageFetcher.

Vertex AI (Google Cloud)

Vertex AI uses a different approach by shelling out to the Google Cloud SDK:

1. Ensure gcloud is installed and authenticated.
2. CodexBar executes gcloud auth print-access-token and caches the result in VertexAIOAuthCredentialsStore.
3. The token is refreshed automatically on a 60-minute TTL.

Automatic Token Refresh and Persistence

CodexBar implements proactive token refresh to prevent authentication failures. Each provider uses distinct refresh logic:

• Codex: Checks if last_refresh exceeds eight days, then invokes the CLI's token refresh endpoint.
• Claude: Uses ClaudeOAuthDelegatedRefreshCoordinator to exchange refresh tokens via Anthropic's OAuth endpoint.
• Vertex AI: Refreshes every 60 minutes via gcloud command execution.

Refreshed credentials are persisted with restrictive permissions (0600). The CodexOAuthCredentialsStore.save method (lines 55-86) writes JSON back to disk, while Claude's ClaudeOAuthCredentialsStore.writeMemoryCache eventually calls writePrivateFile (lines 189-200) to ensure secure storage.

Programmatic Access and Custom Integrations

Developers can interact with the credential stores directly for custom widgets or automation:

import CodexBarCore

do {
    // Load existing credentials
    let creds = try CodexOAuthCredentialsStore.load()
    // Force a refresh (use the public API)
    let refreshed = try CodexOAuthCredentialsStore.save(creds)
    print("New access token: \(creds.accessToken)")
} catch {
    print("OAuth error: \(error)")
}

For Claude environment variable access:

let credentials = try? ClaudeOAuthCredentialsStore.loadFromEnvironment(ProcessInfo.processInfo.environment)
print(credentials?.accessToken ?? "No token")

To verify CLI initialization:

# First login – creates ~/.claude/.credentials.json

claude login

# Verify that CodexBar can read it

codexbar status --provider claude

Summary

• CodexBar supports OAuth for Codex, Claude, Gemini, and Vertex AI through dedicated credential stores in Sources/CodexBarCore/Providers/.
• Credentials are discovered via environment variables first, then JSON files in ~/.codex, ~/.claude, or ~/.config/gemini.
• Automatic refresh occurs every eight days for Codex and via delegated coordinators for Claude, with tokens persisted using 0600 permissions.
• The CodexOAuthUsageFetcher and ClaudeOAuthUsageFetcher classes handle API authentication for usage metrics retrieval.
• Developers can programmatically access credentials using CodexOAuthCredentialsStore.load() and ClaudeOAuthCredentialsStore.loadFromEnvironment().

Frequently Asked Questions

Where does CodexBar store OAuth credentials?

CodexBar stores credentials in provider-specific JSON files: ~/.codex/auth.json for Codex, ~/.claude/.credentials.json for Claude, and ~/.config/gemini for Gemini. These files are created by the official CLIs (codex login, claude login) and are read by methods like CodexOAuthCredentialsStore.load and ClaudeOAuthCredentialsStore.load in the respective credential store implementations.

How do I force a token refresh in CodexBar?

For Codex, you can programmatically trigger a refresh by calling CodexOAuthCredentialsStore.save() after loading the credentials, or simply delete the existing token file and re-run codex login. For Claude, the ClaudeOAuthDelegatedRefreshCoordinator handles automatic refresh when the token expires, but you can also set the CODEXBAR_CLAUDE_OAUTH_TOKEN environment variable to override the cached value temporarily.

Can I use environment variables instead of credential files?

Yes. CodexBar checks environment variables before falling back to JSON files. For Claude, set CODEXBAR_CLAUDE_OAUTH_TOKEN to the access token string. The ClaudeOAuthCredentialsStore.loadFromEnvironment method specifically checks ProcessInfo.processInfo.environment for this variable, allowing temporary authentication without persistent file storage.

What happens when my OAuth token expires?

CodexBar implements automatic refresh mechanisms. For Codex, the needsRefresh property (checking if the token is older than eight days) triggers CLI-based refresh. For Claude, the ClaudeOAuthRefreshFailureGate and ClaudeOAuthDelegatedRefreshCoordinator manage the OAuth token exchange with Anthropic's platform endpoint. If refresh fails, the app marks the provider as unauthenticated until manual CLI re-authentication occurs.

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