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/nguyenphutrong/quotio 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.

GO — Healthy across the board

• Last commit 5d ago
• 19 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

What it runs against: a local clone of nguyenphutrong/quotio — 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 nguyenphutrong/quotio | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nguyenphutrong/quotio. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nguyenphutrong/quotio.git
#   cd quotio
#
# 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 nguyenphutrong/quotio and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nguyenphutrong/quotio(\\.git)?\\b" \\
  && ok "origin remote is nguyenphutrong/quotio" \\
  || miss "origin remote is not nguyenphutrong/quotio (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Quotio/QuotioApp.swift" \\
  && ok "Quotio/QuotioApp.swift" \\
  || miss "missing critical file: Quotio/QuotioApp.swift"
test -f "Quotio/Services/QuotaFetchers/QuotaFetcherFactory.swift" \\
  && ok "Quotio/Services/QuotaFetchers/QuotaFetcherFactory.swift" \\
  || miss "missing critical file: Quotio/Services/QuotaFetchers/QuotaFetcherFactory.swift"
test -f "Quotio/Services/Proxy/ProxyBridge.swift" \\
  && ok "Quotio/Services/Proxy/ProxyBridge.swift" \\
  || miss "missing critical file: Quotio/Services/Proxy/ProxyBridge.swift"
test -f "Quotio/ViewModels/QuotaViewModel.swift" \\
  && ok "Quotio/ViewModels/QuotaViewModel.swift" \\
  || miss "missing critical file: Quotio/ViewModels/QuotaViewModel.swift"
test -f "Quotio/Services/StatusBarMenuBuilder.swift" \\
  && ok "Quotio/Services/StatusBarMenuBuilder.swift" \\
  || miss "missing critical file: Quotio/Services/StatusBarMenuBuilder.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
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/nguyenphutrong/quotio"
  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).

Quotio is a native macOS menu bar application that unifies management of multiple AI provider accounts (Claude, Gemini, OpenAI, Qwen, Antigravity, etc.) by running a local CLIProxyAPI server and providing real-time quota tracking, smart auto-failover, and one-click configuration for AI coding tools like Claude Code and OpenCode. It solves the problem of juggling separate authentication, quota monitoring, and provider selection across disparate AI services. Single Swift app structure organized into logical modules: Quotio-Models (data types), Quotio-Services (core logic including QuotaFetchers, Proxy, Antigravity integration), Quotio-Views-Screens (UI screens: Dashboard, Quota, Providers, Settings), Quotio-Views-Components (reusable UI elements), and Quotio-Views-Onboarding (first-run flow). Supporting configuration lives in .agentlens/ (agent documentation) and .github/workflows/ (CI/CD).

macOS developers and power users who use multiple AI coding assistants (Claude, Gemini, OpenAI) and need centralized quota management, failover strategies, and CLI proxy configuration without manually switching between provider dashboards or managing API keys across multiple tools.

Actively developed with established infrastructure (GitHub Actions CI/CD workflows for agentlens and release automation, .cursorrules for AI assistance, multi-language support). The 1.5MB+ Swift codebase and structured module organization suggest stability, though explicit test coverage data is not visible in the file list. Production-ready for its intended use case with active maintenance.

Single-language Swift codebase (1.5MB) makes macOS-only distribution a constraint; no visible test directory suggests limited automated test coverage, increasing refactoring risk. Dependency on third-party OAuth providers (Google, Anthropic, OpenAI) and their API stability is an external risk factor. Single-maintainer GitHub handle 'nguyenphutrong' suggests potential bus factor.

Repository includes structured agent-lens documentation (.agentlens/AGENT.md, .agentlens/INDEX.md, module outlines), suggesting recent documentation push. Release automation workflow exists (.github/workflows/release.yml), and there is an active CHANGELOG.md. Evidence of multi-language localization (README.vi.md, README.zh.md, README.fr.md) indicates ongoing internationalization work.

Clone: git clone https://github.com/nguyenphutrong/quotio.git && cd quotio. The package.json shows dependencies on @clack/prompts and TypeScript; use npm install or bun install for JavaScript tooling. For the Swift app itself, open Quotio.xcodeproj or Quotio.xcworkspace in Xcode 15+ and build with xcodebuild or the Xcode UI (minimum macOS 12 likely required given native app).

Daily commands: Open Quotio.xcodeproj in Xcode, select the Quotio scheme, set target to 'My Mac', and press Cmd+R to build and run. The app will launch as a menu bar application. For release builds: xcodebuild -scheme Quotio -configuration Release -derivedDataPath build (check .github/workflows/release.yml for exact flags).

• Quotio/QuotioApp.swift — Main entry point for the macOS app; initializes the menu bar integration and app lifecycle
• Quotio/Services/QuotaFetchers/QuotaFetcherFactory.swift — Factory that instantiates quota fetchers for all providers (Claude, Gemini, OpenAI, Qwen, Antigravity); core abstraction for multi-provider support
• Quotio/Services/Proxy/ProxyBridge.swift — Bridges API requests across multiple providers with auto-failover logic; load-bearing for the core value proposition
• Quotio/ViewModels/QuotaViewModel.swift — Manages quota state, real-time tracking, and UI updates; connects fetchers to views
• Quotio/Services/StatusBarMenuBuilder.swift — Constructs the menu bar interface with provider status and quick actions; UI orchestration layer
• Quotio/Models/AIProvider.swift — Core enum/model defining supported providers and their metadata; fundamental data structure across the app
• Config/Release.xcconfig — Build configuration for release; manages versioning and signing for distribution

Add Support for a New AI Provider

1. Add a new case to the AIProvider enum (Quotio/Models/AIProvider.swift)
2. Create a new QuotaFetcher class (e.g., NewProviderQuotaFetcher.swift) implementing the QuotaFetcher protocol in Quotio/Services/QuotaFetchers/ (Quotio/Services/QuotaFetchers/NewProviderQuotaFetcher.swift)
3. Update the QuotaFetcherFactory to instantiate the new fetcher for the new provider case (Quotio/Services/QuotaFetchers/QuotaFetcherFactory.swift)
4. Add provider metadata (name, icon, endpoint) to AgentConfigurationService (Quotio/Services/AgentConfigurationService.swift)
5. Update ProxyBridge to handle request/response conversion for the new provider (Quotio/Services/Proxy/ProxyBridge.swift)
6. Add API key field to SettingsScreen for the new provider (Quotio/Views/Screens/SettingsScreen.swift)

Add a New UI Tab or Screen

1. Create a new SwiftUI View in Quotio/Views/Screens/ (e.g., NewFeatureScreen.swift) (Quotio/Views/Screens/NewFeatureScreen.swift)
2. Create an associated ViewModel in Quotio/ViewModels/ if state management is needed (Quotio/ViewModels/NewFeatureViewModel.swift)
3. Add a navigation case to the main app's navigation state (likely in AppDelegate or a Navigation model) (Quotio/Views/Screens/DashboardScreen.swift)
4. Integrate the new screen into StatusBarMenuBuilder to expose it in the menu bar menu (Quotio/Services/StatusBarMenuBuilder.swift)

Implement Auto-Failover for a New Code Tool Integration

1. Define the request/response protocol for the new tool in ProxyBridge (Quotio/Services/Proxy/ProxyBridge.swift)
2. Add format conversion rules in FallbackFormatConverter if the tool uses a non-standard API format (Quotio/Services/Proxy/FallbackFormatConverter.swift)
3. Update CLIProxyManager to register the new tool's endpoint and failover chain (Quotio/Services/Proxy/CLIProxyManager.swift)
4. Add a new row to the ProvidersScreen or SettingsScreen to show failover status for the tool (Quotio/Views/Screens/ProvidersScreen.swift)

Add Real-Time Quota Refresh

1. Implement a refresh timer or background task trigger in QuotaViewModel (Quotio/ViewModels/QuotaViewModel.swift)
2. Call fetchAllQuotas() at the desired interval (Quotio/ViewModels/QuotaViewModel.swift)
3. Update QuotaScreen to display refresh timestamp and add a manual refresh button (Quotio/Views/Screens/QuotaScreen.swift)
4. Optionally add refresh frequency settings in SettingsScreen (Quotio/Views/Screens/SettingsScreen.swift)

• SwiftUI — Native macOS framework for building the menu bar UI with real-time data binding and reactive state management
• Combine (Reactive) — Manages asynchronous quota fetches across multiple providers in parallel with Publisher/Subscriber patterns
• REST/HTTP APIs — Lightweight integration with provider quota endpoints (Claude, OpenAI, Gemini, Qwen, Antigravity)
• Local HTTP Proxy —

Requires macOS 12+ and Xcode 15+ for native development; Swift Package Manager or Carthage dependencies not explicitly listed but likely needed. OAuth flows for Google, Anthropic, OpenAI, etc. require registered app credentials (not in repo). The local CLIProxyAPI server must be running for proxy features; quota-only mode works standalone. Menu bar app may have sandboxing restrictions on file access depending on macOS version; check Signing & Capabilities in Xcode. Sparkle updater requires a signed release channel.

• API Proxy Server (CLIProxyAPI) — Quotio's core enables local interception and routing of AI provider requests with failover; understanding proxy request routing, header manipulation, and response transformation is essential to extend provider support
• OAuth 2.0 Authorization Code Flow — Quotio uses OAuth for Google Gemini, Anthropic Claude, OpenAI, and Antigravity authentication; you must understand token refresh, revocation, and scoping to troubleshoot auth issues or add new OAuth providers
• Rate Limiting & Token Bucket Algorithm — Quotio's quota tracking and smart failover (Round Robin / Fill First strategies) depend on understanding token bucket patterns and rate limit tracking per provider
• macOS Menu Bar Application Architecture — Quotio is a menu bar app, not a full window app; understanding NSStatusBar, event loop integration, and background execution is critical for UI/UX changes
• Failover & Fallback Strategies — Quotio implements smart multi-provider failover (Round Robin / Fill First) with FallbackFormatConverter; understanding request retry logic, cascade patterns, and format translation is key to extending failover
• SwiftUI View Model Pattern (MVVM) — Quotio-ViewModels-QuotaViewModel drives the UI; understanding SwiftUI's @Published properties, @ObservedObject, and EnvironmentObject is essential for UI changes
• Multi-Provider API Aggregation — Quotio's core value is unifying quota data from heterogeneous providers (Gemini, Claude, OpenAI APIs with different schemas); understanding payload normalization, fallback parsing, and error handling across APIs is critical

• anthropics/anthropic-sdk-python — Official Claude API SDK; Quotio integrates Claude quotas and authentication, so understanding the API contract is essential
• google-gemini/generative-ai-swift — Google's official Swift SDK for Gemini; Quotio includes Gemini quota fetching and must maintain compatibility with this SDK
• openai/openai-swift — OpenAI's Swift SDK; Quotio integrates OpenAI for quota tracking and proxy failover
• alibaba-cloud-swift/alibaba-cloud-sdk-swift — SDK for Qwen (Alibaba's AI); Quotio supports Qwen quota fetching and must track this provider's API changes
• cline/cline — Popular VSCode AI assistant; Quotio auto-configures similar tools (Claude Code, OpenCode) and shares the problem domain of managing AI assistant credentials and failover

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 QuotaFetchers Service Module

The .agentlens/modules/Quotio-Services-QuotaFetchers/ module lacks documented test coverage. Given that quota fetching is critical to Quotio's core functionality (real-time quota tracking across Claude, Gemini, OpenAI, Qwen, Antigravity), adding unit tests would prevent regressions when adding new providers or modifying fetcher logic. This is a high-risk area that directly impacts user experience.

• [ ] Create Quotio/Tests/Services/QuotaFetchersTests.swift with test cases for each provider's quota fetcher
• [ ] Add tests for error handling scenarios (invalid API keys, network failures, rate limits)
• [ ] Add integration tests for FallbackFormatConverter (referenced in file structure) to ensure quota format normalization works across providers
• [ ] Update .github/workflows/ to run these tests on PR (currently only agentlens.yml and release.yml exist)

Add ProxyBridge Integration Tests and CLI Proxy Manager Tests

The Quotio-Services-Proxy-ProxyBridge-swift.md and Quotio-Services-Proxy-CLIProxyManager-swift.md files suggest complex proxy logic for auto-failover between AI tools (Claude Code, OpenCode, Droid). Without tests, changes to failover logic risk breaking the core value prop. Tests should verify that when one provider fails, requests correctly route to the fallback provider.

• [ ] Create Quotio/Tests/Services/ProxyTests.swift with mocked API responses for testing failover behavior
• [ ] Add tests for CLIProxyManager to verify proxy configuration is correctly applied to CLI tools
• [ ] Add tests verifying ProxyBridge correctly selects fallback providers based on quota status
• [ ] Add edge case tests: simultaneous provider failures, quota exhaustion during request

Document Provider Integration Patterns in CLAUDE.md and Add Custom Provider Extension Guide

The codebase includes CustomProviderSheet-swift.md suggesting users can add custom providers, but there's no documented guide for contributing new provider support. The CLAUDE.md file exists but likely doesn't cover the provider integration pattern. This blocks community contributions of new AI providers and increases maintenance burden on core team.

• [ ] Expand CLAUDE.md with a 'Provider Integration Guide' section explaining: AgentConfigurationService structure, quota fetcher implementation pattern, and fallback format requirements
• [ ] Create docs/CUSTOM_PROVIDERS.md with step-by-step example: integrating a hypothetical new provider by implementing required protocols
• [ ] Reference the specific files from .agentlens/modules/Quotio-Services-*/ that show existing provider implementations
• [ ] Add checklist template for provider PRs to PULL_REQUEST_TEMPLATE.md (currently missing from repo)

• Add test coverage for Quotio-Services-QuotaFetchers module: create unit tests for each provider's quota API parsing (Claude, Gemini, OpenAI, Qwen, Antigravity) in a new Tests/QuotaFetchersTests/ directory to catch quota API breaking changes early
• Write integration documentation for adding a new AI provider: document the exact steps a contributor must follow to add a provider quota fetcher (following the pattern in Quotio-Services-QuotaFetchers), including required API endpoints, auth method, and quota response schema
• Implement CLI fallback format converter tests: the FallbackFormatConverter is critical for multi-provider failover but has no visible test coverage; add unit tests for format conversion between Claude, Gemini, and OpenAI API response styles

• High · Potential API Key Exposure in Configuration Files — Config/ directory, particularly Local.xcconfig and related configuration management. The codebase handles multiple AI service API keys (Claude, Gemini, OpenAI, Qwen, Antigravity). Configuration files like 'Config/Local.xcconfig.example' and similar patterns may contain or reference API credentials. If actual config files (without .example extension) are committed to version control, this poses a critical exposure risk. Fix: 1. Ensure all actual credential files are in .gitignore. 2. Use secure credential storage via macOS Keychain. 3. Implement environment variable injection at build time. 4. Never commit files like Local.xcconfig that contain real API keys. 5. Use Config/Local.xcconfig.example as template only.
• High · Insecure Data Storage in Menu Bar Application — Services layer (QuotaFetchers, AgentConfigurationService), Data models (Quotio-Models). As a native macOS menu bar app managing multiple AI subscriptions and quotas, the application likely stores sensitive information (API keys, usage data, user credentials). Without explicit encryption, this data could be accessible to other processes or through filesystem access. Fix: 1. Implement macOS Keychain integration for all API keys and credentials. 2. Encrypt sensitive data at rest using CryptoKit. 3. Use @Secure property wrappers for sensitive UserDefaults storage. 4. Implement file protection attributes for local data storage. 5. Review data persistence in QuotaViewModel and related storage mechanisms.
• High · Unvalidated CLI Proxy Integration — Quotio-Services-Proxy-CLIProxyManager-swift.md, Quotio-Services-Proxy-ProxyBridge-swift.md, Quotio-Services-Proxy-FallbackFormatConverter-swift.md. The CLIProxyManager and ProxyBridge components interface with external CLI tools. Without proper input validation and sanitization, this could enable command injection attacks, especially when handling fallback scenarios or format conversions. Fix: 1. Implement strict input validation for all CLI command arguments. 2. Use ProcessInfo and Process APIs with explicit argument arrays (never shell strings). 3. Escape or sanitize all user-provided inputs before passing to subprocess. 4. Implement allowlisting for acceptable CLI commands and parameters. 5. Log all CLI invocations for audit purposes.
• Medium · No Visible TLS/Certificate Pinning for API Communications — Services layer (quota fetchers, API integrations). The application communicates with multiple AI service providers (Claude, Gemini, OpenAI, Qwen, Antigravity). Without certificate pinning, the application is vulnerable to man-in-the-middle attacks on untrusted networks. Fix: 1. Implement TLS certificate pinning for all external API calls. 2. Use URLSessionConfiguration with custom serverTrustEvaluator. 3. Pin to CA certificates rather than leaf certificates for flexibility. 4. Implement certificate update mechanisms. 5. Validate all SSL/TLS connections with appropriate security policies.
• Medium · Custom Provider Sheet Input Validation — Quotio-Views-Components-CustomProviderSheet-swift.md. The CustomProviderSheet component allows users to add custom AI providers. User-supplied input (URLs, API endpoints, configuration) must be validated to prevent injection attacks or misconfiguration that could route traffic to malicious servers. Fix: 1. Validate all URL inputs are valid and use secure protocols (HTTPS only). 2. Implement regex or URLComponents-based validation. 3. Restrict allowed URL schemes. 4. Sanitize configuration parameter names and values. 5. Provide user warnings for custom providers. 6. Store and encrypt custom provider configurations securely.
• Medium · Insufficient Quota Tracking Data Validation — Quotio-ViewModels-QuotaViewModel-swift.md, Quotio-Services-QuotaFetchers. The QuotaViewModel fetches and displays quota information from multiple providers. Unauthenticated or unvalidated responses could be manipulated to provide false quota information, potentially misleading users about their service limits. Fix: 1. Validate all API responses against expected schema. 2. Implement response signature verification where possible. 3. Cross-validate quota data across multiple sources. 4. Implement rate limiting on quota fetch requests. 5. Add circuit breakers for unreliable

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

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

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