lov-check-balance

Quota Checkup · Check Balance

Converge the "how much is left and when does it reset" scattered across different agents into a single read-only checkup table: official subscription window quotas, API platform prepaid balances, actual local gateway consumption, and how much longer it can last at the current intensity.

Triggers

Activate when

• The user says "check my quota," "how much usage do Claude / Codex have left," "when does it reset," or "how many more days will the balance last."
• The user wants to be alerted before being rate-limited or before the balance runs out, or needs quotas included in scheduled inspections.
• User asks "how much quota do I have left", "when does the Codex limit reset", or "check the API balance".

Do not activate when

• The user wants to manage, rotate, or add API Keys themselves; leave it to lov-env-management, this Skill only reads existing credentials.
• The user wants to set up scheduled execution and notification channels; leave it to lov-yoda-automation, this Skill only provides --json input.
• The user wants to free up disk space or archive files; leave it to lov-clean-mac。
• The user wants to top up, purchase, or upgrade a subscription; this Skill only reports the current status and does not perform any billing operations.

Output Contract

Each run outputs the same structure, rendered as a text table by default,--json outputs a machine-readable version:

• providers[]: for each account, the id、status(ok / expired / unavailable), plan, window usage and reset time, or balance and currency.
• burn_rate: optional.--watch After secondary sampling, gives hourly consumption and remaining days available.
• alerts[]: windows that are fully used up, balances below the threshold, providers without daily/monthly limits set.

Read-only invariants: the script does not refresh tokens, does not write any credentials, and does not print keys; missing sources are only marked unavailable and a remediation hint is given, without affecting other providers.

User Profile (cross-session)

This Skill in skill.yaml declares user-profile/v1. At runtime, it is resolved in the order "current request → project context → Skill records → shared preferences → shared user/workspace → safe defaults." Long-term preferences stated directly by the user (for example, gateway log path, balance alert threshold) are written back through scripts/profile_store.py record --skill-id lov-check-balance --path records.<字段> --value <值> --confirm , and the save path is reported back. Credentials themselves are never written to the Profile.

Skill Group Composition

First read references/skill-composition.md. Adjacent capabilities are mainly optional handoffs: upstream lov-env-management handles the credential lifecycle, downstream lov-yoda-automation handles scheduling and notification; this Skill does not hide dependencies on any sibling.

Workflow（MANDATORY）

Step 0: Parse the runtime context

• Prefer the SKILL_DIRprovided by the host; otherwise infer the installation directory from the current Skill context.
• Confirm that scripts/check_balance.py and references/providers.md exist; if missing, report the expected relative path and stop.
• Parse the Profile:--profile parameter → LOVSTUDIO_PROFILE → shared Profile default path.

Step 1: Execute detection

python3 scripts/check_balance.py \
  --gateway-log "$GATEWAY_LOG" \
  --min-balance-cny "${MIN_BALANCE_CNY:-50}"

• To check only one category of accounts, use --only codex、--only deepseek, repeatable.
• Add --json。
• when structured downstream consumption is needed; first verify each provider's source and reset semantics by references/providers.md .

Step 2: Secondary sampling when rate is needed

python3 scripts/check_balance.py --watch 120 --json

• Sampling window recommended ≥120 seconds: balances are settled in batches, and the implied exchange rate from a short window cannot be used as a conclusion.
• When the balance has not changed, the script automatically falls back to gateway pricing estimation and annotates estimate_basis。

Step 3: Cross-validation and reporting

• Official subscriptions report "percentage used + reset time"; prepaid balances report "remaining amount + consumption rate".
• Cross-check gateway consumption against balance changes; when the two differ in basis, list both and do not arbitrarily take one as the true value.
• Report the minimal sufficient set: each account's remaining balance, reset time, data source, and items requiring user action.

Dependencies

• Python 3.8+ (standard library only: urllib / sqlite3 / subprocess / json).
• Optional inputs: macOS Keychain,~/.codex/auth.json, cc-switch SQLite, LiteLLM request logs.
• No third-party dependencies, no network write permissions required; unconfigured sources are treated as unavailable.