Skip to content

README.en.md

Latest commit

 

History

History
67 lines (45 loc) · 3.11 KB

README.en.md

File metadata and controls

67 lines (45 loc) · 3.11 KB
Raw

opencode-usage-watchdog

Check quota for one or more OpenCode Go keys. Scheduled runs report only when attention is needed. Python 3.11+, standard library only. 中文

Quick start

git clone https://github.com/getaskclaw/opencode-usage-watchdog.git
cd opencode-usage-watchdog
python3 opencode_usage_monitor.py --once

Single-key discovery remains, in order:

  1. OPENCODE_GO_API_KEY / OPENCODE_ZEN_API_KEY environment variables;
  2. $HERMES_HOME/.env;
  3. ~/.hermes/.env.

OPENCODE_ZEN_API_KEY is a compatibility name: this queries Go usage, not Zen balance.

Multiple keys

Create a private keys.json outside the repository (values below are placeholders):

[
  {"name": "laptop", "key": "YOUR_FIRST_KEY"},
  {"name": "server", "key": "YOUR_SECOND_KEY"}
]
chmod 600 /path/to/keys.json
python3 opencode_usage_monitor.py --keys-file /path/to/keys.json --once
python3 opencode_usage_monitor.py --keys-file /path/to/keys.json --once --json
  • An explicit file overrides environment discovery; invalid files never silently fall back.
  • Identical keys are queried once, keeping the first label. --workers accepts 1–16 (default 4). One failure does not stop other keys.
  • Never put keys in labels, command arguments, Git or screenshots. The config is plaintext: protect it.
  • Multiple keys may share an account. Do not sum their quotas.

Results

Endpoint: GET https://opencode.ai/zen/go/v1/usage, using Bearer authentication.

Reports show used/remaining percentages, status and reset times for rolling, weekly and monthly windows. Text is Chinese; --json provides machine-readable results and success/failure counts.

Percentages are not token counts or bills. The old hardcoded $12/$30/$60 dollar conversion has been removed; OPENCODE_WATCHDOG_DOLLAR_LIMITS is no longer used. A successful usage check does not prove inference works.

Scheduled monitoring

Omit --once for one stateful tick; this is not a daemon. Reports appear on the first check, the first check of a UTC day, a change of at least 2 percentage points, usage at 70% (warning) or 85% (alert), or a non-OK quota status. Failure messages are limited to once an hour per key. Silence does not prove success: check the exit code. --json always emits machine-readable output rather than staying silent.

State/history default to $HERMES_HOME (otherwise ~/.hermes); filenames include a SHA-256 key identifier, never the raw key. OPENCODE_WATCHDOG_STATE and OPENCODE_WATCHDOG_HISTORY override the base paths; the identifier is still added. Legacy unattributed state files are left untouched but not imported, so upgrading produces a fresh first report. Do not run overlapping monitor processes writing the same state.

--once never reads or writes monitoring state/history.

Tests

python3 -m unittest -v
python3 opencode_usage_monitor.py --selftest

Offline tests do not validate real credentials. --selftest needs the repository's test file.

Exit codes: 0 checks completed (quota alerts allowed), 1 configuration error, 2 query/storage failure. Invalid CLI arguments also return 2.