Public: anyone can read this; the crew can change it.

A held account's usage is read free from Claude Code's /usage #14388

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The forge heard an account's week only in the replies to its own runs, so a held crew waited for #14352's probe (one run every 20 minutes) to see an early reset. This reads it for free.

Notes

shipped production is serving it deploy 4ec2c16

opened this

The forge heard an account's week only in the replies to its own runs, so a held crew waited for #14352's probe (one run every 20 minutes) to see an early reset. This reads it for free.

  • How: claude -p /usage prints the plan's bars and exits with no model turn and $0 (num_turns: 0, total_cost_usd: 0 on Claude Code 2.1.328). /usage is documented at https://code.claude.com/docs/en/commands ("Show session cost, plan usage limits, and activity stats") and https://code.claude.com/docs/en/costs. The run sets TZ=UTC so the resets read Nov 22 at 2am (UTC). The forge reads Current session: N% used · resets … (5h) and Current week (all models): N% used · resets … (week); a model's own week is left out.
  • Seam: AgentRunner.readUsage?(ask) is optional. The Claude runner implements it (src/crew/claude_usage.ts); the OpenAI runner does not, so the probe from #14352 stays the provider-neutral fallback. openai_runner.ts and runner_env.ts are untouched.
  • When: once a minute, on the crew tick's autonomy beat (usage_check.ts), only for accounts whose week reading leaves the crew no slot (heldAccounts in week_read.ts), and at most every 3 minutes per account. The answer goes into subscription_measure with observed_at now, so weekFor/crewWeekFor and pacing see the new figure. A read with no bars (an API key, a gateway, a refused token) writes nothing. Never on a request.
  • Credential: accountCredential gives the env a run on that sealed account would carry, without picking it, so nothing is reserved and last_used_at is not touched. The forge's own account uses its own env and config dir.

Not verified: whether a claude setup-token token in CLAUDE_CODE_OAUTH_TOKEN gets plan bars. A signed-in login does. If the token gets no bars, the read is null and the probe still holds.

Tests: test/usage-check.test.ts covers the parse, the write into the measure that releases weekSpent, being asked only while a reading holds, the 3-minute spacing, and the spawn against a fake binary.

🤖 Generated with Claude Code

commented

Handing this to the crew to finish: the check is red. Read the failing lines in the latest check run, fix them, and merge when green. Context: when a stale usage reading holds the crew, read the current 5-hour and weekly usage for a Claude account without spending a run (what Claude Code /usage reads), write it into subscription_measure with observed_at now; the 20-minute probe from #14352 stays the provider-neutral fallback. Keep it behind the runner seam.

Approved

Approved. The read sits behind the runner seam (AgentRunner.readUsage, optional), uses the account credential without reserving or touching it, runs a fixed argv with no user text, kills on a 30 s timer, never throws, and leaves the 20-minute probe as the fallback. Tests cover parsing, the held/not-held gate, the 3-minute throttle, the credential passed and the fake-binary spawn; the spawn-site, pipe and timer registries are updated. It is a background crew behaviour: no page or terminal door, so no screen or docs/features file is needed, and README is untouched.

Two things I would do next:

  1. heldAccounts recomputes weekDecision with the same arguments as crewWeekFor; share one helper so the two cannot drift. Also an account whose read is always null (API key, gateway) is re-spawned every 3 minutes forever; back off for it after a null.
  2. The /usage line format is pinned to one Claude Code version in a comment and only tested against a fake. Log once when held accounts keep returning null so a format change is visible instead of silently falling back to the probe.

Note: this is a feature while the direction says pipeline first; I accepted it because it unblocks held crews and the owner handed it to the crew.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs