Home widget for Grok and Codex subscription usage
- Dominant language
- TypeScript
- Stars
- 909
- Forks
- 116
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 156
Description
### Before filing
- [x] I searched [open and closed issues](https://github.com/block/berd/issues?q=is%3Aissue) for duplicates.
- [x] I am using a recent [release](https://github.com/block/berd/releases) and this doesn't already exist.
- [x] This is one request, not several bundled together.
### Closest existing issue
none found. #141 is the nearest usage-related report, but that is the composer context-window tooltip, not subscription / plan quota. #143 is about keeping the Home board visible while chatting, not about a usage widget.
### Is this new, or an improvement?
New capability — Berd can't do this at all today
### The problem, in your terms
I use Grok (SuperGrok weekly limit) and Codex / ChatGPT in Berd, and I have to leave the app to see how much of each subscription is left. The numbers I care about live on grok.com Usage and chatgpt.com/codex/settings/usage: percent used, a progress bar, and the reset time. By the time I remember to check, I have already burned a chunk of the week.
Home is the place I already glance at. I want remaining quota there, next to the chats and agents I already pin, without opening a browser.
### What you do today
Open grok.com Usage and the Codex / ChatGPT usage page in a browser. There is no in-app surface for this on Berd 0.6.2.
I also checked the official CLIs I already have signed in:
- `grok usage` / `grok quota` / `grok billing` are not CLI commands. Grok's `/usage` (alias `/cost`) is an in-TUI slash command. Headless `grok -p "/usage show"` treats it as a normal prompt and does not return the SuperGrok weekly limit.
- `codex usage` is not a CLI command either. Codex's `/usage` is TUI-only.
So I cannot honestly schedule an automation that fetches live subscription usage.
### What you'd like to see
A first-class Home canvas widget that shows live model-subscription usage for connected providers, starting with Grok and Codex / ChatGPT.
Useful v1 fields:
- Provider / plan name (for example Weekly SuperGrok Limit, Codex / ChatGPT)
- Percent used and a progress bar
- Reset time
- Optional secondary line (for example “Grok Build 18%”)
- Stale / signed-out / unavailable states instead of a fake 0%
Clicking the widget should open the provider’s official usage page, or a Berd settings/provider surface if one exists later. Refresh on Home focus and on a modest interval, with a last-updated time.
If a provider has no official usage API yet, show “Usage unavailable” plus a link, not a guessed number.
### Why this belongs in Berd itself
Home widgets are a closed catalog (`clock`, `stickyNote`, `checklist`, `photo`, plus pins for agents, chats, projects, automations, and skills). A skill is a `SKILL.md` instruction pack; pinning one only adds a clickable pill. It cannot draw a live usage bar.
An `automationOutputPin` can only show the last run’s text summary, and only if some official command actually returns usage. That is not true for Grok or Codex today, and a text card would go stale between runs anyway.
Scraping grok.com / ChatGPT or replaying stored login tokens against undocumented endpoints is not a good product path. This needs a first-class widget that talks to official provider usage APIs, or waits until those CLIs ship a supported command.
### Non-goals
- Not asking Berd to redeem / purchase / reset usage from Home.
- Not asking for a generic “any website” embed or MCP app as the answer.
- Not asking a skill or automation to fake live quota by scraping.
- Not asking for per-chat token accounting (that is closer to #141).
- Not asking to change the Grok or Codex CLIs in this issue.
### Alternatives you considered
- **Skill.** Rejected. Skills cannot render on Home.
- **Scheduled automation, then pin it.** Rejected for now. No official CLI/API returns SuperGrok or Codex subscription usage. The pin would be empty, guessed, or scraped.
- **Keep checking the browser.** Works, but it is exactly the glance I want on Home.
### Mockups, prior art, or other context
Berd 0.6.2 on macOS (Apple Silicon). Public build; in-app Feedback is not shown (`berdctl feedback` is also missing from this CLI), so filing here.
The Grok web Usage panel I want to mirror on Home shows:
- Weekly SuperGrok Limit
- `18% used`
- Reset date/time
- Breakdown row: `Grok Build 18%`
- A separate Redeem card, which I do **not** want on Home
Contributor guide
Research direction
Start by reviewing the Home canvas widget catalog and the existing provider or settings surfaces, then verify whether Grok or Codex exposes an official usage API. Define the supported data and unavailable states before implementation; done means a Home widget can show provider, quota, reset time, refresh status, and an official usage link without scraping or guessing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- desktop
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100