CodexBar Competitive Parity — Spec Interview Architecture

Implementation architecture for 6 active phases closing Pitwall's feature gaps vs. CodexBar (12.9k stars, 40+ providers). Each phase preserves Pitwall's differentiation: confidence labels, decision-first UI, privacy-first architecture, and cross-device sync via CalcLLM. Spec interview completed 2026-05-19.

Active Phases 6
Total Effort ~22.5d
Decisions Made 18
Blocked 1 (P16)
Deferred 1 (P17)

Execution Order

Priority reordered from severity to urgency: P18 Cookie Auth fixes broken ChatGPT login (active user pain), while P16 Distribution is blocked on Apple Developer enrollment.

1
P18 Cookie Auth
5-7d
NEXT
2
P19 CLI
4-5d
UNBLOCKED
3
P22 Widgets
4-5d
UNBLOCKED
4
P21 Badges
2d
UNBLOCKED
5
P20 Guide
2d
UNBLOCKED
6
P16 Distro
3-4d
BLOCKED
7
P17 Providers
6-10d
DEFERRED

P18: Cookie Auth Architecture

Opt-in browser cookie extraction for Chrome and Safari. Fixes broken ChatGPT login. Provider-generic CookieProviderConfig maps provider to domain, cookie name, and decryption strategy. Feeds into existing AuthHealthWarning model from auth-resilience spec.

P18 Cookie Extraction Flow
Chrome Path
Chrome Cookies SQLite
→
AES-128-CBC Decrypt
→
Session Token
Key from "Chrome Safe Storage" Keychain item
Safari Path
Cookies.binarycookies
→
Binary Format Parse
→
Session Token
4-byte magic, page headers, cookie records
Session Token
→
CookieProviderConfig
→
AuthHealthWarning
→
Existing Auth Model
Cookie Provider Config
struct CookieProviderConfig {
  let provider: ProviderType
  let domains: [String]
  let cookieName: String
  let decryptionStrategy: CookieDecryptionStrategy
}
Provider-generic: same reader code, different config. Scales to new providers by adding config entries, not new reader implementations.
Consent UX
Settings → Auth → "Auto-detect browser cookies" toggle (off by default). First enable shows consent dialog listing exact file paths. Requires Full Disk Access TCC permission. Manual entry remains the default onboarding path.
Opt-in consent vs CodexBar's silent reads
Provider Scope
ChatGPT/OpenAI .openai.com, .chatgpt.com
Claude .anthropic.com, .claude.ai
Codex, Gemini N/A (device flow, OAuth)
Auth Integration
Cookie expiry → AuthHealthWarning.expiringSoon
Cookie invalid → standard re-auth flow
Source tracked: .cookieSourced vs .manuallyEntered

Supersedes auth-resilience.md Non-Goal: "Automated browser cookie extraction"

P19: CLI Architecture

Separate monorepo product at apps/pitwall-cli/ with own Package.swift. Imports PitwallCore as local dependency. Shares Keychain credentials with the menu bar app.

P19 Command Surface
pitwall status All providers table
pitwall status --provider Single provider detail
pitwall status --json Machine-readable output
pitwall providers Config + health status
pitwall suggest Push/Conserve/Switch
Opinionated recommendations (CodexBar is data-only)
Monorepo Structure
apps/pitwall-cli/
  Package.swift # imports PitwallCore
  Sources/PitwallCLI/
    PitwallCLI.swift
    StatusCommand.swift
    ProvidersCommand.swift
    SuggestCommand.swift
    Formatters/
  Tests/PitwallCLITests/
Depends on: swift-argument-parser, PitwallCore (local)

P22: Widget Architecture

WidgetKit integration with dual-write data sharing. Small widget shows single-provider decision word. Medium widget shows all-provider overview with routing suggestion.

P22 Data Sharing: Dual Write
App Storage (existing)
~/Library/Application Support/Pitwall/
+
App Group (new)
group.com.pitwall.shared
Main app writes WidgetSnapshot to both locations on each fetch. Widget extension reads from App Group container. No migration of existing storage.
Widget Designs
Small
Claude
PUSH
62%
Resets 2h 14m
Medium — All Providers
● Claude 62% Push 2d 4h
● ChatGPT 85% Conserve 1d 12h
● Gemini 30% Push 5d 2h
→ Switch to Gemini if ChatGPT runs out

P21: Status Badge Architecture

Unified badge composes 4 signals into one per-provider health indicator. Worst-case signal determines badge color. Degradation ties into confidence labels.

P21 Four-Signal Badge Composition
External Status
Anthropic, OpenAI, Google status pages
Poll every 5 min
Data Freshness
Last successful snapshot age
Existing timestamps
Auth Health
Session/cookie validity
From AuthHealthWarning
Confidence Roll-up
delta / estimated / stale
Existing labels
Badge color = worst-case across all 4 signals: green (all healthy) → yellow (any warning) → red (any critical)
StatusChecker Service
actor StatusChecker {
  // Atlassian Statuspage JSON
  let endpoints: [ProviderType: URL]
  let pollInterval: TimeInterval = 300
  
  enum ExternalStatus {
    case operational
    case degraded(String)
    case majorOutage(String)
    case unknown
  }
}
Confidence Degradation
When StatusChecker reports degradation:

Major outage: degrade confidence .delta → .estimated
All states: append "Usage data may be inaccurate — [Provider] is reporting degraded service"

Debounce: 2 consecutive degraded polls before surfacing (10 min minimum).
Status tied to confidence (CodexBar shows badge only)

Key Interview Decisions

18 decisions made during spec interview. These represent deviations from the original roadmap or resolutions of open questions.

Phase Decision Alternatives Rejected Rationale
P18 Direct DB read (Chrome SQLite + Safari binary) Browser extension, AppleScript Proven approach (CodexBar uses it), no extension install needed
P18 Provider-generic CookieProviderConfig Per-provider readers Same code, different config — scales without new reader implementations
P18 Integrates with existing AuthHealthWarning Separate auth model Cookie expiry feeds natural .expiringSoon warnings
P19 Separate apps/pitwall-cli/ package Target in existing Package.swift, standalone repo Follows monorepo convention, own build cycle
P19 Shared Keychain (no separate config) Config file, read app data dir Zero-config: works if menu bar app is configured
P22 Dual-write (current storage + App Group) App Group only, Core Data shared store No migration risk, existing app storage unchanged
P21 Unified 4-signal badge Simple status dot (CodexBar), separate indicators Composes signals CodexBar treats separately into one actionable view
All P18 first, P16 deferred until enrollment P16 first (critical severity) P18 fixes active user pain; P16 blocked on external dependency
All P17 deferred indefinitely Active (6-10d effort) 3 providers sufficient; P20 community infra enables organic growth

Key Files by Phase

New files in green, modified files in yellow.

P18 Cookie Auth
+ CookieAuthSource.swift
+ ChromeCookieReader.swift
+ SafariCookieReader.swift
+ CookieProviderConfig.swift
~ PitwallApp/ (consent UI)
~ auth-resilience.md
P19 CLI
+ apps/pitwall-cli/Package.swift
+ PitwallCLI.swift
+ StatusCommand.swift
+ ProvidersCommand.swift
+ SuggestCommand.swift
+ Formatters/
P22 Widgets
+ Sources/PitwallWidget/
+ WidgetSnapshot.swift
~ App Group entitlements
~ Data fetch (dual-write)
P21 Status Badges
+ StatusChecker.swift
+ ProviderBadge.swift
~ Popover provider cards
P20 Provider Guide
+ CONTRIBUTING.md
+ TemplateAdapter.swift
+ .github/ISSUE_TEMPLATE/
+ .github/PULL_REQUEST_TEMPLATE/
~ provider-adapter-guide.md
P16 Distribution
~ scripts/release.sh
+ homebrew-pitwall/ (separate repo)
+ appcast.xml
~ Makefile
~ App target (Sparkle)

Cross-Phase Integration

How the 6 phases connect to existing Pitwall architecture and to each other.

PitwallCore (shared foundation)
CookieAuthSource
P18 — Cookie extraction
StatusChecker
P21 — External status polling
WidgetSnapshot
P22 — Shared data model
Existing Models
ProviderState, AuthHealthWarning, ConfidenceLabel
↓ consumed by ↓
Consumers
PitwallApp
Menu bar + popover (existing)
PitwallCLI
P19 — Terminal interface
PitwallWidget
P22 — WidgetKit extension
CalcLLM Sync
Cross-device (existing)

Differentiation Preserved

Every phase closes a CodexBar gap while extending Pitwall's unique angles.

Privacy-First Cookie Auth
P18: Explicit consent dialog, exact file paths shown. CodexBar reads silently.
Decision-First CLI
P19: pitwall suggest gives Push/Conserve/Switch. CodexBar CLI is data-only.
Decision-First Widgets
P22: Single pacing word + color in small widget. CodexBar widgets show raw numbers.
Status + Confidence
P21: Degradation degrades confidence labels. CodexBar shows badge only, no data trust signal.
Quality-First Community
P20: Confidence label decision tree for contributors. CodexBar: "just show something."
Cross-Device Sync
Existing CalcLLM differentiator. No CodexBar equivalent. All phases preserve this angle.

References

specs/codexbar-competitive-parity.md — Full implementation specification
specs/codexbar-competitive-parity-interview.md — Interview decision log
specs/auth-resilience.md — Auth health model (P18 integrates with this)
codexbar-refactor-preview.html — Feature gap analysis + architecture reference
research/pitwall-calcllm/competitive-analysis.md — Competitive landscape
tasks/roadmap.md — Roadmap phases P16-P22 (lines 725-928)