Omahub
← All plugins
J

Grok Usage

by James Barnette

Grok on the Omarchy agents panel: SuperGrok weekly meter, today's tokens, and the real Grok mark.

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
08a2053
Scanned
12 hours 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
08a2053
Reviewed
11 hours ago

The plugin is a usage dashboard that reads local Grok session data and queries the official Grok billing endpoint using the user's existing credentials. The code is transparent, well-structured, and includes explicit safeguards (same-origin redirect checks, O_NOFOLLOW file reads, size caps, safe agent-id validation) to prevent token exfiltration and symlink attacks. No malicious or destructive behavior was found.

  • The plugin reads the user's Grok auth token from ~/.grok/auth.json and sends it to cli-chat-proxy.grok.com; this is inherent to its purpose but is a credential-handling surface.
  • The optional sync feature writes snapshots to a user-specified directory; if misconfigured to a sensitive path, it could write there, but this is user-controlled and not a default.
  • The plugin replaces the stock agents widget and runs a Python helper on refresh; the helper is part of the plugin and is not obfuscated.
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/calmasacow/omarchy-grok-usage --enable
Developer Tools #bar #quickshell #ai

Grok Usage

Grok Usage

Grok on the Omarchy agents panel. Opens on your default coding agent.

ID: calmasacow.grok-usage
Author: James Barnette
License: MIT
Version: 0.3.9

Stock Omarchy already shows Claude, Codex, and Fireworks on the robot-head Agents widget. This plugin is that same panel (the bar icon stays the robot head), plus:

  • the Grok mark in the Grok tab (not the star that shipped in 0.2)
  • a weekly SuperGrok meter that matches grok.com: percent used, reset timestamp, and Grok Build vs Chat segments
  • today's token count, remaining percent in the header, and shortcuts to Add Credits / Console / Docs at the bottom of the Grok tab
  • Details always open (sessions, cache hit, top models) — the daily token chart is gone; today's usage is a token stat instead
  • a Grok collector (SuperGrok weekly pool, plan name, local session stats)
  • the panel opens on your default coding agent (omarchy default agent) instead of the first id alphabetically

Enabling it replaces omarchy.agents in the bar. Removing it puts the stock widget back.

Unofficial. Not affiliated with xAI or Omarchy.

Install

Grok Build must already be signed in (grok login).

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

Left-click the robot head. The Grok chip should be selected if your default agent is grok.

Usage

Control Action
Left-click Open / close the usage panel
Right-click Launch the default coding agent
Middle-click Next subscription
h / l Switch subscription
r or Enter Refresh
Esc Close

Remove

omarchy plugin remove calmasacow.grok-usage

If you previously installed the collector-only script (0.1), stop the watcher too:

systemctl --user disable --now omarchy-agent-usage-grok.service
rm -f ~/.config/systemd/user/omarchy-agent-usage-grok.service
rm -f ~/.config/omarchy/agents/omarchy-agent-usage-grok
rm -f ~/.config/omarchy/agents/omarchy-agent-usage-grok-watch
rm -f ~/.config/omarchy/hooks/post-boot.d/start-grok-usage-collector.hook

How it works

The stock panel only displays JSON in ~/.local/state/omarchy/agents/usage/. Packaged omarchy-agent-usage-update scans $OMARCHY_PATH/bin, so Grok cannot live there. This plugin runs scripts/omarchy-agent-usage-grok after each refresh and writes grok.json.

The collector reads the login already in ~/.grok/auth.json and asks the same CLI-proxy billing endpoints Grok Build uses for /usage. Authenticated requests stay on cli-chat-proxy.grok.com and refuse cross-origin redirects so the Grok token is not forwarded. Usage files are opened as regular files with a size cap (O_NOFOLLOW); QML never FileView-reads them. No tokens are stored in this repository.

Optional usage sync publishes snapshots through the Python helper. It opens each sync-directory component without following symlinks, pins the directory with a file descriptor, and atomically replaces the snapshot entry rather than following its symlink target. Snapshot input is bounded and files use mode 0600. Sync folders containing symlink components are rejected.

File Role
Panel.qml Bar icon + usage dashboard
Main.qml Discover records, refresh collectors, prefer default agent
scripts/omarchy-agent-usage-grok Session scan + SuperGrok billing probe

Codex five-hour and weekly limits are recovered through a bounded app-server RPC read if the stock collector loses its response. Recovery uses fresh account limits. The panel keeps the last successful Codex meters during refresh and ignores empty reads or temporary limits-probe failures until valid data arrives. Codex collection and recovery finish before a single atomic report write, so intermediate errors never replace the shared usage file. Empty or failed refreshes leave the previous report in place. Explicit unavailable/authentication errors remain visible.

Requirements

  • Omarchy
  • Grok Build signed in (grok login)
  • python3

License

MIT. Panel QML is adapted from Omarchy's first-party Agents plugin.