# How CodexBar Imports Browser Cookies for Authentication

> Learn how CodexBar seamlessly imports authentication cookies from popular browsers like Chrome and Edge via SQLite. Securely stores them in the macOS keychain for effortless LLM provider requests.

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

---

**CodexBar automatically extracts authentication cookies from Chrome, Chromium, Edge, or Safari's SQLite databases and stores them in the macOS keychain to authenticate LLM provider requests without requiring manual cookie input.**

CodexBar is a macOS application that interfaces with various LLM providers including OpenAI and Claude. Instead of asking users to paste raw cookie strings, the app implements an automated **browser cookie import** system that reads session tokens directly from the user's web browsers when authentication errors occur.

## The Three-Component Architecture

CodexBar's cookie import system relies on three coordinated components that handle detection, storage, and orchestration.

### BrowserDetection

The **`BrowserDetection`** class scans the file system to locate installed browsers and determine the path to each browser's cookie SQLite database. It maintains a preference order of Chrome first, followed by Chromium-based browsers, Edge, and finally Safari. The detector caches results for the lifetime of the process using the `BrowserDetection(cacheTTL:)` initializer.

In [`Sources/CodexBar/BrowserDetection.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/BrowserDetection.swift), the implementation reads standard macOS directories such as `~/Library/Application Support/Google/Chrome/Default/Cookies` to build an ordered list of available browsers.

### CookieHeaderCache and KeychainCookieHeaderStore

The **`KeychainCookieHeaderStore`** class persists the final **`Cookie:`** header string in the macOS keychain so credentials survive application restarts, while **`CookieHeaderCache`** provides an in-memory layer to avoid repeated keychain hits.

According to [`Sources/CodexBar/CookieHeaderStore.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/CookieHeaderStore.swift), the store offers `loadCookieHeader()` to read a generic-password entry identified by the provider name, and `storeCookieHeader(_:)` to write the header after normalization by `CookieHeaderNormalizer`.

### UsageStore Extensions

Provider-specific extensions such as **`UsageStore+OpenAIWeb`** orchestrate the import workflow. When a fetcher receives a *login-required* or *account-mismatch* error, the extension triggers the browser detection and cookie extraction logic, then retries the request once with the new credentials.

The source file `Sources/CodexBar/UsageStore+OpenAIWeb.swift` contains the trigger logic: *"On login-required … import cookies from the configured browser order and retry once."*

## Step-by-Step Import Process

When CodexBar needs to authenticate a web endpoint request, it executes the following sequence:

1. **Detect browsers** – `BrowserDetection` scans the file system and builds an ordered array `[Browser]` of viable cookie sources.

2. **Select the first viable profile** – The system iterates through the list sequentially, attempting to open each browser's cookie database until it finds an accessible SQLite file.

3. **Open the SQLite cookie store** – A read-only connection is established to the `Cookies` database file. macOS encrypts Safari's cookies, but Chrome and Chromium use a format readable by the system SQLite driver.

4. **Query the cookie table** – The app executes SQL similar to the following query found in [`Sources/CodexBarCore/BrowserCookieImporter.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/BrowserCookieImporter.swift):

   ```sql
   SELECT name, value FROM cookies
   WHERE host_key LIKE '%openai.com%' AND (name = 'session' OR name = 'auth')
   ORDER BY expires_utc DESC LIMIT 1;
   ```

5. **Build the header** – The retrieved `name=value` pair is formatted into a header string and passed through `CookieHeaderNormalizer` for validation:

   ```swift
   let header = "Cookie: \(name)=\(value)"
   ```

6. **Persist credentials** – The normalized header is saved via `KeychainCookieHeaderStore.storeCookieHeader(header)` and cached in `CookieHeaderCache`.

7. **Retry the request** – The original network fetcher (such as `OpenAIChatFetcher` or `ClaudeUsageFetcher`) re-executes the HTTP request with the freshly imported `Cookie:` header.

If no browser contains a matching cookie, the import silently fails and the UI displays the message *"Sign in to chatgpt.com, then refresh OpenAI cookies"* as referenced in [`Tests/CodexBarTests/StatusMenuNativeSectionSpacingTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/StatusMenuNativeSectionSpacingTests.swift).

## Implementation Code Examples

### Detecting Available Browsers

The following pattern appears throughout the test suite, such as in [`Tests/CodexBarTests/WindsurfWebFetcherTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/WindsurfWebFetcherTests.swift):

```swift
let detection = BrowserDetection(cacheTTL: 0)          // cache disabled for tests
let browsers = detection.availableBrowsers()          // → [.chrome, .chromium, .edge, .safari]

```

### Importing and Storing OpenAI Cookies

This simplified implementation demonstrates the core extraction logic:

```swift
func importOpenAICookie() throws -> String? {
    for browser in detection.availableBrowsers() {
        guard let db = try? browser.openCookieDatabase() else { continue }
        if let (name, value) = try db.fetchOpenAICookie() {
            let header = "Cookie: \(name)=\(value)"
            try KeychainCookieHeaderStore(account: "openai", promptKind: .openAI).storeCookieHeader(header)
            return header
        }
    }
    return nil      // no matching cookie found
}

```

### Retrieving Stored Headers for Requests

Fetchers load the stored header before making authenticated requests:

```swift
let store = KeychainCookieHeaderStore(account: "openai", promptKind: .openAI)
let header = try store.loadCookieHeader()

var request = URLRequest(url: endpoint)
if let h = header { 
    request.addValue(h, forHTTPHeaderField: "Cookie") 
}

```

## Key Source Files

The cookie import functionality spans the following files in the `steipete/CodexBar` repository:

- **[`Sources/CodexBar/BrowserDetection.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/BrowserDetection.swift)** – Detects installed browsers and resolves cookie database paths.
- **[`Sources/CodexBar/CookieHeaderStore.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/CookieHeaderStore.swift)** – Keychain wrapper for loading and saving cookie headers.
- **[`Sources/CodexBar/CookieHeaderCache.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBar/CookieHeaderCache.swift)** – In-memory cache to minimize keychain access.
- **`Sources/CodexBar/UsageStore+OpenAIWeb.swift`** – Coordinates import-on-error flows for OpenAI providers.
- **[`Sources/CodexBarCore/BrowserCookieImporter.swift`](https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/BrowserCookieImporter.swift)** – Opens SQLite databases and executes extraction queries.
- **[`Tests/CodexBarTests/WindsurfWebFetcherTests.swift`](https://github.com/steipete/CodexBar/blob/main/Tests/CodexBarTests/WindsurfWebFetcherTests.swift)** – Unit tests verifying automatic import and retry behavior.

## Summary

- **BrowserDetection** locates Chrome, Chromium, Edge, and Safari profiles by scanning macOS Library directories.
- **KeychainCookieHeaderStore** persists the `Cookie:` header in the macOS keychain with an in-memory cache for performance.
- **UsageStore extensions** trigger automatic imports when network requests return authentication errors, retrying once with the new credentials.
- The system queries browser SQLite databases using provider-specific SQL to extract session tokens like `session` or `auth`.
- All cookie handling operates automatically without manual user input, falling back to UI prompts only when no valid cookies are found.

## Frequently Asked Questions

### Which browsers does CodexBar support for cookie import?

CodexBar supports Chrome, Chromium-based browsers, Microsoft Edge, and Safari. The `BrowserDetection` class prioritizes Chrome first, then falls back through Chromium variants, Edge, and finally Safari if earlier options fail or lack valid cookies.

### How does CodexBar handle Safari's encrypted cookie database?

While Safari encrypts its cookie storage on macOS, CodexBar primarily targets Chrome and Chromium browsers which use unencrypted SQLite formats readable by the system SQLite driver. The `BrowserDetection` class includes Safari in its fallback chain, but the implementation focuses on the accessible Chrome/Chromium format for reliable automation.

### Where does CodexBar store imported cookies between app restarts?

Imported cookie headers are stored in the macOS keychain using `KeychainCookieHeaderStore`, identified by the provider name (e.g., "openai"). An in-memory `CookieHeaderCache` prevents redundant keychain queries during active sessions, while the keychain ensures persistence across application restarts.

### Can users manually trigger a cookie refresh?

The automatic import triggers when fetchers receive *login-required* or *account-mismatch* errors. If automatic import fails, the UI displays *"Sign in to chatgpt.com, then refresh OpenAI cookies"* as implemented in the status menu tests, prompting users to authenticate via browser before the next automatic import attempt.