quotio

Centralizes authentication credentials for Claude, Gemini, OpenAI, Qwen, and Antigravity through a native macOS SwiftUI interface that handles provider-specific OAuth flows, token refresh, and secure credential storage in the system keychain. The ManagementAPIClient service abstracts provider-specific authentication patterns while the AppBootstrap component orchestrates initial setup and credential validation during application launch.

Continuously polls quota endpoints for each authenticated provider and displays usage metrics in a dedicated Quota Screen with visual indicators (progress bars, percentage breakdowns, remaining tokens). The QuotaViewModel orchestrates quota fetching services that call provider-specific quota APIs, caches results with configurable refresh intervals, and triggers alerts when usage approaches configured thresholds. Data flows through Swift Concurrency patterns (async/await) to prevent UI blocking.

The Providers Screen allows users to configure advanced, provider-specific settings such as custom API endpoints, request timeout values, retry policies, rate limit overrides, and model-specific parameters. Each provider has a dedicated settings panel with provider-specific options (e.g., Claude's context window size, OpenAI's temperature and top_p parameters). Custom configurations are stored in JSON files in ~/.quotio/providers/ and are applied to all requests routed through that provider. Users can also define custom providers with arbitrary API endpoints and authentication methods.

Quotio implements an auto-update system that checks for new versions on app launch and periodically (every 24 hours). When an update is available, it downloads the new binary in the background without interrupting the user's workflow. The update is staged for installation on the next app launch, with an optional 'Update Now' button to force immediate restart. The system maintains a rollback mechanism to revert to the previous version if the new version fails to launch. Update checks include version comparison, release notes fetching, and optional staged rollout (e.g., 10% of users get the update first).

Quotio supports multiple languages (English, French, Vietnamese, Chinese) through a comprehensive i18n system that localizes all UI strings, date/time formatting, and number formatting. Language selection is available in Settings and persists across app launches. The i18n system uses Swift's built-in Localizable.strings files for each language, with fallback to English if a translation is missing. All user-facing strings in the SwiftUI UI are wrapped with localization keys, ensuring consistent translation across screens.

Implements a Model Fallback Strategy System that automatically routes requests to alternative providers when the primary provider hits quota limits, experiences downtime, or returns errors. The system maintains a fallback chain (e.g., Claude → OpenAI → Gemini) configured per agent, evaluates provider health and quota status in real-time, and transparently switches providers without interrupting the user's workflow. The CLIProxyManager coordinates fallback logic by intercepting proxy requests and applying routing rules before forwarding to the selected provider.

Manages the CLIProxyAPI local proxy server (written in Go) through the CLIProxyManager service, handling installation, startup, graceful shutdown, configuration updates, and continuous health monitoring. The proxy runs as a background process on localhost (configurable port, default 8000) and intercepts requests from IDE plugins and CLI agents, applying quota checks, fallback routing, and authentication before forwarding to providers. Health checks run every 30 seconds via HTTP GET to the proxy's health endpoint; if the proxy becomes unhealthy, the app attempts automatic restart with exponential backoff.

Provides one-click configuration for IDE plugins (VS Code, JetBrains, Cursor) to route requests through the local Quotio proxy instead of directly to providers. The AgentConfigurationService generates provider-specific environment variables and configuration snippets that plugins consume. A Warmup System pre-establishes connections to providers on app launch to reduce latency for the first request. The app monitors active IDE processes and displays real-time request metrics (requests/sec, latency, error rate) in the Agents Screen, enabling developers to see which agents are active and how they're performing.

The AgentConfigurationService generates ready-to-use configuration for CLI agents (Claude Code, OpenCode, Droid) by creating shell aliases, environment variables, and configuration files that point to the Quotio proxy. Users can copy-paste generated configuration into their shell profile or IDE settings. The Agents Screen displays all configured agents, their status (active/inactive), and allows users to enable/disable agents without restarting the proxy. Configuration is persisted in JSON files in the Quotio config directory (~/.quotio/agents.json).

Quotio supports three distinct operating modes to accommodate different workflows: (1) Standard mode runs the full SwiftUI app with menu bar integration, quota monitoring, and agent management; (2) Proxy-Only mode disables the UI and runs only the proxy server in the background, useful for headless servers or minimal resource usage; (3) Headless mode runs the proxy without any UI or menu bar presence, controlled entirely via CLI or configuration files. Mode selection is configured at launch via command-line flags or environment variables, allowing the same binary to serve different deployment scenarios.

Quotio includes native integration with Antigravity, a custom AI provider that offers cost-optimized model routing. The integration allows users to configure Antigravity as a provider, authenticate via API key, and use Antigravity's intelligent model selection to automatically route requests to the cheapest available model that meets quality requirements. Antigravity-specific quota tracking and cost visualization are displayed in the Quota Screen. The fallback system treats Antigravity as a first-class provider, enabling users to use it as a primary or fallback option.

The StatusBarManager integrates Quotio into the macOS menu bar, displaying a compact status icon that shows overall proxy health (green/yellow/red) and provides a click-to-expand menu with quick access to quota status, active providers, and common actions (restart proxy, open settings, view logs). The menu bar icon updates in real-time as quota changes and provider status changes. Clicking the menu bar icon opens a popover with the Dashboard Screen, allowing users to quickly check status without opening the full app window.

Quotio maintains detailed logs of all proxy requests, provider responses, quota checks, fallback events, and errors in a local SQLite database. The Logs Screen provides a searchable, filterable log viewer with columns for timestamp, request type, provider, status code, latency, and error messages. Logs can be filtered by provider, date range, status code, or search terms. Log entries include full request/response payloads (sanitized of sensitive data) for debugging. Logs are automatically rotated and compressed after 30 days to manage disk space.