Jigsaw
grok-budget-mcp is one piece of a growing family of projects, big and small. Here is how the pieces fit together, as seen from this one.
grok-budget-mcp you are here
A small local MCP server that tells a Grok Build agent how much of its weekly usage pool is left, the same figure as /usage. Read-only, unofficial endpoint.
Fregoli possible user
A web application an agent can rewrite while it is running: capabilities are Cordis plugins mounted and unmounted in a live Node process.
A web app whose agent could ask this gauge about its budget. Fregoli runs the Grok CLI as its in-app agent, and Grok can load extra MCP servers from its own config, so the agent could call get_budget before expensive work, stop when the weekly pool is empty, or warn the user. This is a possible use, not built or tested yet.
Hermetarium possible habitat
The world an agent wakes up in: an OCI image it may use freely as root, behind a wall with Squid as the only, logged way out.
A house this gauge could serve in two ways; neither is built or tested yet. Inside a habitat: a Grok Build inhabitant could load the server and ask about its own budget. The image would hold only a placeholder auth.json, and Squid would add the real grok login token from the host-side ACL, the way Hermetarium already injects vendor keys; the billing route would need its own ACL entry, and the token is short-lived, so it needs renewing. Next to the supervisor: a watching agent on the host could call get_budget, send a habitat to sleep while the weekly pool is empty and wake it after period_end. Hermetarium has no such sleep and wake yet, only create and destroy, and keeping a changed world is not implemented (the spec leaves it open).
claude-budget-mcp sister
A small local MCP server that tells a Claude Code agent how much of its 5-hour and weekly usage limits is left, the same figures as /usage. Read-only, unofficial endpoint.
The younger sister, the same kind of gauge for Claude Code. It reads Claude Code’s own login file, never renews it, and reports the 5-hour session window and the weekly window instead of one weekly pool. The code layout, error codes and release process follow this one, so a fix in one is usually worth checking in the other.
Git Warden kin
Guard posts between AI agents and their Git remote: a Push Guard that checks every push with deterministic rules, and a Backup Guard that keeps an append-only backup of every branch and tag.
A fellow piece of the same puzzle; no direct connection yet.