Omahub
← All plugins
V

Grok Usage

by Vitally Tezhe

Writes Grok usage into the stock Omarchy Agents panel. No bar widget of its own.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
a77bde2
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

Low
AI risk level
Low
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
a77bde2
Reviewed
1 month ago

The plugin is a transparent, well-written collector that reads the user's local Grok auth token and queries the official Grok billing endpoint to write a usage JSON file for the Omarchy Agents panel. It includes strong security measures (O_NOFOLLOW, size caps, redirect/same-origin checks) and no obfuscation or destructive behavior. The only inherent risk is that it accesses a credential file, but it does so only for its stated purpose and never exfiltrates the token.

  • Reads ~/.grok/auth.json containing the Grok auth token; though it only sends it to the official cli-chat-proxy.grok.com endpoint, a compromise of that endpoint could expose the token.
  • Runs a background service that periodically makes network requests; this is disclosed and matches the plugin's purpose.
How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/vitally/omarchy-grok-usage --enable
Developer Tools #quickshell #ai

Grok Usage

Headless collector that writes a Grok tab for the stock Omarchy Agents widget.

ID: vt.grok-usage Author: Vitally Tezhe License: MIT

Stock Omarchy already shows Claude, Codex, and Fireworks. This plugin does not replace that widget. It runs in the background, writes ~/.local/state/omarchy/agents/usage/grok.json, and the first-party panel picks the file up the same way it picks up any other agent record.

The collector is a JavaScript port of calmasacow/omarchy-grok-usage. Unofficial. Not affiliated with xAI or Omarchy.

Install

Grok Build must already be signed in (grok login), and a JavaScript runtime (node or bun) must be available to omarchy-shell — on PATH, or as a mise/user shim under ~/.local. Leave omarchy.agents in the bar.

omarchy plugin add https://github.com/vitally/omarchy-grok-usage.git --enable

Left-click the robot head. A Grok chip appears once the first write lands. The mark is the stock robot glyph: this plugin does not ship panel chrome.

Usage

The stock Agents panel is unchanged: left-click opens it, r refreshes Claude/Codex/Fireworks. Grok refreshes on this service's timer (15 minutes, matching the stock collectors) and once at shell start. A billing outage retries after 30 seconds.

Force a Grok rewrite:

omarchy-shell vt.grok-usage refresh

Or run the collector yourself:

node scripts/omarchy-agent-usage-grok.js --write

Remove

omarchy plugin remove vt.grok-usage
rm -f "${XDG_STATE_HOME:-$HOME/.local/state}/omarchy/agents/usage/grok.json"

Removing the plugin stops writes; delete grok.json if you also want the tab gone.

How it works

omarchy-agent-usage-update only scans $OMARCHY_PATH/bin, so a Grok collector cannot live there. This service runs scripts/omarchy-agent-usage-grok.js --write and drops grok.json in the directory the stock panel already watches.

The collector reads ~/.grok/auth.json and asks the same CLI-proxy billing endpoints Grok Build uses for /usage. That is the SuperGrok weekly pool, plan name, and prepaid balance — the same meters /usage shows. Session transcripts are not scanned, so the stock panel will not show tokens-by-day or tokens-by-model for Grok.

Authenticated requests stay on cli-chat-proxy.grok.com and refuse cross-origin redirects. Auth and cache files are opened as regular files with a size cap (O_NOFOLLOW, O_NONBLOCK). No tokens are stored in this repository.

File Role
Service.qml Timer + runtime probe + collector process
scripts/omarchy-agent-usage-grok.js SuperGrok billing probe

Requirements

  • Omarchy with the stock Agents widget
  • Grok Build signed in (grok login)
  • node or bun (dependency-free script; no npm packages)

Tests

node test/collector.test.js

License

MIT. The collector is a JavaScript port of calmasacow/omarchy-grok-usage.