# 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:

```text
~/.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

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

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

```bash
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](LICENSE).