ClaudeDo/docs/explore-notes/usage-monitoring.md

# Usage monitoring, gate & throttle

> **Explore-note — verify before trusting.** Distilled map of a subsystem, not authoritative.
> Last verified against commit `bf56cd8c` (2026-08-24).
> Drift check: `git log --oneline bf56cd8c..HEAD -- src/ClaudeDo.Worker/Usage src/ClaudeDo.Worker/Queue src/ClaudeDo.Ui/ViewModels/UsagePillViewModel.cs`
> Stable structure only (no line numbers). See docs/explore-notes/README.md.

Covers `src/ClaudeDo.Worker/Usage/`, the queue's throttle/gate integration, per-run token
accounting, and the UI surfaces (usage pill + usage monitor modal).

**Two independent data sources, on purpose.** Limits/gate/throttle come from the OAuth poll
below; the *analytics* (per-model and per-task breakdown, cost) come from the external
TokenTracker CLI. Neither one can break the other.

## Data source (limits, gate, throttle)

`GET https://api.anthropic.com/api/oauth/usage` — an **undocumented** Anthropic endpoint,
authenticated with the Bearer access token Claude Code itself keeps fresh at
`~/.claude/.credentials.json`. ClaudeDo reads that token, never refreshes it, never logs it.

Because the endpoint is undocumented and can change without notice, **every consumer
fails open**. That is the single most important invariant here.

## Components (`Usage/`)

| Type | Role |
|---|---|
| `UsageModels` | `UsageBucket` / `UsageLimitRow` / `UsageSnapshot`. `UsageBucket.Utilization` is already a 0–100 percent — compare directly against thresholds, don't rescale. |
| `ClaudeOAuthUsageClient` | Reads the token, calls the endpoint. Defensive parsing: missing/null buckets → null, missing `limits` → empty list. |
| `UsageState` | Threadsafe singleton. A failed poll **never** overwrites the last good snapshot — it only sets `LastError`. |
| `UsageMonitorService` | `BackgroundService`; polls on `usage_poll_interval_seconds` (default 60, clamped to min 15 on config load), one poll at startup. Logs a failure at most once per distinct error message. Broadcasts `HubBroadcaster.UsageUpdated` after **every** tick, success or failure. |
| `UsageSnapshotBuilder` | Builds the Hub-facing `UsageSnapshotDto` from `UsageState` + `IUsageGate` + `AppSettings`. The one shared place for stale/threshold/gate logic — `WorkerHub.GetUsageSnapshot` and `UsageMonitorService` must not diverge. |
| `UsageGate` | Hard pause decision → `UsageGateDecision(IsBlocked, Reason)`. |
| `UsageThrottle` | Pure static staging of parallelism ahead of the gate. |
| `TranscriptUsageReader` | Reads **one** session's cumulative totals for per-run accounting. **No** aggregation — the date/model/scope roll-up moved to `TokenTracker/`. |
| `TokenTracker/` | The external analytics backend: cost + per-model/per-task breakdown. Own section below. |

Interfaces in `Usage/Interfaces/`: `IUsageClient`, `ITranscriptUsageReader`, `IUsageGate`;
plus `Usage/TokenTracker/Interfaces/ITokenTrackerClient`.

## The gate (hard pause)

Thresholds: `AppSettings.UsageGateFiveHourPct` / `UsageGateSevenDayPct` (defaults 80/90).
Blocked once `five_hour >= UsageGateFiveHourPct` **or** `seven_day >= UsageGateSevenDayPct`
(`>=`, not `>`). Threshold `0` = that bucket never gates.

What it pauses: **only the queue's slot-fill loop** — new queued tasks don't start.
Unaffected: already-running runs, `RunNow`, `ContinueTask`, interactive ConPTY sessions,
planning sessions, daily prep (all bypass the queue).

**Fail-open**: no snapshot yet, a failed last poll, or an app-settings read error all
resolve to not-blocked.

There is **no persistent pause state**. Recovery is just the queue's 30 s backstop timer
(`queue_backstop_interval_ms`) re-evaluating the gate on its own once usage drops back
under the threshold. A blocked↔free transition is logged and broadcast (`WorkerLog`, Warn
on block / Info on resume) exactly **once per change**, not every tick.

## The throttle (staged parallelism)

`UsageThrottle.EffectiveSlots(configuredSlots, fiveHourPct, fiveHourThresholds, sevenDayPct,
sevenDayThresholds)` — pure static, no state. `UsageThresholds(SoftPct, HardPct, GatePct)` is the
per-bucket triple (same file).

Thresholds are **per bucket** (`usage_throttle_five_hour_{soft,hard}_pct` /
`usage_throttle_seven_day_{soft,hard}_pct`, defaults 50/65 each) because the 5h and 7d windows fill
at very different rates. Each bucket is staged independently and the **strictest** bucket wins —
not "whichever is more utilized", so a bucket that is lower but tightly configured can be the one
that throttles:

| Utilization (per bucket) | That bucket's slots |
|---|---|
| below soft | full configured `max_parallel_executions` |
| `>= softPct` | capped at 2 |
| `>= hardPct` | capped at 1 |
| `>= gatePct` | 0 — same hard block as `UsageGate` |

A threshold of `0` disables that stage for that bucket, and a bucket with no reading (null) never
throttles. The `0` return is deliberately kept in sync with `UsageGate`'s hard block because both
read the same gate thresholds — change one, change both.

Only **new** slot fills are affected; a run already occupying a slot when the stage tightens
runs to completion. Same fail-open policy: no snapshot means no throttling.

The effective stage (configured vs. effective slots + the decisive bucket, `ThrottleBucket`
= `"five_hour"` / `"seven_day"`) rides along on `UsageSnapshotDto` purely for UI display.
It does **not** change what the gate gates on.

## Queue integration (`Queue/QueueService`)

Per loop tick:

1. `GetEffectiveMaxParallelAsync` reads `AppSettings.MaxParallelExecutions` and steps it
   down via `UsageThrottle.EffectiveSlots` against the current `UsageState` snapshot.
   A missing/failed snapshot fails open to the configured value. A **stage change** (not
   every tick) logs once.
2. Separately, `IUsageGate.EvaluateAsync` — if blocked, the slot-fill loop is skipped
   entirely for that tick.

## Per-run token accounting

`task_runs` stores four raw token fields: `tokens_in` / `tokens_out` /
`cache_read_tokens` / `cache_write_tokens`.

These are **not** read from the stream-json `result` event's `usage.input_tokens` — that is
only the uncached remainder of a single API call and undercounts the real prompt size by
orders of magnitude once caching kicks in.

Instead `TaskRunner.ApplyUsageAsync` calls
`ITranscriptUsageReader.ReadSessionTotalsAsync(sessionId)` — the session transcript's
cumulative raw totals across every assistant message, located by `{sessionId}.jsonl` — and
stores the **delta** against prior `task_runs` rows sharing the same `session_id`, so a
`--resume`'d run doesn't double-count turns already billed to an earlier run.

A missing/unreadable transcript leaves all four fields `null`; it never fails the run.

`ReadSessionTotalsAsync` **stays** — it is the per-run source of truth and is deliberately *not*
routed through TokenTracker, whose export has no per-run granularity (it aggregates a whole
session, which a `--resume`'d task spreads over several runs).

### `TranscriptUsageReader` details

Locates a single `{sessionId}.jsonl` under `~/.claude/projects/**`, sums the raw `usage` fields of
every assistant message, deduped by `requestId` (falling back to `message.id`), with a per-file
length+mtime cache. `<synthetic>`-model lines are skipped — they are not real API calls.

There is no history-wide `ReadAsync` any more; `WorkerConfig` is still a constructor parameter
purely so the DI registration and call sites stayed untouched.

## Analytics via TokenTracker

The per-model / per-task / cost view comes from **TokenTracker**, an external MIT-licensed CLI
(`tokentracker-cli`, npm) that reads the same local Claude transcripts. Everything lives in
`Usage/TokenTracker/`; the pure parts (`SessionHash`, `TokenTrackerArgs`,
`TokenTrackerExportParser`, `TokenTrackerAggregator`) have no I/O and are unit-tested, only
`TokenTrackerClient` (processes) and `TokenTrackerService` (cache coordination) touch the world.

- **Invocation:** `tokentracker sessions --from <d> --to <d> --no-git --format json`
  (`TokenTrackerArgs`). `--no-git` matters — without it TokenTracker runs `git log` inside every
  session's working directory. We **never** call `tokentracker init`: that would write hooks into
  the user's global `~/.claude/settings.json` and switch on cloud sync. Install is an explicit
  `npm i -g tokentracker-cli`, never `npx`. Resolution goes through the shared
  `ExecutableResolver` because an npm CLI is a `.cmd` shim.
- **The join:** the export never carries a raw session id, only `session_hash` =
  `sha256("claude\0" + sessionId)` hex, first 24 chars (`SessionHash.ForClaudeSession`,
  mirroring TokenTracker's `lib/session-analytics.js`). That hash set — built from
  `task_runs.session_id` — is also what decides the **ClaudeDo vs. other** scope split. Note this
  is *narrower* than the old cwd-based split: an interactive or planning session has no
  `task_runs` row and therefore counts as "other".
- **One wide fetch, local filtering:** `TokenTrackerService.WindowDays` = 90. TokenTracker's
  `buildSessionAnalytics` walks the whole history regardless of `--from`/`--to` (v0.88.4 returns
  the same rows either way), so narrowing the request buys nothing while making every range switch
  pay again. Range switching is then pure in-memory filtering in `TokenTrackerAggregator`.
- **Freshness:** `EnsureFreshAsync(maxAge)`. No export at all → the caller awaits the fetch;
  an export older than **15 minutes** → served immediately while a refresh runs behind the
  caller's back. `RefreshAsync` is single-flight (a second caller waits for the in-flight run
  instead of spawning another process). The probe (CLI present? Node ≥ 20?) is cached until an
  install forces it.
- **Version check:** the export's `version` field is compared against
  `TokenTrackerExportParser.SupportedFormatVersion` (11). A mismatch is treated as a **failure**
  — the state keeps the last good export and reports the version in `LastError`.
- **Fail-open everywhere:** `TokenTrackerState` mirrors `UsageState` — a failed or unparseable
  fetch never overwrites a good export, it only sets `LastError`. CLI missing → empty analytics
  plus a hint card in the UI. Nothing here can throw into the queue.
- **Local dashboard:** `tokentracker serve --port <p> --no-open --no-sync`, started by the worker on
  demand (`ITokenTrackerClient.StartDashboardAsync`) for the "Open TokenTracker dashboard" button.
  Three things this path has to get right: TokenTracker's default port **7680 is not free** on
  Windows (Delivery Optimization holds `[::]:7680`) and `serve` exits instead of falling back, so
  we scan 7680–7689 with a **dual-stack** bind probe (an IPv4-only probe calls 7680 free and the
  spawn then dies); `--no-open` because the CLI would open the browser before the server answers,
  so we poll `GET http://127.0.0.1:<p>/` (30 s cap) and let the **UI** open the URL; and the child
  is a `cmd.exe` shim, so shutdown kills the **process tree** or node keeps listening. The
  spawned server is reused while alive and dies with the worker (`TokenTrackerClient` is
  `IDisposable`, registered as a singleton) — a worker *crash* leaks it until the port is scanned
  past.
- **Limits, gate and throttle do *not* come from TokenTracker.** They are the OAuth poll above.
  A broken or absent TokenTracker costs you the cost columns, nothing else.

## UI surfaces

- **`UsagePillViewModel`** — one shared instance backs the `UsagePill` control in both the
  footer and the Mission Control header. Loads via `GetUsageSnapshotAsync`, updates live off
  `IWorkerClient.UsageUpdatedEvent`. Dot state priority is mutually exclusive:
  **blocked > stale > warn > normal**. `IsThrottled` (effective slots below configured, and
  not gate-blocked) adds a tooltip line naming effective/configured slots + decisive bucket.
  The pill's click handler (`IslandsShellViewModel.OpenUsageMonitor`) **shows the window before
  loading** (`BeginLoad`) — awaiting the load first made the pill feel like a dead click, because
  the first `GetModelUsage` per worker process scans the whole transcript history.
- **Draggable stage markers** — each of the two real gauges carries three markers (soft/hard/gate).
  `UsageGaugeBar` (`Views/Controls`) draws them against its own width and does the pointer work;
  the math is a pure static, `UsageThresholdDrag` (in the modal VM's file), which keeps
  soft ≤ hard ≤ gate and treats a neighbour of `0` as off. Release fires the row's
  `CommitCommand` → read-modify-write via `GetAppSettings` + `UpdateAppSettings`, so only the
  dragged bucket's three fields change. Plan-dependent `weekly_scoped` gauges are read-only.
- **Legend = numeric editor.** Under each adjustable bar sit three legend rows whose colour swatches
  match the markers (soft `TextDimBrush`, hard `StatusReviewBrush`, gate `StatusErrorBrush`), each
  with a `NumericUpDown`. `NumericUpDown` has no commit command, so the box's `Tag`
  (`soft`/`hard`/`gate`) plus two code-behind handlers (`LostFocus`, Enter) call the row's
  `CommitSoft`/`CommitHard`/`CommitGate` command. Those run the typed value through the **same**
  `UsageThresholdDrag.Apply` clamp as a drag, so a box can't invert the order and only the edited
  stage moves. ⚠️ The `KeepLastNumber` converter is mandatory on those bindings — see the
  `NumericUpDown` null gotcha in `src/ClaudeDo.Ui/CLAUDE.md`.
  Rows are updated **in place** on each snapshot (keyed by limit kind) so a poll landing mid-drag
  doesn't replace the bound instance.
- **`UsageMonitorModalViewModel`** — opened from the pill. Renders one gauge **per row** in
  `UsageSnapshotDto.Limits` — deliberately **dynamic**, because the `seven_day_opus` /
  `seven_day_sonnet`-style buckets the raw API returns are plan-dependent and come back
  `null` on plans that don't have them; a fixed gauge layout would break. Also shows model
  usage (`GetModelUsageAsync`, ClaudeDo-vs-Other split per model) and top-task usage
  (`GetTaskUsageAsync`) over a 7d/30d preset or custom range — both with a **cost** column, the
  task table additionally with retries.
- **Analytics header vs. hint card** — the modal shows exactly one of the two. With TokenTracker
  present: total tokens + total cost, a freshness stamp, a manual `RefreshAnalytics` button and an
  **Open TokenTracker dashboard** button (spinner while the server boots; everything this modal
  deliberately doesn't show lives there).
  Without it: a hint card explaining what TokenTracker is (local only, no `init`, no cloud sync)
  plus an `Install TokenTracker` button — which is hidden and replaced by a Node-version hint when
  Node < 20 or Node is missing, because the install would just fail. Install progress and every
  failure go through `ErrorReported` into the shell's footer log strip, not a private banner.

## Hub surface

- `GetUsageSnapshot() -> UsageSnapshotDto` — percentages/limits/`FetchedAtUtc` are null and
  `IsStale=true` when no snapshot has landed yet. `IsStale` also trips on a failed last poll
  or a snapshot older than 3× `usage_poll_interval_seconds`.
- `GetModelUsage(from, to)` — filters + aggregates the **cached TokenTracker export**
  (`TokenTrackerAggregator.ByModel`). Returns an empty list rather than throwing when TokenTracker
  is unconfigured or no export landed. `Sessions` replaced the old assistant-message count — the
  export has no message granularity.
- `GetTaskUsage(from, to)` — unchanged source: top consumers from `task_runs` joined to task/list,
  grouped per task. Null token columns count as **0**, never drop the row. `Model` comes from that
  task's most recent run. Sorted by total tokens descending, capped at 100. Cost/retries/
  productive/one-shot are an **enrichment** via the `session_hash` join — a missing export just
  leaves those columns empty, it never triggers a fetch (`GetModelUsage` is what does).
- `GetTokenTrackerStatus()` — probe + state, as `TokenTrackerStatusDto(Installed, Version, NodeOk,
  NodeVersion, LastFetchedUtc, LastError, FormatVersion, SessionCount)`. Never throws; an
  unconfigured worker comes back as not-installed with a reason.
- `RefreshTokenTracker()` — forces a fetch, then re-probes and returns the status.
- `OpenTokenTrackerDashboard()` — brings up the local dashboard server and returns
  `TokenTrackerDashboardDto(Ok, Url, Error)`; the UI opens the browser (`ShellOpen.Url`, which
  refuses anything that isn't http/https). Never throws — a failure also lands in `WorkerLog`.
- `InstallTokenTracker()` — `npm i -g tokentracker-cli`, streaming npm's output line by line into
  `WorkerLog` (npm writes progress to stderr; forwarding it is what keeps a multi-minute global
  install from looking hung), then force-re-probes.
- `UsageUpdated` event carries the same `UsageSnapshotDto`.

## Settings columns

`app_settings`: `usage_gate_five_hour_pct` / `usage_gate_seven_day_pct` (80/90),
`usage_throttle_five_hour_{soft,hard}_pct` / `usage_throttle_seven_day_{soft,hard}_pct` (50/65 per
bucket). All six clamped 0..100 by `AppSettingsRepository.UpdateAsync`, which does **not** enforce
soft ≤ hard ≤ gate — the ordering is a UI-side drag constraint, and an out-of-order stored config
degrades instead of throwing. Worker config: `usage_poll_interval_active_seconds` /
`usage_poll_interval_idle_seconds`.

The gate percentages are editable in **two** places that both write the same `app_settings` row:
Settings → General (typed) and the usage-monitor gauges (dragged). The throttle stages are
gauge-only — `SettingsModalViewModel` therefore carries them load→save verbatim so saving Settings
can't reset a dragged value.