The JSON format a usage command prints so byre's Status tab shows a vendor's usage and limits, and how to set one.

# Usage commands

byre shows each vendor's (claude, codex, antigravity) usage and limits in the Status tab. By default it uses what the vendor itself reports. A usage command replaces that for one vendor: a shell command that prints the numbers in a vendor-neutral format, so byre needn't know where they come from.

## Contract

- byre runs it with `$SHELL -l -c '<command>'` in byre's own environment (no task's worktree or `$PORT`), at startup, after every turn of that vendor's agents ends, and when the command is saved. One run at a time per vendor.
- It must finish within 10 seconds, print one JSON object to stdout and exit 0. On a non-zero exit, a timeout or output that doesn't parse, byre shows nothing for that vendor.
- Every field is optional. Unknown fields are ignored. No field names a vendor.

```json
{
  "updated_at": "2026-10-19T21:24:56Z",
  "rejected": "daily budget spent",
  "windows": [
    {
      "label": "Today",
      "used": 150.94,
      "limit": 200,
      "unit": "usd",
      "resets_at": "2026-10-20T12:00:00Z",
      "window_seconds": 86400
    },
    {
      "label": "Rate",
      "used": 36,
      "limit": 40,
      "unit": "requests",
      "resets_in_seconds": 240
    }
  ]
}
```

| Field | Meaning |
|---|---|
| `updated_at` | RFC 3339 time the numbers were current; now when absent. |
| `rejected` | Why the vendor is refusing work; absent while it isn't. A window whose `used` reaches its `limit` also shows the vendor as rejected. |
| `windows[]` | Independent meters, shown in order. |
| `label` | Short name for the meter. |
| `used`, `limit` | Numbers in `unit`. A window without `limit` shows as a bare count. |
| `unit` | `usd`, `tokens`, `requests` or `percent`; selects formatting. |
| `resets_at` | RFC 3339 time the meter resets. |
| `resets_in_seconds` | Alternative to `resets_at`, relative to `updated_at`. |
| `window_seconds` | The window's length; with `resets_at`, it draws the pace bar of time elapsed against amount used. |

Status shows the example as `Today  $150.94 / $200.00 · 75%  … in 14h 35m` and `Rate  36 / 40 requests · 90%  … in 4m`.

## Setting one

The human sets it in the app: Server tab, Usage commands, one field per vendor; empty uses the vendor's own reports. The same is `PUT /api/admin/usage-commands` with `{"claude": "...", "codex": "...", "antigravity": "..."}` (all three; `GET` reads them). Test a command by running it by hand and checking its output parses as above.