quotacli-mac 0.1.0__tar.gz

quotacli_mac-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: macos-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

quotacli_mac-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.coverage

quotacli_mac-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lokesh Devnani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quotacli_mac-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: quotacli-mac
+Version: 0.1.0
+Summary: Terminal quota tracker for Claude Code, Cursor, Codex, Antigravity, and Grok
+Project-URL: Homepage, https://github.com/lokeshdevnani/quotacli
+Project-URL: Repository, https://github.com/lokeshdevnani/quotacli
+Project-URL: Issues, https://github.com/lokeshdevnani/quotacli/issues
+Author-email: Lokesh Devnani <lokeshdevnani@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: antigravity,claude-code,cli,codex,cursor,grok,quota,rate-limit,usage
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyobjc-framework-security>=10.0; sys_platform == 'darwin'
+Requires-Dist: rich>=13.7
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# quotacli
+
+Terminal quota tracker for Claude Code, Cursor, Codex, Antigravity, and Grok.
+Reads the credentials each tool already stores locally on your Mac — no new
+sign-in flow, nothing sent anywhere except each provider's own usage endpoint.
+
+macOS only: every provider's read mechanism (Keychain, `~/Library/...` paths,
+`lsof`/`ps` process discovery) is macOS-specific.
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```
+quotacli                                  # one-shot table, all 5 providers
+quotacli --watch [--interval 30]          # live-refreshing view, like top
+quotacli --json                           # machine-readable output
+quotacli --provider claude-code           # limit to one or more providers (repeatable)
+quotacli --provider antigravity -v        # report which of Antigravity's 4 data-source tiers answered
+```
+
+State (last-known-good snapshots, and Claude Code/Codex 429 backoff
+deadlines) persists at `~/.config/quotacli/state.json`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+All 5 providers' undocumented, reverse-engineered endpoints can drift without
+notice. The pure response-parsing function per provider
+(`providers/<name>.py::parse_*`) is unit-tested against frozen fixtures in
+`tests/fixtures/` — periodically run `quotacli <provider-id>` live and diff
+against those fixtures to catch upstream API changes.
+
+What isn't (and can't be) covered by the unit tests:
+
+- **Keychain enumeration** (Claude Code, Antigravity) — needs a machine with
+  the real tool installed and signed in. Claude Code specifically rotates
+  its keychain item on every token refresh instead of updating one in
+  place, so the "pick the newest of several duplicates by modification
+  date" logic in `keychain.py` can only be validated against a real account
+  that's rotated at least once.
+- **Antigravity's tier-2 local bridge** (`ps`/`lsof` process discovery,
+  scoped self-signed-TLS bypass) — only testable with Antigravity actually
+  running. Use `quotacli --provider antigravity -v` to see which of the 4
+  tiers answered.
+- **429 backoff persisted across real repeated invocations** — the backoff
+  math and state round-trip are both unit-tested in isolation and trusted
+  to compose correctly; forcing a real 429 against the live API to test the
+  full path end-to-end isn't practical.
+
+## Not yet built
+
+A `caffeinate`-style subcommand (keep the Mac awake while a tracked
+provider's CLI is actively running) is planned but intentionally deferred —
+the CLI is a `click.Group` from the start so it can be added later without
+restructuring the entrypoint.

quotacli_mac-0.1.0/README.md

@@ -0,0 +1,66 @@
+# quotacli
+
+Terminal quota tracker for Claude Code, Cursor, Codex, Antigravity, and Grok.
+Reads the credentials each tool already stores locally on your Mac — no new
+sign-in flow, nothing sent anywhere except each provider's own usage endpoint.
+
+macOS only: every provider's read mechanism (Keychain, `~/Library/...` paths,
+`lsof`/`ps` process discovery) is macOS-specific.
+
+## Install
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## Usage
+
+```
+quotacli                                  # one-shot table, all 5 providers
+quotacli --watch [--interval 30]          # live-refreshing view, like top
+quotacli --json                           # machine-readable output
+quotacli --provider claude-code           # limit to one or more providers (repeatable)
+quotacli --provider antigravity -v        # report which of Antigravity's 4 data-source tiers answered
+```
+
+State (last-known-good snapshots, and Claude Code/Codex 429 backoff
+deadlines) persists at `~/.config/quotacli/state.json`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+All 5 providers' undocumented, reverse-engineered endpoints can drift without
+notice. The pure response-parsing function per provider
+(`providers/<name>.py::parse_*`) is unit-tested against frozen fixtures in
+`tests/fixtures/` — periodically run `quotacli <provider-id>` live and diff
+against those fixtures to catch upstream API changes.
+
+What isn't (and can't be) covered by the unit tests:
+
+- **Keychain enumeration** (Claude Code, Antigravity) — needs a machine with
+  the real tool installed and signed in. Claude Code specifically rotates
+  its keychain item on every token refresh instead of updating one in
+  place, so the "pick the newest of several duplicates by modification
+  date" logic in `keychain.py` can only be validated against a real account
+  that's rotated at least once.
+- **Antigravity's tier-2 local bridge** (`ps`/`lsof` process discovery,
+  scoped self-signed-TLS bypass) — only testable with Antigravity actually
+  running. Use `quotacli --provider antigravity -v` to see which of the 4
+  tiers answered.
+- **429 backoff persisted across real repeated invocations** — the backoff
+  math and state round-trip are both unit-tested in isolation and trusted
+  to compose correctly; forcing a real 429 against the live API to test the
+  full path end-to-end isn't practical.
+
+## Not yet built
+
+A `caffeinate`-style subcommand (keep the Mac awake while a tracked
+provider's CLI is actively running) is planned but intentionally deferred —
+the CLI is a `click.Group` from the start so it can be added later without
+restructuring the entrypoint.

quotacli_mac-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "quotacli-mac"
+version = "0.1.0"
+description = "Terminal quota tracker for Claude Code, Cursor, Codex, Antigravity, and Grok"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Lokesh Devnani", email = "lokeshdevnani@gmail.com" }]
+keywords = ["cli", "claude-code", "cursor", "codex", "antigravity", "grok", "quota", "rate-limit", "usage"]
+classifiers = [
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS :: MacOS X",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+    "Typing :: Typed",
+]
+dependencies = [
+    "click>=8.1",
+    "rich>=13.7",
+    "httpx>=0.27",
+    "pyobjc-framework-Security>=10.0; sys_platform == 'darwin'",
+]
+
+[project.urls]
+Homepage = "https://github.com/lokeshdevnani/quotacli"
+Repository = "https://github.com/lokeshdevnani/quotacli"
+Issues = "https://github.com/lokeshdevnani/quotacli/issues"
+
+[project.scripts]
+quotacli = "quotacli.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov", "build", "twine"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/quotacli"]

quotacli_mac-0.1.0/src/quotacli/__init__.py

@@ -0,0 +1,3 @@
+"""quotacli — terminal quota tracker for AI coding-assistant CLIs."""
+
+__version__ = "0.1.0"

quotacli_mac-0.1.0/src/quotacli/__main__.py

@@ -0,0 +1,4 @@
+from quotacli.cli import main
+
+if __name__ == "__main__":
+    main()

quotacli_mac-0.1.0/src/quotacli/backoff.py

@@ -0,0 +1,52 @@
+"""Pure backoff/retry-after math, shared by the Claude Code and Codex
+providers. Kept dependency-free and side-effect-free so it's trivially
+unit-testable without credentials, network, or state.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from email.utils import parsedate_to_datetime
+
+
+def parse_retry_after(header_value: str | None) -> float:
+    """Parse a Retry-After header into seconds (>=0).
+
+    Accepts either a plain integer-seconds string or an HTTP-date string.
+    Missing or unparseable input returns 0.0 — callers must never trust this
+    value alone (some APIs send `Retry-After: 0`), only use it to raise a
+    floor computed independently.
+    """
+    if not header_value:
+        return 0.0
+    header_value = header_value.strip()
+    if header_value.isdigit():
+        return float(header_value)
+    try:
+        when = parsedate_to_datetime(header_value)
+    except (TypeError, ValueError):
+        return 0.0
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=dt.timezone.utc)
+    delta = (when - dt.datetime.now(dt.timezone.utc)).total_seconds()
+    return max(0.0, delta)
+
+
+def claude_code_backoff_seconds(attempt: int, retry_after_seconds: float) -> float:
+    """Exponential backoff for Claude Code's /usage endpoint.
+
+    Floor starts at 60s and doubles per consecutive 429 (attempt is
+    0-indexed on the first 429), capped at attempt index 4 (60*2^4=960,
+    clamped to the overall 900s/15min ceiling). The server's Retry-After
+    header only ever raises this floor, never overrides it — Anthropic's
+    endpoint has been observed sending `Retry-After: 0`.
+    """
+    floor = min(900.0, 60.0 * (2 ** min(attempt, 4)))
+    return max(floor, retry_after_seconds)
+
+
+def codex_backoff_seconds(retry_after_seconds: float) -> float:
+    """Flat backoff for Codex's usage endpoint: minimum 60s, or the
+    server's Retry-After value if it asks for longer. No exponential
+    doubling on repeated 429s (simpler than Claude Code's scheme)."""
+    return max(60.0, retry_after_seconds)

quotacli_mac-0.1.0/src/quotacli/cli.py

@@ -0,0 +1,171 @@
+"""quotacli entrypoint. A click Group (not a bare command) so a future
+`quotacli caffeinate` subcommand can be added later without restructuring.
+"""
+
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+import click
+from rich.live import Live
+
+from quotacli.protocol import ErrorKind, Provider, ProviderError
+from quotacli.providers import build_providers
+from quotacli.render import RenderRow, build_compact, build_json, build_table, console
+from quotacli.state import StateStore
+
+DEFAULT_INTERVAL = 30
+
+
+def _safe_fetch(provider: Provider, store: StateStore) -> RenderRow:
+    try:
+        snapshot = provider.fetch_snapshot()
+        return RenderRow.from_snapshot(provider.id, provider.display_name, snapshot)
+    except ProviderError as exc:
+        cached = store.get_cached_snapshot(provider.id)
+        return RenderRow.from_error(provider.id, provider.display_name, exc, cached)
+
+
+def gather_rows(providers: list[Provider], store: StateStore) -> list[RenderRow]:
+    order = {p.id: i for i, p in enumerate(providers)}
+    rows: list[RenderRow] = []
+    with ThreadPoolExecutor(max_workers=max(1, len(providers))) as pool:
+        futures = {pool.submit(_safe_fetch, p, store): p for p in providers}
+        for future in as_completed(futures):
+            rows.append(future.result())
+    rows.sort(key=lambda r: order[r.provider_id])
+    return rows
+
+
+def _visible_rows(rows: list[RenderRow], *, show_all: bool, explicit_ids: set[str]) -> list[RenderRow]:
+    """Hide providers that have never been signed in and have nothing
+    cached to show — pure noise if you don't use that tool. A provider
+    named explicitly via --provider is always shown regardless (asking for
+    it by name is an unambiguous request to see it, even if unauthenticated),
+    and --all bypasses this filter entirely."""
+    if show_all:
+        return rows
+    visible = []
+    for row in rows:
+        if row.provider_id in explicit_ids:
+            visible.append(row)
+            continue
+        if (
+            row.snapshot is None
+            and row.error is not None
+            and row.error.kind == ErrorKind.NEEDS_AUTH
+        ):
+            continue
+        visible.append(row)
+    return visible
+
+
+def _print_verbose_tiers(providers: list[Provider]) -> None:
+    """Antigravity's bridge-discovery tier can't be meaningfully unit-tested
+    end-to-end, so -v reports which of its 4 tiers actually answered."""
+    for provider in providers:
+        tier = getattr(provider, "last_tier", None)
+        if tier is not None:
+            console.print(f"[dim]{provider.display_name}: answered via {tier}[/dim]", highlight=False)
+
+
+@click.group(invoke_without_command=True)
+@click.option("--watch", is_flag=True, help="Live-refreshing view, like top.")
+@click.option(
+    "--interval",
+    default=DEFAULT_INTERVAL,
+    show_default=True,
+    help="Refresh interval in seconds for --watch.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+@click.option(
+    "--provider",
+    "provider_ids",
+    multiple=True,
+    help="Limit to one or more provider ids (repeatable), e.g. --provider claude-code.",
+)
+@click.option("-v", "--verbose", is_flag=True, help="Report which data source answered per provider.")
+@click.option(
+    "-a",
+    "--all",
+    "show_all",
+    is_flag=True,
+    help="Include providers that aren't signed in (hidden by default).",
+)
+@click.option(
+    "--compact",
+    is_flag=True,
+    help="Single line, statusline-style: glyph + worst % per provider, no labels or reset times.",
+)
+@click.pass_context
+def main(
+    ctx: click.Context,
+    watch: bool,
+    interval: int,
+    as_json: bool,
+    provider_ids: tuple[str, ...],
+    verbose: bool,
+    show_all: bool,
+    compact: bool,
+) -> None:
+    """Quota status for Claude Code, Cursor, Codex, Antigravity, and Grok.
+
+    Providers that have never been signed in are hidden by default; pass
+    -a/--all to see them too.
+    """
+    if ctx.invoked_subcommand is not None:
+        return
+
+    providers = build_providers()
+    explicit_ids: set[str] = set(provider_ids)
+    if explicit_ids:
+        known = {p.id for p in providers}
+        unknown = explicit_ids - known
+        if unknown:
+            raise click.UsageError(
+                f"Unknown provider id(s): {', '.join(sorted(unknown))}. "
+                f"Known: {', '.join(sorted(known))}."
+            )
+        providers = [p for p in providers if p.id in explicit_ids]
+
+    store = StateStore()
+
+    if as_json and watch:
+        raise click.UsageError("--json and --watch cannot be combined.")
+    if verbose and watch:
+        raise click.UsageError("--verbose and --watch cannot be combined.")
+    if as_json and compact:
+        raise click.UsageError("--json and --compact cannot be combined.")
+    if verbose and compact:
+        raise click.UsageError("--verbose and --compact cannot be combined.")
+
+    if as_json:
+        rows = _visible_rows(gather_rows(providers, store), show_all=show_all, explicit_ids=explicit_ids)
+        console.print_json(build_json(rows))
+        return
+
+    if not watch:
+        rows = _visible_rows(gather_rows(providers, store), show_all=show_all, explicit_ids=explicit_ids)
+        if compact:
+            console.print(build_compact(rows), highlight=False)
+        else:
+            console.print(build_table(rows))
+            if verbose:
+                _print_verbose_tiers(providers)
+        return
+
+    with Live(console=console, refresh_per_second=1) as live:
+        try:
+            while True:
+                rows = _visible_rows(
+                    gather_rows(providers, store), show_all=show_all, explicit_ids=explicit_ids
+                )
+                live.update(build_compact(rows) if compact else build_table(rows))
+                time.sleep(interval)
+        except KeyboardInterrupt:
+            pass
+
+
+if __name__ == "__main__":
+    main()

quotacli_mac-0.1.0/src/quotacli/httpclient.py

@@ -0,0 +1,18 @@
+"""Shared httpx.Client factory. Each provider call gets a short-lived client
+(`with make_client() as c:`) rather than a shared pool — call volume is low
+enough that connection reuse isn't worth the lifecycle management, especially
+across --watch ticks that can span many minutes.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+DEFAULT_TIMEOUT = 15.0
+USER_AGENT = "quotacli/0.1"
+
+
+def make_client(*, timeout: float = DEFAULT_TIMEOUT, verify: bool = True) -> httpx.Client:
+    """verify=False must only ever be used for Antigravity's self-signed
+    loopback bridge call — never for a real internet-facing endpoint."""
+    return httpx.Client(timeout=timeout, verify=verify, headers={"User-Agent": USER_AGENT})

quotacli_mac-0.1.0/src/quotacli/keychain.py

@@ -0,0 +1,71 @@
+"""macOS Keychain access via pyobjc's Security.framework binding.
+
+Deliberately not the `security` CLI or the `keyring` package: both return a
+single item chosen by an undocumented tie-break and have no way to enumerate
+duplicates and pick the newest by modification date. That enumeration is
+required for Claude Code, which writes a brand-new keychain item on every
+token rotation instead of updating one in place.
+"""
+
+from __future__ import annotations
+
+from Security import (
+    SecItemCopyMatching,
+    kSecAttrAccount,
+    kSecAttrModificationDate,
+    kSecAttrService,
+    kSecClass,
+    kSecClassGenericPassword,
+    kSecMatchLimit,
+    kSecMatchLimitAll,
+    kSecMatchLimitOne,
+    kSecReturnAttributes,
+    kSecReturnData,
+    kSecReturnRef,
+    kSecValueRef,
+    errSecItemNotFound,
+    errSecSuccess,
+)
+
+
+class KeychainError(Exception):
+    """No matching keychain item exists at all. Callers should translate
+    this into ErrorKind.NEEDS_AUTH."""
+
+
+def read_newest_generic_password(service: str, account: str | None = None) -> bytes:
+    """Find all generic-password items matching service(+account), pick the
+    one with the max kSecAttrModificationDate, then fetch its secret data via
+    a single targeted lookup by persistent ref.
+    """
+    query = {
+        kSecClass: kSecClassGenericPassword,
+        kSecAttrService: service,
+        kSecMatchLimit: kSecMatchLimitAll,
+        kSecReturnAttributes: True,
+        kSecReturnRef: True,
+    }
+    if account is not None:
+        query[kSecAttrAccount] = account
+
+    status, results = SecItemCopyMatching(query, None)
+    if status == errSecItemNotFound:
+        raise KeychainError(f"no keychain item for service={service!r}")
+    if status != errSecSuccess:
+        raise KeychainError(f"SecItemCopyMatching attrs failed: OSStatus {status}")
+
+    # kSecMatchLimitAll always returns an NSArray (even for a single match) —
+    # it's already iterable and works directly with max(), no wrapping needed.
+    newest = max(results, key=lambda item: item[kSecAttrModificationDate])
+    value_ref = newest[kSecValueRef]
+
+    fetch_query = {
+        kSecClass: kSecClassGenericPassword,
+        kSecValueRef: value_ref,
+        kSecMatchLimit: kSecMatchLimitOne,
+        kSecReturnData: True,
+    }
+    status, data = SecItemCopyMatching(fetch_query, None)
+    if status != errSecSuccess:
+        raise KeychainError(f"SecItemCopyMatching data failed: OSStatus {status}")
+    return bytes(data)

quotacli_mac-0.1.0/src/quotacli/protocol.py

@@ -0,0 +1,60 @@
+"""Shared provider interface: the contract every provider module implements.
+
+An ABC (not typing.Protocol) is used deliberately — there are five known,
+hand-written implementations, not third-party plugins, so nominal inheritance
+is the more honest fit and lets the base class carry shared helpers later.
+"""
+
+from __future__ import annotations
+
+import abc
+import dataclasses
+import datetime as dt
+import enum
+
+
+class ErrorKind(enum.Enum):
+    NEEDS_AUTH = "needs_auth"  # never signed in / no credential found at all
+    CREDENTIAL_EXPIRED = "credential_expired"  # was valid; provider will self-refresh
+    RATE_LIMITED = "rate_limited"  # 429, backoff in effect
+    ACCESS_DENIED = "access_denied"  # authenticated but server said no
+    NOTHING_METERED = "nothing_metered"  # valid account, nothing to show yet
+    BAD_RESPONSE = "bad_response"  # network error, timeout, unexpected shape
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class ProviderError(Exception):
+    kind: ErrorKind
+    message: str
+    retry_after: dt.datetime | None = None
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.message
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class LimitWindow:
+    label: str
+    used_fraction: float | None
+    resets_at: dt.datetime | None
+    detail: str | None = None
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Snapshot:
+    provider_id: str
+    fetched_at: dt.datetime
+    windows: list[LimitWindow]
+    plan_label: str | None = None
+    is_stale: bool = False
+
+
+class Provider(abc.ABC):
+    id: str
+    display_name: str
+
+    @abc.abstractmethod
+    def fetch_snapshot(self) -> Snapshot:
+        """Fetch live usage. Raises ProviderError on any failure; never
+        returns a partially-valid Snapshot to signal failure."""
+        raise NotImplementedError

quotacli_mac-0.1.0/src/quotacli/providers/__init__.py

@@ -0,0 +1,21 @@
+"""Provider registry, in canonical display order."""
+
+from __future__ import annotations
+
+from quotacli.protocol import Provider
+from quotacli.providers.antigravity import AntigravityProvider
+from quotacli.providers.claude_code import ClaudeCodeProvider
+from quotacli.providers.codex import CodexProvider
+from quotacli.providers.cursor import CursorProvider
+from quotacli.providers.grok import GrokProvider
+
+
+def build_providers() -> list[Provider]:
+    """Instantiate all five providers, in canonical display order."""
+    return [
+        ClaudeCodeProvider(),
+        GrokProvider(),
+        CodexProvider(),
+        CursorProvider(),
+        AntigravityProvider(),
+    ]