Plan usage is how much of each rate-limit window an account has used: the five-hour session window, the weekly windows, and so on. agentio has three ways to read it: CachedUsageReader reads the copy the vendor CLI left on disk (free, safe in a loop), UsageReader asks the vendor once (network, may 429), and SubscriptionReader reports the plan itself. All three return neutral types, so one status bar can show Claude Code and Codex side by side.
- Modules:
github.com/ubgo/agentio,github.com/ubgo/agentio/claude,github.com/ubgo/agentio/codex(orbuiltin). - Cached usage needs only the home on disk.
- Live usage and the Claude subscription need a logged-in, unexpired home and
Host.HTTP. In tests, point the Claude agent at anhttptestserver withclaude.New(h).WithBaseURL(srv.URL).
examples/usage copies the fixture homes into a temp dir, starts an in-process fake vendor API serving the recorded response shapes, and routes every request of its HTTP client to that server, so nothing leaves the process.
CachedUsage(home) returns (Usage, found, error). found is false when the vendor has not left a reading in that home; that is not an error. Claude keeps the last usage response in .claude.json; Codex records rate limits in its session transcripts.
// printCachedUsage reads the usage each vendor CLI left on disk: no network,
// safe in a loop. The reading is as old as the vendor's last refresh, so the
// age (Host clock minus ObservedAt) is part of the answer.
func printCachedUsage(w io.Writer, h agentio.Host, agents []agentio.Agent) error {
for _, a := range agents {
cu, ok := agentio.CachedUsageOf(a)
if !ok {
continue
}
homes, err := a.Homes()
if err != nil {
return err
}
for _, home := range homes {
u, found, err := cu.CachedUsage(home)
if err != nil {
return err
}
if !found {
fmt.Fprintf(w, "%s %s: no cached usage\n", a.ID(), home.Name())
continue
}
age := h.Now().Sub(u.ObservedAt).Round(time.Minute)
fmt.Fprintf(w, "%s %s: max %.0f%% source=%s age=%s\n", a.ID(), home.Name(), u.MaxPercent(), u.Source, age)
printWindows(w, u)
}
}
return nil
}Usage.ObservedAt is when the vendor fetched or recorded the reading, and Usage.Source says where it came from (cache, transcript). Show the age: a cached reading from two weeks ago is not today's usage.
Usage(ctx, home) makes one request with the home's stored login. It never refreshes a token: an expired login returns ErrExpired before any request is sent.
// printLiveUsage asks each vendor once for the default home's usage. This
// is a network read that may 429: call it on demand, cache the answer,
// never poll. An expired login is refused before any request.
func printLiveUsage(ctx context.Context, w io.Writer, agents []agentio.Agent) error {
for _, a := range agents {
ur, ok := agentio.UsageOf(a)
if !ok {
continue
}
u, err := ur.Usage(ctx, a.DefaultHome())
switch {
case errors.Is(err, agentio.ErrExpired):
fmt.Fprintf(w, "%s: login expired; run the vendor CLI once to refresh it\n", a.ID())
continue
case errors.Is(err, agentio.ErrRateLimited):
fmt.Fprintf(w, "%s: rate limited; keep the last reading\n", a.ID())
continue
case err != nil:
return err
}
fmt.Fprintf(w, "%s: max %.0f%% billing=%s source=%s\n", a.ID(), u.MaxPercent(), u.Billing, u.Source)
printWindows(w, u)
}
return nil
}The neutral agentio.Usage carries:
Windows []Window: each withLength(atime.Duration, 0 when the vendor does not say),Scope(a model or surface, "" for all usage),Label,Percent,ResetsAt(nil for no scheduled reset) andVendorKind(the raw kind, such asfive_hour).Window.Class(): aWindowClassderived fromLength(shortunder a day,day,week,month,unknownfor 0).MaxPercent(): the highest percent across windows; any window at 100% blocks the account.Billing:subscription,per-tokenorunknown.per-tokenmeans there are no windows at all: an answer, not a failure.Source:server,cache,transcriptorprobe.Rawkeeps the vendor body for vendor decoders such asclaude.ExtraUsageOf.
Subscription(ctx, home) returns the plan label and, where the vendor reports them, status, billing type and start date. Claude asks its profile endpoint (network); Codex answers from the claim in its stored login first and calls the network only when the claim is absent.
// printSubscriptions reads the plan of each default home. Claude asks the
// profile endpoint (network); Codex answers from the login on disk first.
func printSubscriptions(ctx context.Context, w io.Writer, agents []agentio.Agent) error {
for _, a := range agents {
sr, ok := agentio.SubscriptionOf(a)
if !ok {
continue
}
s, err := sr.Subscription(ctx, a.DefaultHome())
if err != nil {
return err
}
fmt.Fprintf(w, "%s: plan=%q status=%q billing-type=%q\n", a.ID(), s.Plan, s.Status, s.BillingType)
}
return nil
}cd examples && go run ./usageThe first three sections of the output:
== cached usage ==
claude personal: max 6% source=cache age=387h21m0s
Current session short 6.0% resets 2026-10-28T12:59:59Z
All models week 2.0% resets 2026-11-04T05:59:59Z
Fable week 0.0% resets 2026-11-04T06:00:00Z
claude work: no cached usage
codex personal: max 12% source=transcript age=722h0m0s
7d week 12.0% resets 2026-09-21T14:13:20Z
== live usage ==
claude: max 42% billing=subscription source=server
Current session short 42.0% resets 2026-11-13T15:00:00Z
All models week 18.0% resets 2026-11-18T09:00:00Z
codex: login expired; run the vendor CLI once to refresh it
== subscription ==
claude: plan="Max (20x)" status="active" billing-type="stripe_subscription"
codex: plan="Plus" status="" billing-type=""
The fixture's Codex login is expired, so live usage is refused locally; the Codex subscription still answers because it comes from the stored login.
- Never poll
Usage. It is a network read that may returnErrRateLimited(HTTP 429). Call it when the user asks, cache the result, and fall back toCachedUsagein loops and status lines.agentio.RateLimitErrorcarries the server's retry time when it sent one. - Expired is local, not a 401. An expired stored login returns
ErrExpiredwithout a request. The fix is to run the vendor CLI once in that home; agentio never refreshes a token because refreshing rotates the refresh token and logs the vendor CLI out. ErrNotLoggedIn,ErrUnauthorized,ErrScopeLimitedare the other answers to expect: no login, a rejected token, and (Claude) a token that lacks the profile scope. Match them witherrors.Is.- Cached readings can be very old. The example's Claude reading is 16 days old. Compare
ObservedAtwithHost.Now()before you call it "current". found == falseis not an error. A home that never fetched usage (the Claude work home here) has nothing cached.- Point both vendors at a test server with
WithBaseURL.claude.Agent.WithBaseURLandcodex.Agent.WithBaseURLreplace the API origin (codex.DefaultBaseURLishttps://chatgpt.com/backend-api), so a test passes anhttptestserver's client asHost.HTTPand its URL as the base, with no custom transport;examples/usagedoes this for both. - Window labels come from the vendor. Labels like
Fableor7dare whatever the vendor sent; group byClass()orLength, not by label.
- Logins and tokens: login commands, token logins and the token probe (the fourth way to read usage).
- Shared capabilities and accessors.
- Vendor pages: Claude usage (extra usage, rich limits), Claude account, Codex auth and usage.
- Errors for
ErrExpired,ErrRateLimitedand friends. - Choosing guides. Example:
examples/usage. Feature index: features.