# CodexBar Hidden Quirks Wiki

> CodexBar is a macOS menu-bar app that aggregates AI-provider quota and cost data from 40+ providers. This wiki surfaces non-obvious implementation constraints, safety rails, edge-case adapters, and behavioral decisions that a casual reader of the README would miss entirely.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492)
- [GitHub repository](https://github.com/steipete/CodexBar)

## Repository

- Repository: steipete/CodexBar

- Generated: 2026-05-18T21:31:14.234Z
- Updated: 2026-05-21T21:34:24.914Z
- Runtime: Claude Code
- Format: Hidden Quirks
- Pages: 6

## Pages

- [Hidden Quirks Map](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/pages/01-hidden-quirks-map.md): The six non-obvious implementation quirks every maintainer should know: keychain accessibility migration, browser-cookie prompt suppression, a universal quota parser, Claude peak-hour awareness, a dual-path display link, and an orphan-detecting watchdog process. Each exists because a naive implementation either triggers repeated macOS permission dialogs, silently fails on diverse API shapes, or leaks child processes at app quit.
- [Keychain Accessibility Migration — Silencing Rebuild Prompts](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/pages/02-keychain-accessibility-migration-silencing-rebuild-prompts.md): On every development rebuild macOS pops a keychain Allow/Deny dialog for each stored credential, breaking the edit-run loop. CodexBar silently migrates all legacy keychain items from their default accessibility level to kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly on first launch. The migration is one-shot (guarded by UserDefaults key "KeychainMigrationV1Completed"), uses a delete-then-add dance because SecItemUpdate cannot change kSecAttrAccessible, and is skipped entirely when KeychainAccessGate.isDisabled is set (CI / sandboxed environments). The list of migrated accounts is hard-coded in KeychainMigration.itemsToMigrate and includes every cookie and token the app manages.
- [BrowserCookieAccessGate — 6-Hour Prompt Cooldown](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/pages/03-browsercookieaccessgate-6-hour-prompt-cooldown.md): Reading Chromium browser cookies for providers like Claude-web requires decrypting the "Chrome Safe Storage" keychain entry, which itself triggers a macOS permission prompt. BrowserCookieAccessGate wraps every cookie-fetch call and suppresses attempts for 6 hours after a denial. The gate uses KeychainAccessPreflight.checkGenericPassword to probe each known safe-storage label without triggering the full dialog; if interaction is required it records a "denied until" timestamp in UserDefaults and returns false immediately. The cooldown is intentionally long (6h) to prevent repeated nagging if the user clicks Deny. The gate is a no-op stub on non-macOS platforms so the same CodexBarCore code compiles for Linux tests. Evidence: BrowserCookieAccessGate.swift, BrowserCookieAccessGate.cooldownInterval = 60*60*6.
- [Synthetic Provider — Universal Quota Parser That Handles Any API Shape](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/pages/04-synthetic-provider-universal-quota-parser-that-handles-any-api-shape.md): The Synthetic provider is designed for any OpenAI-compatible proxy; its quota API can return wildly different JSON shapes. SyntheticUsageParser does not rely on a fixed schema: it tries 10+ key aliases for each field (percentUsed/usagePercent/used_percent/percent_used/percent…), auto-detects whether a percent value is already 0-100 or 0-1, derives missing fields by algebra (used = limit − remaining), and parses duration strings like "5hr", "30min", "2 days" by sorting suffix strings longest-first to prevent prefix collisions. When the known Synthetic API shape is detected (rollingFiveHourLimit / weeklyTokenLimit / search.hourly keys) it uses slot-positioned mapping so a missing middle lane stays nil instead of shifting labels. Timestamp heuristic: numbers > 1e12 are treated as milliseconds, numbers > 1e9 as seconds, strings are tried with and without fractional seconds. Evidence: SyntheticUsageParser.swift, SyntheticUsageParser.windowSuffixMultipliers sorted by suffix length.
- [Claude Peak-Hour Awareness — ET 8am–2pm Weekdays](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/pages/05-claude-peak-hour-awareness-et-8am-2pm-weekdays.md): ClaudePeakHours hard-codes Anthropic's known rate-limit peak window: weekdays 08:00–14:00 America/New_York. The status() method returns a labeled Status struct with a countdown ("Peak · ends in 2h 15m" or "Off-peak · peak in 18h 30m") computed against the Eastern timezone calendar. Weekends are always off-peak. The next-peak search correctly skips Saturday (skip=2 days) and Sunday (skip=1 day) so Monday is always the next target. ClaudeSourcePlanner uses this signal alongside credential availability and ProviderRuntime to decide which data source to attempt, making the fetch strategy time-aware without any external configuration. Evidence: ClaudePeakHours.swift peakStartHour=8, peakEndHour=14, peakTimeZone="America/New_York"; ClaudeSourcePlannerTests.swift.
- [DisplayLink Dual-Path & Watchdog Orphan Detection](https://grok-wiki.com/public/wiki/steipete-codexbar-3494bea25492/pages/06-displaylink-dual-path-watchdog-orphan-detection.md): Two unrelated but equally subtle runtime quirks shape how CodexBar animates its icon and manages child processes. DisplayLinkDriver uses NSScreen.displayLink (macOS 15+) when available and falls back to CVDisplayLink (macOS 14), bridging the two via a scheduleTick() dispatch to the main actor since CVDisplayLink fires on a background thread. CADisplayLink ticks are rate-limited by a manual timestamp comparison so the 12 fps target is honored regardless of the display's native refresh rate. Separately, CodexBarClaudeWatchdog is a standalone POSIX executable that spawns claude as a child process group leader and polls waitpid every 200ms. Its critical invariant: if getppid() returns 1, the macOS app has been killed without sending SIGTERM, so the watchdog kills the child process tree (SIGTERM → 500ms grace → SIGKILL) and exits. The watchdog also manually decodes waitpid's raw status integer because Swift cannot import function-like C macros (WIFEXITED/WEXITSTATUS). Evidence: DisplayLink.swift startCVDisplayLink(), CodexBarClaudeWatchdog/main.swift getppid()==1 branch, exitCode(fromWaitStatus:) bit-manipulation.

## Source Files

- `Sources/CodexBar/DisplayLink.swift`
- `Sources/CodexBar/KeychainMigration.swift`
- `Sources/CodexBarClaudeWatchdog/main.swift`
- `Sources/CodexBarCore/BrowserCookieAccessGate.swift`
- `Sources/CodexBarCore/BrowserCookieImportOrder.swift`
- `Sources/CodexBarCore/Host/Process/SubprocessRunner.swift`
- `Sources/CodexBarCore/Host/PTY/TTYCommandRunner.swift`
- `Sources/CodexBarCore/KeychainAccessGate.swift`
- `Sources/CodexBarCore/KeychainAccessPreflight.swift`
- `Sources/CodexBarCore/KeychainNoUIQuery.swift`
- `Sources/CodexBarCore/Providers/Claude/ClaudeCredentialRouting.swift`
- `Sources/CodexBarCore/Providers/Claude/ClaudePeakHours.swift`
- `Sources/CodexBarCore/Providers/Claude/ClaudeSourcePlanner.swift`
- `Sources/CodexBarCore/Providers/Synthetic/SyntheticProviderDescriptor.swift`
- `Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageFetcher.swift`
- `Sources/CodexBarCore/Providers/Synthetic/SyntheticUsageParser.swift`
- `Tests/CodexBarTests/ClaudeOAuthCredentialsStoreTests.swift`
- `Tests/CodexBarTests/ClaudeSourcePlannerTests.swift`
- `Tests/CodexBarTests/OpenAIWebAccountSwitchTests.swift`
- `Tests/CodexBarTests/TTYCommandRunnerTests.swift`
- `Tests/CodexBarTests/VeniceUsageFetcherTests.swift`