Config File Reference

Overview

CodexBar stores all provider configurations in a single JSON file at ~/.codexbar/config.json. This file contains:

Provider enable/disable toggles
Authentication credentials (API keys, cookies)
Source mode preferences (CLI, web, OAuth, API)
Provider-specific settings (region, workspace ID)

Security: The config file contains sensitive credentials. CodexBar sets file permissions to 0600 (owner read/write only) automatically.

File Location

Path: ~/.codexbar/config.json
Permissions: 0600 (enforced on macOS and Linux)
Auto-created: If missing, CodexBar creates it with default settings

Schema

Root Structure

{
  "version": 1,
  "providers": [
    // Array of ProviderConfig objects
  ]
}

Field	Type	Required	Description
`version`	`number`	Yes	Config schema version (currently `1`)
`providers`	`array`	Yes	List of provider configurations

Provider Configuration

{
  "id": "codex",
  "enabled": true,
  "source": "auto",
  "cookieSource": "auto",
  "cookieHeader": null,
  "apiKey": null,
  "region": null,
  "workspaceID": null,
  "tokenAccounts": null
}

Field	Type	Required	Description
`id`	`string`	Yes	Provider identifier (see Provider IDs)
`enabled`	`boolean`	No	Enable/disable provider (defaults to provider default)
`source`	`string`	No	Preferred source mode: `auto`, `web`, `cli`, `oauth`, `api`
`cookieSource`	`string`	No	Cookie policy: `auto` (browser import), `manual`, `off`
`cookieHeader`	`string`	No	Raw cookie header for manual cookie mode
`apiKey`	`string`	No	API token for providers with API support
`region`	`string`	No	Provider-specific region (e.g., `zai`, `minimax`)
`workspaceID`	`string`	No	Workspace identifier (e.g., `opencode`)
`tokenAccounts`	`object`	No	Multi-account token data (see Token Accounts)

Provider IDs

Valid provider identifiers:

codex, claude, cursor, opencode, factory, gemini, antigravity, 
copilot, zai, minimax, kimi, kilo, kiro, vertexai, augment, 
jetbrains, kimik2, amp, ollama, synthetic, warp, openrouter

Provider order in the providers array controls display order in the app and CLI. Reorder the array to change menu bar icon sequence.

Source Modes

Mode	Description	Availability
`auto`	Uses provider-specific fallback order	All providers
`web`	Force browser cookie authentication	Web-capable providers
`cli`	Force CLI tool invocation	CLI-capable providers
`oauth`	Force OAuth flow	Claude, Gemini, Copilot
`api`	Force API key authentication	Providers with API support

Each provider has a default fallback order when auto is selected. See individual provider docs for details.

Source	Description	Use Case
`auto`	Import cookies from browsers automatically	Default for most users
`manual`	Use `cookieHeader` field	Browser import fails or unsupported browser
`off`	Disable cookie-based authentication	Use CLI or OAuth instead

When using cookieSource: "manual", provide the raw cookie header:

{
  "id": "claude",
  "cookieSource": "manual",
  "cookieHeader": "sessionKey=abc123...; __cf_bm=xyz789...; intercom-session=..."
}

Cookie headers contain sensitive session tokens. Never commit config.json to version control or share it publicly.

Token Accounts

Some providers support multiple accounts with separate tokens (e.g., OpenRouter, Synthetic).

Schema

{
  "version": 1,
  "activeIndex": 0,
  "accounts": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "label": "[email protected]",
      "token": "sk-or-v1-...",
      "addedAt": 1735123456,
      "lastUsed": 1735220000
    }
  ]
}

Field	Type	Required	Description
`version`	`number`	Yes	Token accounts schema version (currently `1`)
`activeIndex`	`number`	Yes	Index of the active account in the `accounts` array
`accounts`	`array`	Yes	List of account objects

Account Object

Field	Type	Required	Description
`id`	`string`	Yes	Unique UUID for the account
`label`	`string`	Yes	Display name (typically email)
`token`	`string`	Yes	API token or bearer token
`addedAt`	`number`	Yes	Unix timestamp when account was added
`lastUsed`	`number`	No	Unix timestamp of last use

Examples

Minimal Configuration

Default providers with no customization:

{
  "version": 1,
  "providers": [
    { "id": "codex" },
    { "id": "claude" },
    { "id": "cursor" },
    { "id": "opencode" },
    { "id": "gemini" }
  ]
}

{
  "version": 1,
  "providers": [
    {
      "id": "codex",
      "enabled": true,
      "source": "auto",
      "cookieSource": "manual",
      "cookieHeader": "__Secure-next-auth.session-token=eyJhbGc...; __cf_bm=abc..."
    }
  ]
}

Claude with OAuth and CLI Fallback

{
  "version": 1,
  "providers": [
    {
      "id": "claude",
      "enabled": true,
      "source": "oauth"
    }
  ]
}

OAuth credentials are stored in Keychain, not in config.json. The source field only controls the preferred authentication method.

z.ai with API Token and Region

{
  "version": 1,
  "providers": [
    {
      "id": "zai",
      "enabled": true,
      "apiKey": "zai_1234567890abcdef",
      "region": "us-west"
    }
  ]
}

OpenCode with Workspace ID

{
  "version": 1,
  "providers": [
    {
      "id": "opencode",
      "enabled": true,
      "workspaceID": "my-workspace-id"
    }
  ]
}

Multiple Providers with Custom Order

{
  "version": 1,
  "providers": [
    {
      "id": "claude",
      "enabled": true,
      "source": "oauth"
    },
    {
      "id": "codex",
      "enabled": true,
      "source": "cli",
      "cookieSource": "off"
    },
    {
      "id": "cursor",
      "enabled": true,
      "cookieSource": "auto"
    },
    {
      "id": "gemini",
      "enabled": false
    }
  ]
}

OpenRouter with Multi-Account Tokens

{
  "version": 1,
  "providers": [
    {
      "id": "openrouter",
      "enabled": true,
      "tokenAccounts": {
        "version": 1,
        "activeIndex": 0,
        "accounts": [
          {
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "label": "[email protected]",
            "token": "sk-or-v1-abc123...",
            "addedAt": 1735123456,
            "lastUsed": 1735220000
          },
          {
            "id": "f7e8d9c0-b1a2-3456-7890-abcdef123456",
            "label": "[email protected]",
            "token": "sk-or-v1-xyz789...",
            "addedAt": 1735130000,
            "lastUsed": null
          }
        ]
      }
    }
  ]
}

Editing the Config File

Via Settings UI

Most settings can be changed through Settings → Providers:

Enable/disable toggles
Source mode selection
Cookie source selection
API key entry
Region and workspace ID fields

Changes are automatically saved to config.json.

Manual Editing

Quit CodexBar
Open ~/.codexbar/config.json in a text editor
Make changes (see examples above)
Validate JSON syntax
Relaunch CodexBar

Manual edits bypass validation. Invalid JSON or unsupported values may cause CodexBar to fail to launch.

Validating the Config

Use the CLI to validate your config:

codexbar config validate

For JSON output:

codexbar config validate --format json

Example output:

{
  "valid": true,
  "errors": [],
  "warnings": [
    "Provider 'gemini' is disabled but has API key configured"
  ]
}

Config Normalization

CodexBar normalizes the config on load:

Adds missing providers: Any provider not in the providers array is appended with defaults
Removes duplicates: If a provider appears multiple times, only the first occurrence is kept
Applies defaults: Omitted fields use provider-specific defaults
Cleans sensitive fields: Trims whitespace and removes surrounding quotes from apiKey and cookieHeader

Migration from Legacy Storage

CodexBar previously stored credentials in Keychain and UserDefaults. Starting with v2.0, all credentials are migrated to config.json. What gets migrated:

Keychain-stored API tokens (z.ai, Copilot, OpenRouter, Synthetic, etc.)
Keychain-stored cookie headers (Codex, Claude, Cursor, Factory, etc.)
UserDefaults provider toggles and source modes

What stays in Keychain:

OAuth tokens (Claude OAuth, Gemini OAuth)
Browser safe storage keys (for automatic cookie decryption)

Migration happens automatically on first launch. Legacy storage is not deleted to allow rollback.

Backup and Restore

Backing Up

cp ~/.codexbar/config.json ~/.codexbar/config.json.backup

Restoring

cp ~/.codexbar/config.json.backup ~/.codexbar/config.json

Relaunch CodexBar after restoring.

Resetting to Defaults

rm ~/.codexbar/config.json

CodexBar recreates the file with default settings on next launch.

This deletes all provider configurations, API keys, and custom settings. Use “Export Settings” from the UI if you want to preserve a copy.

Troubleshooting

Config file is missing or empty

Symptom: CodexBar shows no providers or “Failed to load config”Solution:

Check that ~/.codexbar/ directory exists
Check file permissions: ls -la ~/.codexbar/config.json
Recreate with: codexbar config validate (generates default config if missing)

Changes don't persist after editing

Symptom: Manual edits to config.json are lost after relaunching CodexBarSolution:

Ensure CodexBar is fully quit (check Activity Monitor)
Verify JSON syntax with: python3 -m json.tool ~/.codexbar/config.json
Check that file isn’t read-only: ls -la ~/.codexbar/config.json
If permissions are wrong: chmod 600 ~/.codexbar/config.json

API key or cookie not working

Provider order doesn't match config

Symptom: Menu bar icons appear in wrong order despite correct providers array orderSolution:

Verify the order in config.json
Restart CodexBar (Quit → Relaunch, not just closing the menu)
Check Settings → Providers for the order
If still wrong, delete config.json and reconfigure

CLI Configuration Commands

View Current Config

codexbar config show

Validate Config

codexbar config validate

Reset Config

codexbar config reset

See the CLI Reference for more commands.

Get Started

Core Features

Providers

CLI

Configuration

Development

Config File Reference

Overview

File Location

Schema

Root Structure

Provider Configuration

Provider IDs

Source Modes

Token Accounts

Schema

Account Object

Examples

Minimal Configuration

Claude with OAuth and CLI Fallback

z.ai with API Token and Region

OpenCode with Workspace ID

Multiple Providers with Custom Order

OpenRouter with Multi-Account Tokens

Editing the Config File

Via Settings UI

Manual Editing

Validating the Config

Config Normalization

Migration from Legacy Storage

Backup and Restore

Backing Up

Restoring

Resetting to Defaults

Troubleshooting

CLI Configuration Commands

View Current Config

Validate Config

Reset Config

Build docs developers (and LLMs) love

Get Started

Core Features

Providers

CLI

Configuration

Development

​Overview

​File Location

​Schema

​Root Structure

​Provider Configuration

​Provider IDs

​Source Modes

​Cookie Sources

​Manual Cookie Header Format

​Token Accounts

​Schema

​Account Object

​Examples

​Minimal Configuration

​Codex with Manual Cookie

​Claude with OAuth and CLI Fallback

​z.ai with API Token and Region

​OpenCode with Workspace ID

​Multiple Providers with Custom Order

​OpenRouter with Multi-Account Tokens

​Editing the Config File

​Via Settings UI

​Manual Editing

​Validating the Config

​Config Normalization

​Migration from Legacy Storage

​Backup and Restore

​Backing Up

​Restoring

​Resetting to Defaults

​Troubleshooting

​CLI Configuration Commands

​View Current Config

​Validate Config

​Reset Config

Build docs developers (and LLMs) love

Overview

File Location

Schema

Root Structure

Provider Configuration

Provider IDs

Source Modes

Cookie Sources

Manual Cookie Header Format

Token Accounts

Schema

Account Object

Examples

Minimal Configuration

Codex with Manual Cookie

Claude with OAuth and CLI Fallback

z.ai with API Token and Region

OpenCode with Workspace ID

Multiple Providers with Custom Order

OpenRouter with Multi-Account Tokens

Editing the Config File

Via Settings UI

Manual Editing

Validating the Config

Config Normalization

Migration from Legacy Storage

Backup and Restore

Backing Up

Restoring

Resetting to Defaults

Troubleshooting

CLI Configuration Commands

View Current Config

Validate Config

Reset Config