Omarchy Grok usage collector

Household SuperGrok weekly quota for the stock Omarchy agents panel. Not a bar plugin. Not a fork of third-party compositor QML.

The panel already draws whatever JSON lands in:

~/.local/state/omarchy/agents/usage/<id>.json

This repo writes grok.json there. When Omarchy later ships omarchy-agent-usage-grok under $OMARCHY_PATH/bin/, this collector stops writing and leaves that file alone.

Requirements

• Omarchy with the Quattro omarchy.agents panel
• Grok Build CLI logged in (grok login) so ~/.grok/auth.json exists
• Python 3.10+ (stdlib only)
• systemd --user

It never stores the Grok token in the usage record, cache, or logs. The token is read from the CLI auth file and sent only as Authorization to xAI's CLI billing/settings HTTPS endpoints, with redirects refused.

Install

git clone git@forgejo.jtmorris.net:ebeneezer/omarchy-grok-usage.git
cd omarchy-grok-usage
python3 -m unittest tests.test_collector -v
./install.sh

install.sh copies the collector to ~/.local/bin/omarchy-grok-usage and enables a 15-minute user timer. It does not write under /usr/share/omarchy and does not name the binary omarchy-agent-usage-grok, so Omarchy's omarchy-agent-usage-update glob will not pick this up.

Left-click the agents icon on the bar. A Grok tab appears once grok.json is ready (weekly percent is enough; local session charts are out of scope).

Coexistence with official collectors

omarchy-agent-usage-update only runs $OMARCHY_PATH/bin/omarchy-agent-usage-*.

Situation	What happens
No official Grok collector	This timer writes grok.json
Official omarchy-agent-usage-grok is executable	--write exits 0 and does not touch grok.json
You want to keep this writer anyway	OMARCHY_GROK_USAGE_FORCE=1

After an Omarchy update that ships Grok, you can also ./uninstall.sh. Uninstall does not delete grok.json.

Commands

omarchy-grok-usage           # print the record on stdout
omarchy-grok-usage --write   # atomic replace of grok.json, unless yielding
systemctl --user status omarchy-grok-usage.timer
journalctl --user -u omarchy-grok-usage.service -n 50

Security notes

• Reads ~/.grok/auth.json (mode 0600, owned by you)
• HTTPS only, no redirect following
• Token never copied into the JSON the panel reads
• No QML in omarchy-shell
• No prebuilt binary; you run the Python in this tree

Tests

python3 -m unittest tests.test_collector -v

Fixtures use fake tokens. Tests do not touch a live auth.json or the network.

License

MIT. See LICENSE.