# 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

```bash
python3 -m unittest tests.test_collector -v
```

On a machine with `grok login` already done:

```bash
./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