GrokUsage

Grok credit usage in your macOS menu bar.

A small, native, Grok-only status item: white circular ring showing remaining %, click for a compact remaining-focused chart with reset countdown and burn-rate estimate. Reuses local grok login — no telemetry. v1.3.0

完整安装与使用（中文）→ docs/INSTALL.md
Full install & usage guide (中文 + English quick start)

Quick install

git clone https://github.com/xiangjinwei2003/GrokUsage.git
cd GrokUsage
export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
./Scripts/package_app.sh
open dist/GrokUsage.app

Then run grok login if you have not already. Left-click the menu bar ring for details; right-click for Refresh / Settings / Quit.

Copy to Applications (optional):

cp -R dist/GrokUsage.app /Applications/

If macOS blocks the app: right-click → Open, or xattr -cr dist/GrokUsage.app.

Features

• Menu bar only (no Dock icon): white circular meter + remaining percent (display mode: ring+percent / percent-only)
• Click for detail: remaining ring/meter, prominent reset, amount left, burn-rate (“enough for ~Xd”), equal-width Refresh/Ready
• Real usage pipeline (not hard-coded demo numbers):
  1. Identity from ~/.grok/auth.json (grok login)
  2. Optional grok agent stdio JSON-RPC x.ai/billing
  3. grok.com gRPC-web GetGrokCreditsConfig with Bearer token
  4. Local ~/.grok/sessions/**/signals.json informational fallback
• Reliability: last-good retained as stale on failure; refresh throttle; actionable grok login messaging
• Settings: Launch at Login, severity thresholds, optional high-usage notify (default off), About version
• Auto-refresh (default 5 minutes, configurable)
• Packaging: ./Scripts/package_app.sh → dist/GrokUsage.app + versioned dist/GrokUsage-1.3.0.zip (ad-hoc signed)
• --smoke CLI for headless JSON (identity redacted by default)
• Privacy-first: no analytics; tokens never logged

Requirements

• macOS 14 Sonoma or later
• Xcode 15+ / Swift 5.9+ (full Xcode recommended for tests)
• Grok CLI with grok login

Build & test

export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
swift build
swift build -c release
swift test
./Scripts/package_app.sh          # → dist/GrokUsage.app

Binary: .build/release/GrokUsage

swift run GrokUsage               # menu bar
.build/release/GrokUsage --smoke  # headless JSON

Configuration

Setting	Default	Where
Refresh interval	5 min	Right-click → Settings
CLI RPC first	on	Settings
Launch at Login	off	Settings (SMAppService)
High-usage notify	off	Settings
Severity thresholds	50 / 75 / 90 used%	Settings
Status bar display	Ring + percent	Settings
Auth file	~/.grok/auth.json	Override with GROK_HOME
Version	1.3.0	Settings About / VERSION

Architecture

GrokUsageCore          pure domain (auth, parse, normalize, format, pipeline)
GrokUsage              AppKit status item + SwiftUI popover + --smoke entry
Tests/GrokUsageCoreTests   fixture-driven unit tests

Docs

Doc	Content
docs/INSTALL.md	安装 / 使用 / 故障排除（中文）
docs/PRD.md	Product requirements
docs/PRIVACY.md	Privacy
docs/ENTITLEMENTS.md	Sandbox / signing notes
docs/APP_STORE_READINESS.md	Review checklist

Security

• Never commit ~/.grok/auth.json or real OAuth tokens.
• GrokUsage --smoke omits account identity by default; use --include-identity only locally.
• Redact email in screenshots before posting publicly.

License

MIT