One quota, five agents: the parallel-agent meter problem and the function that solves it

It is the same problem under two names. People say 'parallel sessions' when they mean N concurrent Claude Code processes (tmux panes, git worktrees, IDE plugins, MCP host loops) running against the same Claude account, and 'parallel agents' when those processes are wired into agentic loops. Either way the meter you want is the per-account server-side fraction, not a sum of per-process token counts. ClaudeMeter's dedupe_by_account in src/lib.rs collapses all those parallel session surfaces into one row keyed by account_email or org_uuid, and claude-meter --json prints the usage.five_hour.utilization every parallel session is racing to fill.

No. The rolling 5-hour window is one bucket per Claude account. Anthropic computes utilization on the server against your org_uuid, and every OAuth-authenticated client signed into that account adds to the same fraction. Five Claude Code agents in five tmux panes, three git worktrees, two browser tabs, the IDE plugin, and a Computer Use loop all stack into one five_hour.utilization number. You will hit the rolling wall at the same wall-clock minute regardless of how many parallel agents are racing toward it.

Per-account. seven_day_oauth_apps is a Window field on the JSON returned by GET https://claude.ai/api/organizations/{org_uuid}/usage. The qualifier is by authentication mode (OAuth-authenticated apps, which is how Claude Code, agentic CLIs, and MCP host loops sign in) not by client identity. Two parallel Claude Code agents are two OAuth apps as far as the auth flow is concerned, but they fold into the same seven_day_oauth_apps.utilization fraction because that bucket measures the subset of your account's plan usage that came from any OAuth-authenticated client. ClaudeMeter prints this field directly out of the snapshot returned by /api/organizations/{org}/usage.

No, and not because the tool is bad, because of where it reads. ccusage walks ~/.claude/projects/*.jsonl on disk and sums the inputTokens and outputTokens fields recorded in each transcript line. Each parallel agent writes its own JSONL, so ccusage will show you N per-session token totals, and you can sum them yourself, but the sum is a numerator with no denominator. The plan ceiling Anthropic enforces against does not exist on disk. ccusage at 12 percent and claude.ai at 91 percent is the predictable mismatch when several agents have been running for hours; the local count and the server fraction are two different measurements.

It does not need to merge agent-level usage; the server already did that work. What it does merge is multiple snapshot rows that point at the same Claude account. The function is dedupe_by_account in src/lib.rs of the m13v/claude-meter repo. It walks the Vec<UsageSnapshot> returned by the fetcher, keys on account_email (falling back to org_uuid when the email fetch failed), and folds duplicates into a single row whose browser field becomes a comma-separated list like 'Chrome, Arc'. The five_hour.utilization on that one row is the same fraction every parallel agent on that account is racing to fill.

Yes, because the extension is doing one job: keeping a fresh claude.ai session cookie reachable to the menu bar app via the localhost bridge at 127.0.0.1:63762. The terminal-side agents do not need their own extension. As long as one Chromium-family browser (Chrome, Arc, Brave, Edge) has the extension loaded and you have visited claude.ai once, the extension fires every minute (extension/background.js POLL_MINUTES = 1), POSTs the snapshot to the bridge, and the menu bar reflects the live percent for any number of headless tmux agents on that same account.

Then you get one snapshot row per account, not collapsed. dedupe_by_account is account-scoped: it merges entries that share an email or org uuid. Agents on account A and agents on account B will appear as two rows in claude-meter --json, each with its own five_hour.utilization, seven_day.utilization, and seven_day_oauth_apps.utilization. That is the right answer for the multi-tenant case. The menu bar app shows a row per account; the CLI prints them as an array.

claude-meter --json. The binary is at /Applications/ClaudeMeter.app/Contents/MacOS/claude-meter when installed via brew. Running it prints a Vec<UsageSnapshot>, each snapshot with org_uuid, browser, account_email, fetched_at, and three sub-objects: usage, overage, subscription. The fields a parallel-agent guard cares about are usage.five_hour.utilization, usage.five_hour.resets_at, usage.seven_day_oauth_apps.utilization, and overage.out_of_credits. The shape lives in src/models.rs (UsageResponse and Window structs). Pipe to jq, ingest in Python, parse in Rust; same numbers as the menu bar.

Because there is no published cap to divide by. The plan ceiling Anthropic enforces against is not a fixed token budget. It is a server-computed fraction with peak-hour multipliers, per-model weights, and (in 2026) explicit OAuth-app scoping that all happen on Anthropic's side. The same prompt run at 11 PM Pacific and at 11 AM Pacific does not move the local token total differently, but it moves the server fraction differently. A local divider produces a confident-looking percent that diverges from the 429-firing percent in ways the user cannot debug. The right number is the one Anthropic's own settings page reads, which is /api/organizations/{org_uuid}/usage.

The cadence is a 60-second poll. extension/background.js sets chrome.alarms with periodInMinutes: 1, fetches /api/account, /api/organizations/{org}/usage, /api/organizations/{org}/overage_spend_limit, /api/organizations/{org}/subscription_details, and POSTs the snapshot to 127.0.0.1:63762. The menu bar app applies the new percent on receipt. Sub-minute resolution is not the goal; the rolling 5-hour window does not move that fast for any reasonable parallel-agent setup, and a tighter cadence would burn quota of its own without the user seeing a meaningfully different number.

The 429 fires against the account, not against a specific agent. The sibling agent's next prompt also returns rate_limit_error from the same five_hour bucket because the bucket is shared. The right fix is to gate every parallel agent on the same shared signal before it sends, not to wait for each to discover the wall on its own. claude-meter --json once per iteration in each agent's loop reads the same number, so any agent over the threshold can sleep until usage.five_hour.resets_at instead of producing N broken half-completed tasks at 100 percent.