GO — Healthy across the board

• Last commit today
• 23+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

CodexBar is a lightweight macOS menu bar app that displays real-time usage quotas and rate-limit reset windows for 15+ AI coding providers (OpenAI Codex, Anthropic Claude, GitHub Copilot, Cursor, Gemini, Vertex AI, etc.) without requiring login. It pulls quota data via provider APIs, CLI credentials, browser cookies, or OAuth flows and renders dynamic status icons in the menu bar, replacing the need to visit each provider's web dashboard. Single-target Swift Package (Package.swift) with monolithic source tree under Sources/CodexBar/ containing ~60 Swift files organized by concern: per-provider runners (CodexLoginRunner.swift, ClaudeLoginRunner.swift), account management (CodexAccountPromotion*.swift, CodexHistoryOwnership.swift), UI overlays (ClickToCopyOverlay.swift), and orchestration. Build/release automation via Makefile and shell scripts in Scripts/ (signing, notarization, icon generation, CLI tarball packaging).

Software developers and engineering teams who actively use multiple AI coding assistants and need to track consumption limits at a glance—particularly those using Codex, Claude, or Copilot who want to avoid quota exhaustion surprises without context-switching to web dashboards.

Production-ready with active maintenance: written in Swift 5.9+, targets macOS 14 Sonoma+, has CI/CD workflows for testing and signed releases, and maintains detailed provider docs in docs/. The codebase is well-organized with clear separation of concerns (login runners, account reconciliation, promotion coordinators), suggesting 1-2+ years of refinement. Recent activity visible in shell scripts for code signing, notarization, and automated upstream monitoring.

Low-risk for core functionality but moderate fragility around provider integrations: each of 15+ providers has its own scraping/API layer (browser cookies, OAuth, CLI parsing) that can break if providers change web structure or deprecate APIs—no test suite visible in the file list. Single-maintainer repo (steipete) with upstream monitoring scripts (upstream-monitor.yml) suggesting awareness of breaking changes. Dependency on macOS 14+ limits backwards compatibility.

Active feature expansion around provider support and account management: recent files suggest work on Codex account promotion coordination/execution/reconciliation logic. CI jobs monitor upstream provider changes (upstream-monitor.yml). Release pipeline handles macOS app notarization and CLI cross-compilation (x86_64 + ARM64 for macOS; x86_64 + aarch64 for Linux). CHANGELOG and release scripts indicate regular cadence.

git clone https://github.com/steipete/CodexBar.git
cd CodexBar
make install-lint-tools
# or: ./Scripts/install_lint_tools.sh
make compile-and-run
# or: ./Scripts/compile_and_run.sh

Requires Xcode 15+ (Swift 5.9), macOS 14+, and optional: swiftformat, swiftlint (linting config in .swiftformat, .swiftlint.yml).

Daily commands:

# Development build & run
make compile-and-run

# Or manually
swift run CodexBar

# CLI version (if building CLI target)
make release-cli
# Outputs: CodexBarCLI-v{version}-macos-{arch}.tar.gz

No dev server (native app). Settings live in System Preferences integration on first run; enable providers and auth via provider-specific flows (OAuth, CLI credentials, browser cookies).

• Sources/CodexBar/ClaudeLoginRunner.swift: Implements OAuth and browser-cookie-based auth for Claude; exemplifies the per-provider authentication adapter pattern used across the codebase.
• Sources/CodexBar/CodexAccountPromotionService.swift: Orchestrates multi-step account state management (reconciliation, planning, execution) for complex provider migrations and account linking.
• Sources/CodexBar/CodexHistoryOwnership.swift: Handles attribution and deduplication of quota usage across multiple accounts/sessions—critical for accurate multi-seat reporting.
• Package.swift: Defines the Swift package and build targets (app + CLI); where new dependencies or target platforms would be added.
• Scripts/sign-and-notarize.sh: Implements macOS app notarization pipeline; required for distribution and circumventing Gatekeeper; critical for release process.
• .github/workflows/upstream-monitor.yml: Automated scraper that detects breaking changes in upstream provider web pages and APIs; prevents silent auth failures.
• Makefile: Central orchestration for dev workflows: linting, building, testing, releasing, signing. Main entry point for contributors.
• docs/: Provider-specific auth flows, quota API endpoints, and breaking-change history. Essential reference for understanding each integration.

Add a new provider: Create Sources/CodexBar/FooLoginRunner.swift (implement auth flow), add parsing in account reconciliation logic, add UI toggle in Settings. Fix provider scraping: Search Sources/CodexBar/*LoginRunner.swift for regex patterns or API endpoints. Add CLI feature: Modify Sources/ and recompile with swift build. Update icons/branding: Edit Icon.icon/Assets/codexbar.png, regenerate with Scripts/build_icon.sh. Change build/signing: Modify Makefile, Scripts/sign-and-notarize.sh, or .github/workflows/. Docs: Provider-specific docs live in docs/{provider}.md (Claude.md, Codex.md, Cursor.md, etc.).

No test suite: No Tests/ directory visible; all validation is manual or CI-based (linting, build success). Provider fragility: Auth flows depend on undocumented/unofficial browser cookie formats, regex patterns against web pages, and internal APIs—expect breakage if providers change UX or deprecate endpoints (mitigated by upstream-monitor.yml). macOS-only core app: Compilation and testing require Xcode on macOS; GitHub Actions used for CI but local dev requires native environment. Credential storage: Relies on macOS Keychain and local cookies; no cross-machine sync—users must re-auth after app reinstall. Swift versioning: Requires Swift 5.9+; older macOS/Xcode versions will fail. CLI cross-compilation: macOS/Linux CLI binaries are built in CI (GitHub Actions); local make release-cli may fail if cross-compilation toolchain not installed.

• Browser Cookie Scraping & Regex Parsing — CodexBar extracts quota data from provider web sessions (Cursor, Claude browser, Copilot) by parsing browser cookies and web page HTML via regex—fragile but necessary since many providers don't expose public quota APIs.
• OAuth Device Flow (RFC 8628) — Codex, Copilot, and Gemini use device-code OAuth flows (CLI polls for auth completion) instead of redirect URIs; CodexBar implements this pattern to avoid embedding browser auth in a menu bar app.
• PTY (Pseudo-Terminal) Fallback Authentication — Claude provider has a CLI PTY fallback mode (ClaudeLoginRunner) that shells out to local CLI tools to extract tokens when OAuth fails; demonstrates defensive design against provider API instability.
• Quota Reset Window Tracking & Rate Limiting — Core feature: CodexBar tracks provider-specific reset schedules (Codex: monthly, Claude: weekly, Copilot: hourly) and displays countdown timers; requires understanding of each provider's billing cycle and rate-limit headers.
• macOS Code Signing & Notarization (Gatekeeper) — Production releases require Apple signing certificates and notarization via Scripts/sign-and-notarize.sh to pass Gatekeeper checks on modern macOS; automated in CI but complex local setup required.
• Account Reconciliation & Multi-Account State Management — CodexBar handles users with multiple accounts per provider (e.g., work + personal Codex orgs) via the CodexAccountReconciliation and CodexAccountPromotion* system; prevents quota double-counting and enables account switching.
• Cross-Platform CLI Compilation (Swift/GitHub Actions) — CodexBar ships both a macOS menu bar app and standalone CLI binaries (macOS x86_64/ARM64, Linux x86_64/aarch64); requires cross-compilation toolchain and multi-target Swift package setup.

• aider-ai/aider — CLI tool for AI-assisted coding that tracks and manages Codex/Claude API usage; complementary to CodexBar's quota display.
• github/copilot-cli — GitHub's official Copilot CLI; provides device-flow auth that CodexBar integrates for Copilot quota tracking.
• anthropics/anthropic-sdk-swift — Official Swift SDK for Claude API; CodexBar uses similar OAuth/API patterns for Claude authentication and quota queries.
• openai/openai-swift — Swift bindings for OpenAI API; provides reference for OAuth and token-based auth patterns CodexBar implements for Codex.
• SwiftBar/SwiftBar — Generic macOS menu bar app framework in Swift; CodexBar builds on similar menu bar architecture and native app patterns.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for CodexAccountReconciliation and CodexHistoryOwnership

The codebase has complex account ownership and history reconciliation logic (Sources/CodexBar/CodexAccountReconciliation.swift and CodexHistoryOwnership.swift) but no visible test files in the structure. These are critical for preventing regressions when multiple providers' credentials interact. Adding Swift unit tests would catch bugs in token reconciliation across providers.

• [ ] Create Tests/CodexBar/CodexAccountReconciliationTests.swift with tests for credential migration and conflict resolution
• [ ] Create Tests/CodexBar/CodexHistoryOwnershipTests.swift to verify token history is correctly attributed to providers
• [ ] Add test targets to Package.swift if not present
• [ ] Update .github/workflows/ci.yml to run swift test as part of CI

Add integration tests for LoginRunner implementations in CI workflow

There are multiple LoginRunner implementations (CodexLoginRunner.swift, ClaudeLoginRunner.swift, CursorLoginRunner.swift, GeminiLoginRunner.swift) but no automated tests validating they work correctly. A GitHub Action could mock the authentication flows and verify token extraction without requiring real credentials.

• [ ] Create Tests/CodexBar/LoginRunnerMockTests.swift with mock implementations of each LoginRunner
• [ ] Add a new GitHub Action workflow .github/workflows/login-tests.yml that runs these tests in CI
• [ ] Mock the browser automation and cookie/token extraction logic to avoid external dependencies
• [ ] Verify the test matrix covers macOS 14+ as per the README requirement

Extract and document provider configuration in PROVIDERS.md

The README mentions support for 10+ providers (Codex, Claude, Cursor, Gemini, Copilot, z.ai, Kiro, Vertex AI, Augment, OpenRouter, Codebuff) but there's no dedicated documentation on how to add new providers or what each provider's login/token mechanism is. This is scattered across multiple LoginRunner files and configuration code. A new PROVIDERS.md file would reduce onboarding friction for contributors.

• [ ] Create PROVIDERS.md with a table listing each provider's: supported auth method, token location, rate limit endpoint, and reset schedule
• [ ] Document the LoginRunner pattern and required methods (CodexLoginRunner.swift pattern as template)
• [ ] Add an example section showing how to add a new provider (e.g. stub for a hypothetical new provider)
• [ ] Link PROVIDERS.md from README.md under an 'Adding Providers' section

• Add unit tests for provider quota parsing: Create Tests/CodexBar/ClaudeLoginRunnerTests.swift with mock API responses and verify quota extraction from ClaudeLoginRunner output. Currently zero test coverage.: Prevents silent auth/parsing regressions when providers change API schema.
• Document the account promotion flow (Codex, Claude multi-account): Expand docs/codex.md and docs/claude.md with diagrams/pseudocode explaining how CodexAccountPromotion{Planning,Execution,Coordinator}.swift interact to migrate quota between accounts.: This logic is core to the app but undocumented; new contributors cannot understand or safely modify it.
• Add support for tracking quota resets for Gemini (Google AI Studio): Implement a GeminiLoginRunner.swift that parses quota-reset timestamps from the Gemini CLI or OAuth token introspection; add toggle in Settings UI.: Gemini is listed in README but reset window tracking is incomplete; fills a gap in provider coverage.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/steipete/CodexBar shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live steipete/CodexBar repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/steipete/CodexBar.

What it runs against: a local clone of steipete/CodexBar — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in steipete/CodexBar | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of steipete/CodexBar. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/steipete/CodexBar.git
#   cd CodexBar
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of steipete/CodexBar and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "steipete/CodexBar(\\.git)?\\b" \\
  && ok "origin remote is steipete/CodexBar" \\
  || miss "origin remote is not steipete/CodexBar (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/steipete/CodexBar"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.