Read-only stdlib Python CLI (grokbot-usage) that reports this machine's AI usage so Grok Bot agents can check their own consumption before they burn it. Two required meters — cursor (monthly plan % + on-demand $) and grokbot (weekly included pool) — come from one Cursor session. SuperGrok is an optional third meter via grok login on grok.com / x.ai; the Cursor cookie does not unlock it.

Your reset is not anyone else's. Read resetsAt / cycleEnd from ~/.grokbot-usage/latest.json (or re-run the CLI). Those fields are ISO UTC from this account. Convert to the user's local zone when speaking to a human. If a timestamp is missing or the meter is "error", say reset unknown / unavailable. Do not guess a weekday or time.

curl -fsSL https://raw.githubusercontent.com/bcharleson/grokbot-usage-cli/main/install.sh | bash

Fallback: git clone https://github.com/bcharleson/grokbot-usage-cli.git && cd grokbot-usage-cli && ./install.sh

That copies CLI → ~/.local/bin/grokbot-usage and skill → ~/.grok/skills/fleet-usage/SKILL.md. Add ~/.local/bin to PATH if asked. Python 3.10+ (stdlib) is the runtime. The one-liner needs raw.githubusercontent.com readable (repo public or a token).

This skill also belongs wherever that agent reads skills. Copy cli/skills/fleet-usage/SKILL.md into a Cursor project skill dir, a Grok Bot workflow, or another fleet's skill folder.

From a checkout with no install:

python3 cli/grokbot_usage.py

Tokens and cookies are never printed, logged, or committed. Never paste a cookie into chat.

Same session covers both meters. First match wins:

1. Sign in to the Cursor IDE on this machine, or
2. grokbot-usage login --cookie-file ./cursor-cookie.txt (file holds the WorkosCursorSessionToken value copied from cursor.com DevTools → Application → Cookies), or
3. CURSOR_SESSION_COOKIE, or grokbot-usage login --from-ide, or paste via grokbot-usage login (input hidden on a TTY)

login writes ~/.secrets/cursor-session-cookie at mode 0600. grokbot-usage logout deletes it.

Cursor login does not unlock SuperGrok, even when SuperGrok Heavy is linked to Cursor.

curl -fsSL https://x.ai/cli/install.sh | bash
grok login                  # browser
# or, headless:
grok login --device-auth    # open the printed accounts.x.ai URL, confirm the code

Session lands in ~/.grok/auth.json (mode 0600). Never commit it. grok logout clears it. Missing file → SuperGrok {"error": "..."}, never 0%.

grokbot-usage
grokbot-usage --json --write default

The second command writes ~/.grokbot-usage/latest.json. That file is the ledger. Other useful flags:

grokbot-usage --json --write PATH
grokbot-usage --meter grokbot        # cursor | grokbot | supergrok
grokbot-usage --quiet --threshold 90 # exit 1 if grokbot weekly >= threshold

--quiet default threshold is GROKBOT_USAGE_WEEKLY_BUDGET if set, else 90. Exit 0 ok · 1 grokbot threshold / unknown, or every meter failed · 2 usage error.

Human output prints each meter's reset from this account's API timestamp (converted to local). It does not assume a global reset day.

The three pools reset on different clocks. Read them from ~/.grokbot-usage/latest.json. Never hardcode dates. Never invent %.

A SuperGrok sub does not refill Grok Bot. Cursor login does not read SuperGrok. Missing SuperGrok = unavailable, not 0%. If a timestamp is missing: reset unknown.

Agents: before work, one sentence with remaining % and time-to-reset for each available meter. Schedule heavy fleet work just after this account's grokbot.resetsAt. Tell the human when grokbot is over budget, there is a daily spike, Cursor on-demand is over cap, or any meter is <24h to reset and already elevated. Otherwise quiet.

EXAMPLE speech (not live; the next reader's clocks will differ):

Grok Bot 40% used, resets Tuesday 11:00 local; Cursor plan 23% used, cycle ends mid-month; SuperGrok 33% used, resets Friday morning.

Weekdays at 08:00 / 12:00 / 18:00, write the ledger. Agents Read the file. Stay quiet unless over budget. Do not poll with LLM turns.

0 8,12,18 * * 1-5 $HOME/.local/bin/grokbot-usage --json --write default

1. Drop cli/skills/fleet-usage/SKILL.md into the skill path that fleet uses (./install.sh already lands it at ~/.grok/skills/fleet-usage/).
2. Point agents at ~/.grokbot-usage/latest.json.
3. Do not poll usage with extra LLM turns. Do not use browserUse for %.

If asOf is under 6 hours old, Read the ledger only. If missing or stale, shell grokbot-usage --json --write default, then Read.

Never invent numbers. "error" means unavailable, not 0%.

Daily spike: weekly % is GROKBOT_USAGE_DAILY_SPIKE or more above the last ledger you recorded → flag the human once.

Cursor cash flag: onDemandUsedUSD >= onDemandLimitUSD when both are numbers.

When telling a human when the pool refills: read grokbot.resetsAt, cursor.cycleEnd, and (if present) supergrok.resetsAt from the ledger. Convert UTC → local. If missing or error: reset unknown.

Auth ladder for cursor + grokbot (first hit wins): CURSOR_SESSION_COOKIE, then ~/.secrets/cursor-session-cookie, then Cursor IDE state.vscdb (macOS + Linux) → WorkosCursorSessionToken=<sub-after-pipe>%3A%3A<jwt>.

Unofficial endpoints (can change without notice):

POSTs to cursor.com need Origin: https://cursor.com.

The timestamps below are EXAMPLE only. The next reader's resetsAt / cycleEnd and local clock will differ. Do not treat them as a product default.

{
  "asOf": "2026-01-15T16:00:00+00:00",
  "cursor": {
    "planPercentUsed": 40.0,
    "autoPercentUsed": 44.0,
    "apiPercentUsed": 5.0,
    "onDemandUsedUSD": 8.0,
    "onDemandLimitUSD": 100.0,
    "cycleStart": "2026-01-01T00:00:00.000Z",
    "cycleEnd": "2026-02-01T00:00:00.000Z",
    "membership": "pro"
  },
  "grokbot": {
    "weeklyPercentUsed": 55,
    "resetsAt": "2026-01-20T18:00:00.000Z",
    "periodStart": "2026-01-13T18:00:00.000Z",
    "planLabel": "Grok Bot Plan",
    "onDemandEnabled": true
  },
  "supergrok": {
    "weeklyPercentUsed": 22.0,
    "resetsAt": "2026-01-16T12:00:00.000Z"
  }
}

A meter that cannot be read reports {"error": "..."} instead of fake numbers.

MIT — see LICENSE.

See also CONTRIBUTING.md and SECURITY.md.