Repository navigation
Description
Problem or use case
Orca already computes per-provider usage for Claude, Codex, Gemini, OpenCode Go, Kimi, MiniMax, Antigravity and Grok, with per-window percentages, reset times and the 80% warning chip. None of it is reachable from outside the app. orca account list --json returns the accounts themselves, not what is left on them, and there is no orca usage equivalent.
Anything running beside Orca has to rebuild that knowledge from scratch, one fetcher per provider, from sources of very different quality:
| Provider | What an external tool has to read | Quality |
|---|---|---|
| OpenCode Go | GET https://opencode.ai/zen/go/v1/usage |
exact, live, rolling/weekly/monthly with resetsAt |
| Codex | the rate_limits block in the newest ~/.codex/sessions/**/rollout-*.jsonl |
exact, but only written when Codex actually runs, so a lower bound (related: #11538) |
| Claude Code | nothing cached; token counts have to be reconstructed from ~/.claude/projects/**/*.jsonl |
estimate only |
Concrete cases this blocks:
- An orchestration script deciding which
--agentto pass toworker-startwhen one plan is near its weekly wall and another has just reset. - A dispatcher that wants to stop handing work to a provider at 90% and resume after its reset, rather than discovering the wall by failing.
- Any dashboard or status tool outside the Orca window.
Proposed solution
Expose what the status bar already knows, over the CLI and the RPC surface:
orca usage [--provider <id>] [--account <id>] [--json]
Returning, per provider and account, one row per window:
{
"provider": "codex",
"account": "acct_...",
"buckets": [
{
"id": "weekly",
"window_minutes": 10080,
"used_percent": 93.0,
"resets_at": "2026-09-21T19:26:23Z",
"freshness": "stale",
"observed_at": "2026-09-20T07:39:09Z"
}
]
}The freshness field matters as much as the number. live for a provider Orca can query on demand, stale with an observed_at for one that is only refreshed when the agent runs (Codex today), and unknown when a provider has no usable source. An external consumer can then treat an exact number and an estimate differently, which is the difference between spending a bucket down to a thin reserve and not being able to spend it at all.
Shape and flags to match the existing orca account list --json, so nothing new has to be learned.
Alternatives or additional context
The workaround today is for each external tool to write its own probe per provider, which is what I currently do. It duplicates work Orca has already done, it drifts every time a provider changes an endpoint, and it cannot see Orca's managed per-account homes at all, so it gets the host total rather than the account that a given pane will actually use.
This also compounds well with the provider-coverage issues already open (#18506 Z.ai, #20812 Fireworks, #21476 OpenRouter/TokenRouter/Ollama Cloud, #15516 Cursor, #19224 MuseCode): each one lands once inside Orca and becomes available to external tooling at the same time, instead of every consumer implementing the same fetcher again.
It is also the missing input for #20512. Automatic failover needs a policy, and a policy needs readable numbers; exposing the numbers is the smaller, more generally useful half and can land independently.
Activity
karoliang commentedon Sep 20, 2026
Update with a finding that narrows this request, from building the outside-Orca version.
Codex itself already answers most of what I asked for here, without Orca:
codex app-server→account/rateLimits/readreturns live percentages, window length, reset time and theaccountIdthey belong to, in about 0.74 seconds and with no interactive session needed.{"rateLimits":{"primary":{"usedPercent":7,"windowDurationMins":10080,"resetsAt":1790480193}, "planType":"pro"},"accountId":"e81eb3ba-..."}That matters for this issue in two ways.
The freshness field I asked for is only needed where a reading cannot be refreshed. With this endpoint the Codex number stops ageing between sessions, so the
stalemarker I wanted is no longer needed for Codex at all. It is still needed for Claude Code, whose usage can only be reconstructed from transcripts and is an estimate however recently you read it. The general principle survives: a payload should say how good each number is, because an estimate that reads like a measurement is the dangerous kind, and an old high reading removes a provider that may already have reset.Attribution is the part Orca is still uniquely placed to give. Per the discussion on #20512, Orca hardlinks session files across account homes — confirmed here even with a single account, where one rollout has
nlink=2and shares an inode with the copy under~/.codex. So a file-based reading cannot be attributed to an account, and the per-account homes are an Orca concept an outside tool has to discover by convention.orca account list --jsonreturning a reading per account, each carrying its own identity, is still the thing nothing else can provide.So the narrowed ask: per-account identity and the quality of each reading, rather than the raw numbers, which for Codex are already reachable.