Repository navigation
feat(FIX-2142): show Claude Code usage left, from its runs - #3795
Conversation
Claude Code's rate_limit_event windows reach the per-user usage record through a new onUsage hook on claudeCodeAgent, fed by the harness manager and the session door. readClaudeUsage adds the account and plan. Windows gain a nullable usedPercent and a level; the record gains accountAt. The writer also folds in the three Codex findings open on the spec at merge. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG
|
The latest updates on your projects. Learn more about Vercel for GitHub. 3 Skipped Deployments
|
|
@codex review Please look hardest at:
Generated by Claude Code |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Second look + architecture pass (FIX-2142)Reviewed the code against the approved spec, not the direction. Two findings are worth acting on and the rest are notes. Nothing here re-opens a spec decision. 1. Real bug: a slow or failed
|
There was a problem hiding this comment.
Simplify pass (FIX-2142)
Verdict: The dual path (on-demand readClaudeUsage for account/plan + run-time onUsage for rate_limit_event windows) is the right shape for this vendor surface, not an over-built fork of Codex. Codex can fill HarnessUsageReading.windows from account/rateLimits/read; Claude has no sanctioned off-run percent API in this stack, so pushing merge semantics into harness-usage and a fourth HarnessFeeds hook is load-bearing. The goal controls (read-replaces-run, absent-as-zero, fan-out) make that case: simpler policies fail the product bar.
Where the weight is: Most new complexity sits in applyReading / applyRunWindow (account rebind, runStartedAt vs checkedAt, keeping run windows across refresh). That is hard to read, but it is tested and documented; I would not collapse it without dropping requirements.
Simpler approaches that do not fit (unless product changes):
- Polling-only / reader-only for Claude → Usage stays empty until someone runs work and hits limits.
- Claude-only sidecar storage → duplicates the shared
harnessUsagequery or leaves Claude off the same screen as Codex. - A third-party rate-limit library → does not replace the store-backed refresh claim without losing cross-host throttle semantics.
Low-cost simplifications worth considering (none blocking): optional onUsage on HarnessFeeds (docs already say harnesses that report nothing ignore it), tighten origin to an enum, align Claude reader registration with Codex by threading signal, and reduce shift-manager DTO drift (see inline).
No performance concerns at expected rate_limit_event frequency; awaiting onUsage on the SDK loop is intentional so writes cannot land after the run ends.
Approving directionally — merge logic is the main long-term maintenance cost, and the tests/docs are the right mitigation.
Sent by Cursor Automation: Review For Best Approach
There was a problem hiding this comment.
Code Snob — already tight on 6351a16. No POC.
I read packages/harness-manager/src/harness-usage.ts (accountStep, applyReading, applyRunWindow, recordHarnessUsage), packages/claude-code/src/sdk/usage.ts, the rate_limit_event branch and accountOf in packages/claude-code/src/sdk/agent.ts, HarnessUsageWindow / HarnessUsageReport in packages/core/src/types/harness.ts, windowsOf in packages/codex/src/usage.ts, levelLabel and Usage.tsx, the manager and session-door onUsage feeds, claudeCodeHarness (it already spreads feeds), the goal (run.mts, controls.mts, lab/scripted-sdk.mjs, lab/fsdev.config.mts), and the writer tests.
A rewrite does not shrink the contract:
accountStepis the one comparison both writers share. Inlining repeats the null-account rule. A helper that also hashes is the same length.- The run-window keep is one line (
read-replaces-runpatches it). AMapchanges window order. FoldingapplyRunWindow's two scans saves about a line. - The
recordHarnessUsageoverload is shorter than a second writer plus a shared compare-and-swap. The four-argument form is the existing call. - The two
onUsagefeeds are the same call with different reasons (a replaced attempt is still a true reading; a talk writes the person talking). One shared feed drops the second. accountOfis the 5s cap on the query this run already holds. Inlining it into the message loop is longer.WINDOW_MINUTESnames the ids that have a length. Aseven_dayprefix would lengthen an id the table leaves unlabeled.levelLabelis the three words. The card shows words when the level isreachedor there is no percent, and the percent otherwise.claudeCodeHarnessalready spreads the feeds, and the two goals pass them through whole.HarnessFeedsextends the manager's.- The unit test's
resolveClaudeAgentand the goal's SDK module seam are two fakes. Folding them hides the load path the goal grades. applyReadingandapplyRunWindowstay off the package index. The ordering cases call them so each one does not boot a flow.
The long notes are the rules the names do not carry: a null account rebinds either way, accountAt moves on every taken write, a no-number look older than accountAt is refused, and a run lifts api-key only when it started after that look. I left the recorded calls (one-decimal percent, utilization above 1 dropped, the fsd reader, required onUsage, the scripted seam).
Sent by Cursor Automation: Code Snob
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6351a16aa9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The usage reader now threads its abort signal through probeClaudeAccount and the idle query, so a refresh that gives up closes Claude Code instead of leaving it waiting out the probe's timeout. HarnessFeeds.onUsage is a new required field, so harness-manager's bump is minor. Stored window origin is an enum, and Shift Manager's usage level reuses core's type. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG
|
@codex review This is on 3d82a64. Please check the new abort path in Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3d82a64dc4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
… read A probe that times out, is aborted or throws now marks its none as unanswered, and readClaudeUsage reads that as unavailable, so a failed refresh keeps the last good reading instead of clearing it as signed-out. A run whose account lookup fails drops that window rather than record it under a null account, which would rebind the row. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG
|
@codex review This is on 6db241a. Please check the new "unknown account" path:
Generated by Claude Code |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
@codex review The last run on 6db241a failed on Codex's side. Same focus as before: the unknown-account path in Generated by Claude Code |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
…to claude/project-thread-3x3z3h # Conflicts: # packages/codex/src/usage.ts # packages/core/src/types/harness.ts # packages/shift-manager/src/lib/usage.ts # packages/shift-manager/test/usage.test.ts
|
Test (2/3) failed on 6db241a in Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7728056c83
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
An unavailable reading kept the stored record only once a look had set checkedAt, so a run's windows written before any look were cleared by a failed first refresh. It now keeps any record that holds something. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG
…to claude/project-thread-3x3z3h
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG
|
@codex review Both round-3 P2s are fixed (0eeb790, cb079fc), and base 394d8ae is merged in. Please look closely at the ordering rules in Generated by Claude Code |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb079fcaaa
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…on an unanswered look Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KAhoCzQzu8TK82zvC4anTG


Requested by Jake · project thread
The problem
A person running Shift Manager on a Claude subscription can't see how close Claude Code is to its 5-hour or weekly limit. They find out when a run stops. The Usage view from FIX-2141 shows Codex only.
What this does
Usage gets a Claude Code card. Each window a run reported shows its limit, its reset time, and how close it is. That is a percent when Claude Code sent one (it sends one only near a limit) and otherwise words: "under Claude Code's warning line", "near its limit", "limit reached". The card says the window came "from a run, X ago". An API-key or signed-out Claude Code says so, with no window.
The windows come from the
rate_limit_events Claude Code sends during a run.claudeCodeAgenttakes a newonUsagehook, and the harness manager and the session door both pass one that writes into the same per-user usage record as Codex. Looking at Usage asks who is signed in (readClaudeUsage) and adds the plan, but no windows, because no allowed source gives a percent without a run. Nothing reads a credentials file, calls a usage endpoint, or uses the SDK's experimental usage call.What's asked of you
Nothing new: this implements the approved spec (
specs/issues/FIX-2142/). Three Codex findings on the spec were still open when it merged. All three are fixed in the writer (see Engineering calls), and one of them changes a rule the spec stated. It makes the writer more conservative, so there's nothing to approve beyond reading it.Leg g is owed by a person. No CI has a Claude sign-in. Until you run a real coding task on your own Claude subscription and compare Usage with Claude Code's
/status, the verdict is goal met except leg g.Parts worth reviewing closely
packages/harness-manager/src/harness-usage.ts:applyReadingandapplyRunWindow(pure), which shareaccountStep. These cover account rebinds,accountAtordering, and when a run may lift a no-number status.packages/claude-code/src/sdk/agent.ts: therate_limit_eventbranch. The account is asked once per run (accountInfo(), 5 s cap). The hook is awaited and tracked, a throw is logged and the run carries on, and it is not fenced byinSessionOnly.goals/shift-manager/it-shows-claude-usage-left/: the scripted SDK seam, and leg d's talk through the session door.FIX-2142 · epic FIX-2139 · spec #3771 (merged) · stacked on #3768 (FIX-2141) · merges when approved
How to review this
Engineering calls
The three Codex findings open at the spec's merge (#3771, commit e465664) are fixed here, with unit tests in
harness-usage.spec.ts:nullaccount counts as an identity of its own, so any change of account, in either direction, clears the windows and the plan. This replaces the spec's "a reading with no account keeps the stored one". It is the conservative side of the same rule the spec applied to null-to-named.accountAtadvances on every accepted write, not only on a rebind, so the A→B(stalled)→A ordering can't let the late B win.accountAtis refused, so a delayedapi-keyorsigned-outlook can't clear a newer run's window. A run write advancesaccountAtto its observed time.Other calls:
usedPercentis rounded to one decimal place (0.29 → 29, not 28.999…). Autilizationabove 1 is not a fraction and is dropped. An event with norateLimitType(an API-key run) writes nothing.five_houris 300 minutes, and everyseven_day*is 10 080. Any other id has no length and is labelled by its id.fsdprofile gets theclaude-codereader too (teams/devteam/fsd.fsdev.config.mts). The spec named only the devteam config, but the profile already serves Usage, so leaving it out would show Claude Code as "not checked yet" there forever.lab/scripted-sdk.mjsreplaces@anthropic-ai/claude-agent-sdkthrough the goals' module patch. It answers runs with per-status event fixtures, in the shape the pinned CLI (0.3.234) builds, and passes the account probe through to the real SDK for the empty-home and API-key looks.HarnessFeeds.onUsageis required, like the other feeds. DevTeam's harness stub, and the two goals that wrapclaudeCodeHarness, now pass the feeds through whole.Everything else
Verification (local, on this head's content):
Goal check
goals/shift-manager/it-shows-claude-usage-left/run.mts: PASS on legs a–f in 97 s, with g owed. Each control FAILs where it must:no-scale→ b:91 (0.91%)absent-as-zero→ a:no-number (0%)fan-out→ d:no-claude-windowread-replaces-run→ e:keeps-the-runs-windowThe verdict table is in
goal.md.The Codex goal (
it-shows-codex-usage-left) still PASSes over the reworked writer. Its five controls were re-pointed at the writer's new lines, and each still fails on its own assertion.Tests:
@flow-state-dev/core2519@flow-state-dev/claude-code348, including the newtest/sdk/usage.spec.ts@flow-state-dev/harness-manager287 (harness-usage.spec.tsnow 22)@flow-state-dev/codex109@flow-state-dev/shift-manager566 (usage.test.tsgainslevelLabel).command.test.tsfails locally on the base branch too, because the pages are not built here.pnpm typecheck,check-retired-termsandcheck-new-dead-codePASS.Docs were written by the docs-writer pass, and a separate docs-editor pass checked them against the source. The docs site builds.
Files
packages/core/src/types/harness.ts:usedPercentis nullable.levelis new; the schema defaults it to null, so stored Codex rows still parse.HarnessUsageReportandHarnessUsageHook.packages/claude-code/src/sdk/usage.ts(new):usageWindowOf,readClaudeUsage,CLAUDE_CODE_HARNESS. Alsoagent.ts(onUsage) andtypes.ts.packages/harness-manager:harness-usage.ts:accountAt, the run-window writer, and therecordHarnessUsage(ctx, report)overload.manager.ts:HarnessFeeds.onUsage, the collection installed, and a reserved accessor.session-door.ts: the same feed and collection.packages/codex/src/usage.ts: windows getlevel: null.packages/shift-manager:claude-codereader in both configs.Generated by Claude Code