omarchy-grok-usage/docs/DEV.md

Agent notes — omarchy-grok-usage

Household collector. Owner: John Morris. Author on this Forgejo: Ebeneezer.

Product lock

• Fill SuperGrok weekly remaining quota on the stock Omarchy agents panel.
• Do not add a Quickshell / bar plugin.
• Do not name the installed binary omarchy-agent-usage-grok.
• Do not patch /usr/share/omarchy or omarchy-agent-usage-update.
• When official omarchy-agent-usage-grok exists, --write is a no-op.
• No secrets in git, tests, README examples, or chat.

Layout

Path	Role
src/omarchy_grok_usage.py	Collector (stdlib Python)
bin/omarchy-grok-usage	Checkout launcher (src/ on sys.path)
install.sh / uninstall.sh	User systemd timer
systemd/	--user unit + timer
tests/test_collector.py	unittest, no network

Install copies src/omarchy_grok_usage.py to ~/.local/bin/omarchy-grok-usage.

Verify

python3 -m unittest tests.test_collector -v

On a machine with grok login already done:

./install.sh
python3 -c 'import json,pathlib; p=pathlib.Path.home()/".local/state/omarchy/agents/usage/grok.json"; d=json.loads(p.read_text()); assert d["id"]=="grok"; assert "limits" in d; print(d["tierLabel"], d["ready"], [x.get("percent") for x in d["limits"]])'

Do not print auth.json. Do not dump Authorization headers.

Git

• Public repo is fine. Never commit auth.json, live grok.json, or tokens.
• Forgejo: ebeneezer/omarchy-grok-usage. John (jtmorris) is an admin collaborator.
• Git author for agent commits: Ebeneezer <ebeneezer@jtmorris.net>.

Out of scope

• Claude / Codex / Amp / Cursor
• Session token charts from ~/.grok/sessions
• Chips drawn on the bar itself
• Shipping this as an Omarchy plugin