CodexBar Hidden Quirks Wiki

Pages

1. Hidden Quirks MapThe 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.
2. Keychain Accessibility Migration — Silencing Rebuild PromptsOn 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.
3. BrowserCookieAccessGate — 6-Hour Prompt CooldownReading 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.
4. Synthetic Provider — Universal Quota Parser That Handles Any API ShapeThe 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.
5. Claude Peak-Hour Awareness — ET 8am–2pm WeekdaysClaudePeakHours 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.
6. DisplayLink Dual-Path & Watchdog Orphan DetectionTwo 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.