CodexBar Competitive Parity — Refactor Roadmap

CodexBar is the leading open-source AI coding subscription tracker (12.9k GitHub stars, 40+ provider integrations, ~1k forks). This roadmap captures the 7 phases (P16–P22) needed to close Pitwall's feature gaps while preserving our differentiation angles: confidence labels, pacing guidance, privacy-first architecture, and decision-first UI.

CodexBar 12.9k stars
CodexBar 40+ providers
CodexBar ~1k forks
Pitwall 3 providers
Pitwall ~40% coverage

Feature Gap Comparison

Seven areas where CodexBar's feature set exceeds Pitwall's current implementation. Severity reflects user-facing impact: critical gaps block adoption, significant gaps reduce stickiness, minor gaps are nice-to-haves.

Feature CodexBar Pitwall Today Severity
Cookie Auth Browser cookie reads Manual entry (ChatGPT broken) Critical
Distribution GitHub Releases + Homebrew make install only Critical
CLI Tool codexbar CLI None (separate monorepo product) Significant
Widgets WidgetKit widgets None Significant
Status Badges Provider status indicators None Minor
Community Infra ~1k forks + provider guide None Minor
Provider Coverage 40+ providers ~40% (Claude, Codex, Gemini) Deferred

Implementation Timeline

Active effort: ~22.5 days (range: 19–27 days across 6 phases)  + 8d deferred (P17 providers)
P18 6d
P16 3.5d
P19 4.5d
P22 4.5d
P21 2d
P20 2d
P17 8d
Cookie Auth Distribution CLI Widgets Status Guide Providers (deferred)
S Small (2–3d)
M Medium (4–6d)
L Large (7–10d)

Phase Details

Each phase closes a specific competitive gap while building on Pitwall's differentiation. Blue pills highlight where Pitwall goes beyond feature parity.

P18 — Cookie Auth M NEXT
CodexBar has: Direct browser cookie reads for zero-config auth
Pitwall builds: Opt-in browser cookie extraction with explicit user consent. Fixes broken ChatGPT login and eliminates manual session token entry friction.
Opt-in consent, not silent reads
Effort: 5–7 days
P16 — Distribution S
CodexBar has: GitHub Releases with signed DMG, Homebrew tap, auto-update via Sparkle
Pitwall builds: Automated release pipeline with GitHub Releases, Homebrew formula, and Sparkle auto-update. Moves from make install to one-click install for end users.
Signed + notarized builds
Effort: 3–4 days
P19 — CLI Tool M
CodexBar has: codexbar CLI with JSON output, scriptable queries
Pitwall builds: pitwall CLI as a separate product in the monorepo, sharing PitwallCore pacing engine. Exposes pace, Push/Conserve/Switch recommendations, and JSON output.
Separate monorepo product
Effort: 4–5 days
P22 — WidgetKit Widgets M
CodexBar has: Lock screen + home screen widgets showing usage
Pitwall builds: WidgetKit widgets for macOS Notification Center showing session pace, daily progress bar, and the Push/Conserve/Switch recommendation at a glance.
Decision-first widget UI
Effort: 4–5 days
P21 — Status Badges S
CodexBar has: Color-coded provider status indicators in menu bar
Pitwall builds: Provider health badges showing API status, rate limit state, and data freshness. Integrates with pacing to surface "stale data" confidence warnings.
Freshness + confidence signals
Effort: 1.5–2.5 days
P20 — Provider Guide S
CodexBar has: Community contribution guide, provider template, ~1k forks
Pitwall builds: Provider integration guide with template, test harness, and contribution workflow. Lowers the barrier for community-contributed provider support.
Test harness for contributors
Effort: 1.5–2.5 days
P17 — Provider Coverage L DEFERRED
CodexBar has: 40+ provider integrations including Cursor, Copilot, Windsurf, and more
Pitwall builds: Provider abstraction layer + Cursor and Copilot integrations. Deprioritized — current 3-provider coverage (Claude, Codex, Gemini) is sufficient for now.
Confidence labels per provider
Effort: 7–10 days (when prioritized)

CodexBar Architecture Reference

Analysis of steipete/codexbar — how they structure percentage display, rate windows, and pace calculations. Key patterns to adopt, adapt, or differentiate from.

Percentage Display
CodexBar
Three display modes: percent ("73%"), pace ("+5%"), or both ("73% · +5%"). Always integer display, clamped 0–100. No fractional percentages shown to users.
Pitwall Opportunity
Pitwall already shows fractional daily pace (e.g., "3.2%"). Consider whether the integer-only approach is cleaner for menu bar display while keeping fractional precision in the popover detail view.
Rate Window Model
RateWindow {
  usedPercent: Double     // 0–100
  windowMinutes: Int?   // 300 (session), 10080 (weekly)
  resetsAt: Date?
  nextRegenPercent: Double? // rolling recovery providers
}
Primary
Session window (e.g., Claude 5h)
Secondary
Weekly window (7-day)
Tertiary
Third tier (Cursor, Perplexity)
Extra Named
Feature-specific (Claude "Designs")
Key insight: CodexBar normalizes windows by duration — 300-min windows → primary, 10,080-min → secondary. Pitwall's session/daily/weekly tiers map naturally to this, but our daily tier (synthetic, computed from provider windows) has no CodexBar equivalent — it's a Pitwall differentiator.
Pace Calculation
CodexBar Approach
Compares actual usage against time-proportional expectation within the window. Seven stage thresholds based on delta from expected:
±2% onTrack ±6% slight ±12% ahead/behind >12% far
User sees: menu bar delta ("+5%"), progress bar pace marker (green/red), labels ("On pace", "X% in deficit", "X% in reserve"), ETA projections ("Runs out in 3h"), and run-out probability.
Historical Pace (Advanced)
Exponential weighting with 3-week tau, median-based interpolation across 169-point grids, and runout probability via Laplace-smoothed estimates. JSONL persistence with 56-day retention, 30-min write intervals, 1% delta threshold.
Key Finding: Monitoring vs. Decision Engine
CodexBar has sophisticated pace analytics (7-stage classification, historical weighting, ETA, run-out probability) but deliberately stops at observation. It never says "slow down", "push harder", or "switch providers." Labels are neutral descriptors ("X% in deficit"), not action verbs. Pitwall's differentiation isn't that we track pace — they do too. It's that we translate pace data into decisions (Push/Conserve/Switch) and route across providers. Their historical exponential weighting is worth studying for Pitwall's estimation fallback accuracy.
Pitwall Alignment Decision
For preview docs and CodexBar parity work, use CodexBar's point-delta model: paceDelta = actualUsedPercent - expectedUsedPercent. The bands are absolute percentage points, not ratios: ±2 points is closest-to-target, ±6 points is slight reserve/deficit, ±12 points is materially off pace, and beyond 12 points is far off pace. This matters for Pitwall's daily session slices: a 1.1% / 2.5% slice is only 1.4 points in reserve and should render closest-to-target, even though a ratio calculation would call it severe underuse.
Current Swift helpers still contain ratio-based UI fallbacks in ProviderUsageRowsViewModel and MenuBarStatusFormatter. If Pitwall migrates production behavior, those helpers should be replaced by a shared point-delta pace classifier so Session, Daily, Weekly, widgets, CLI, and preview docs all agree.
Fetch Strategies (per provider)
🔑
Admin API
Direct token auth
🔐
OAuth
Token + refresh flow
🍪
Cookie Scrape
Browser cookie reads
⌨️
CLI Probe
PTY-based CLI exec
P18 relevance: CodexBar's cookie strategy reads Safari/Chrome cookies silently. Pitwall's P18 implementation should study their ClaudeWebFetchStrategy for the cookie format and endpoint patterns, then wrap it in an explicit consent flow — our privacy differentiator.
Provider Abstraction (3-layer)
UI Layer ProviderImplementation
Core Layer ProviderDescriptor
Fetch Layer FetchStrategy
Each CodexBar provider gets 3–6 files. Their ProviderImplementationRegistry uses a giant switch on a 40+ case enum. Pitwall's current 3-provider setup doesn't need this scale, but the window normalization pattern (sorting windows by duration into primary/secondary slots) is worth adopting now — it'll make adding providers incremental rather than architectural.

Status Badges — Deep Dive

CodexBar shows a simple green/yellow/red dot per provider — an "is it up?" signal. Pitwall can go further by surfacing why data might be unreliable, tying badges directly into the confidence label system that already exists in PitwallCore.

Menu bar badge examples
Claude 2m ago DELTA
ChatGPT 3h ago STALE
Gemini Auth expired NO DATA
Data Freshness
How old is the last successful snapshot? Displays relative time ("2m ago", "3h ago") and degrades from green to yellow to red as staleness increases. Thresholds are per-provider since reset windows vary.
Source: snapshot timestamps already tracked in PitwallCore
Rate Limit State
Is the provider throttling requests? Surfaces HTTP 429 / backoff state so the user understands why data might be stale — not that the provider is down, but that Pitwall is being rate-limited from refreshing.
Source: error codes from fetch cycle
Auth Health
Is the session token or cookie still valid? Especially relevant after P18 ships — if an extracted cookie expires, the badge turns yellow before data goes fully stale. Prompts the user to re-auth before numbers disappear.
Source: auth validation on each fetch attempt
Confidence Roll-up
Per-provider confidence tier for the most recent reading: delta (authoritative), estimated (fallback), or stale (outdated). A provider might be "up" but returning data Pitwall can only estimate from — worth surfacing at a glance.
Source: existing confidence label system in PitwallCore
Complexity note: The 1.5–2.5 day estimate assumes badges are a UI-only layer reading state PitwallCore already tracks (snapshot timestamps, auth status, error counts). If active health checks (pinging provider endpoints independently) are added, this pushes toward medium complexity (~4 days).

Pitwall Differentiation

Feature parity is table stakes. These five angles are why users switch from CodexBar to Pitwall — they represent genuinely different design decisions, not incremental improvements.

Cross-Device Sync (via CalcLLM)
CodexBar is entirely local — pace data lives on one machine. Pitwall's CalcLLM connected edition syncs privacy-minimized pace snapshots (bucketed, not exact percentages) across devices and teams. See your laptop's pace on your desktop, share team utilization pressure without exposing individual productivity. Opt-in per user, per workspace, with payload preview before enablement. CodexBar has no equivalent.
Confidence Labels
Every data point carries an explicit confidence tag — estimated, delta, or stale. CodexBar shows raw numbers without indicating whether the data is fresh or interpolated. Users know exactly how much to trust what they see.
Pacing Decisions (not just pace data)
CodexBar tracks pace too — 7-stage classification, ETA projections, run-out probability. But it stops at observation: "X% in deficit", "Runs out in 3h". Pitwall translates pace into Push / Conserve / Switch — actionable decisions, not neutral descriptors. CodexBar monitors; Pitwall recommends.
Privacy Architecture
Cookie reads require explicit opt-in with a consent dialog explaining what's accessed and why. CodexBar silently reads browser cookies. Pitwall's approach trades a small onboarding friction for genuine user trust and compliance safety.
Decision-First UI
CodexBar's menu bar shows "+5%" deltas and progress bar pace markers — data-forward. Pitwall leads with the recommendation (Push/Conserve/Switch), then backs it with data. Session, daily, and weekly tiers cascade in order of actionability. Same underlying pace data, fundamentally different UX philosophy.

Competitive Landscape

CodexBar is the closest direct competitor, but the broader market includes cost analytics tools, team adoption platforms, and vendor-native dashboards. Source: competitive-analysis.md

CodexBar github
12.9k stars, 40+ providers. Sophisticated pace tracking (7-stage, ETA, run-out probability) but purely observational — no recommendations, no cross-device sync, silent cookie reads.
Threat: High (closest feature set)
BurnRate
Local-first cost analytics for AI coding tools. Tracks Claude Code, Cursor, Copilot. Focuses on "what did I spend" not "should I keep going." More observability than pacing.
Threat: Medium (different angle)
Capr
Team adoption analytics for engineering leaders. Weekly reports, cost anomalies, usage patterns. Adoption-coaching framing risks developer surveillance concerns.
Threat: Low (different buyer)
Vendor Dashboards
Provider-specific billing and admin. Authoritative for invoices and seats but siloed. Don't solve cross-provider pacing or help developers in the moment.
Threat: Ambient (default workaround)
Positioning Map
Pitwall wins on
Subscription pacing windows, cross-provider decision routing, privacy-minimized team sync, daily pace tier (no competitor equivalent), Push/Conserve/Switch action framework.
Pitwall matches on
Local-first developer trust, session/weekly pace tracking, provider usage monitoring, free open-source distribution model.
Pitwall trails on
Provider count (3 vs 40+), distribution (make install vs Homebrew), historical pace sophistication (exponential weighting), community size.
Strategic Openings
Own subscription pacing, not generic analytics
"Can I keep using this tool today, or should I switch?" — no competitor owns this question.
Privacy as architecture, not marketing copy
Make the data boundary explicit. Local app works without sync. Synced data is aggregate buckets only.
Cloud saves as connected-mode benefit
Cross-device history via CalcLLM. CodexBar and BurnRate are single-machine only.
Avoid productivity-score positioning
Capacity and cost intelligence, not individual productivity measurement. No developer leaderboards.

Spec Interview Status (2026-05-19)

Production specification completed via spec interview. Key decisions that refine the roadmap above:

Execution Order Revised
P18 Cookie Auth first (fixes broken ChatGPT login), not P16 Distribution (blocked on Apple Developer enrollment). Final order: P18 → P19 → P22 → P21 → P20 → P16. P17 deferred indefinitely.
P18: Provider-Generic Cookie Config
CookieProviderConfig maps provider → (domain, cookieName, decryptionStrategy). Same reader code for ChatGPT + Claude. Integrates with existing AuthHealthWarning model. Supersedes auth-resilience.md "Automated browser cookie extraction" Non-Goal.
P19: Separate Monorepo Product
CLI lives at apps/pitwall-cli/ with own Package.swift, imports PitwallCore as local dependency. Shares Keychain credentials — no separate config. pitwall suggest gives Push/Conserve/Switch.
P22: Dual-Write Data Sharing
App writes WidgetSnapshot to both current storage and App Group container. No migration of existing storage. Small widget: single pacing word + color. Medium: all providers.
P21: Unified 4-Signal Badge
Composes external status, data freshness, auth health, and confidence roll-up. Worst-case determines color. StatusChecker actor polls Atlassian Statuspage endpoints every 5 min with debounce.
Full Spec Documents
specs/codexbar-competitive-parity.md
specs/codexbar-competitive-parity-interview.md
Architecture alignment page