Codeman/docs/usage-limits-display-plan.md

Plan Usage Limits Display — Design & As-Built

Status: SHIPPED. Deployed to prod + pushed to master, not yet released (2026-06-14). App Settings → Display → Plan Usage Limits (showPlanUsageLimits). Default changed in 1.9.3: desktop now defaults ON, handhelds stay OFF, resolved via planUsageChipEnabled(). The per-device notes further down describing it as opt-in/synced record the original 2026-06-14 shape, not current behavior. The exporter changed shape in 1.28 (discussion #405): it is now a self-selecting shell guard that runs a generated, delegating shim (src/statusline-shim.ts) where the shim exists and the inline curl below where it does not (inside a Docker case's container). The shim prints the statusline it shadows and falls back to the footer below only when there is nothing to shadow; with neither it prints nothing, and the route now answers an unknown session with an empty body, so the bare word codeman never renders. Turning the chip OFF now also removes the exporter from live workspaces (statusLineTelemetry:false, sent only on the save that flips the chip off on a device), so the "removal only via the toggle" sentences below are current again and the "never remove" ones record the 1.9-1.27 shape. See docs/architecture-invariants.md#plan-usage-chip-statusline-telemetry. Commits c82f6c8 (feature) → 4d9d93d (end-to-end fixes) → eae225b (per-user reconcile) → 95fb5fc (init-snapshot replay). Full suite green (2869), CI green. No changeset/version bump yet.

Two surfaces from one statusLine callback:

• Header chip (top-right) — account-wide plan limits: 5h 35% · 7d 38%, per-window green/yellow/red.
• In-terminal statusline footer — the current session's status: Opus 4.8 (1M context) in:562,411 out:1,188 ctx:56%.

The rate_limits JSON schema below was empirically confirmed against Claude Code 2.1.177 on a Claude Max account; see the Verification appendix to reproduce.

Problem

Codeman had no proactive view of how much of the Claude subscription is left. It only learned about limits reactively: usage-limit-patterns.ts regex-scrapes ANSI-stripped terminal output for footer strings like 5-hour limit reached ∙ resets 8pm, extracting only the reset time, and only after Claude has already stalled. There was no "73% of your 5-hour limit used" anywhere.

We wanted a live, always-visible gauge so the operator can see a wall coming and pace overnight/autonomous runs — without hijacking the in-terminal statusline, which should keep showing the current session's status.

Data source: the statusline rate_limits JSON

Claude Code (v2.1.80+; prod box runs 2.1.177) pipes a JSON blob to a configured statusLine.command on stdin after each render. On Pro/Max subscriptions that blob includes rate_limits. This is the only channel that exposes plan-limit data (see rejected alternatives) — so the feature must set a statusLine command, which is why the footer is also reconstructed by it (below).

Confirmed schema (real captured payload)

"rate_limits": {
  "five_hour": { "used_percentage": 15, "resets_at": 1781409000 },  // → 2026-06-14T03:50:00Z
  "seven_day": { "used_percentage": 34, "resets_at": 1781827200 }   // → 2026-06-19T00:00:00Z
}

Field	Type	Notes
rate_limits.five_hour.used_percentage	number 0–100	Integer-valued in practice; treat as number, don't assume decimals.
rate_limits.five_hour.resets_at	number	Epoch SECONDS (10 digits). ×1000 for a JS Date.
rate_limits.seven_day.{used_percentage,resets_at}	same

Confirmed facts & gotchas:

• Only two windows exist: five_hour and seven_day. There is no separate Opus-weekly field, even on a Max/Opus account.
• rate_limits is absent on the first render, present after the first API response. UI degrades to "no chip yet."
• statusLine fires only in interactive TUI mode, never --print. Fine — Codeman sessions are interactive TUIs (and so are Codeman-spawned ones in tmux).
• Subscriber-gated. Absent for API-key / non-subscriber auth.

Bonus telemetry in the same payload — used for the footer

The same stdin object also carries model.display_name, context_window.{used_percentage, total_input_tokens, total_output_tokens, …}, cost.total_cost_usd, effort.level, etc. The shipped feature uses model + token totals + context % to build the in-terminal footer (so the statusline stays useful even though we own it). The endpoint also broadcasts contextUsedPercentage/costUsd/modelDisplayName alongside the limits for future chip tooltips.

Alternatives considered & rejected

Source	Why not
OAuth endpoint api.anthropic.com/api/oauth/usage	Undocumented, aggressively rate-limited, needs the encrypted OAuth token. Only worth it for dollar spend.
/usage slash command	Interactive-only, no programmatic output.
On-disk ~/.claude/ files	No usage state persisted (only daemon.status.json = auto-updater supervisor).
CLI flag (claude usage / --check-usage)	Does not exist.
StopFailure hook	Carries only an error_type on failure — no live percentages.

As-built architecture

Claude TUI (any Claude session, incl. linked-case/real-repo sessions)
  │  renders statusline after each assistant msg (+ /compact, mode change)
  ▼
statusLine.command (settings.local.json)  ──reads stdin JSON──▶
  curl -sk POST $CODEMAN_API_URL/api/status-telemetry  {sessionId, data}
  (X-Codeman-Hook-Secret: $(cat $CODEMAN_HOOK_SECRET_FILE))
  │  ◀── HTTP 200 text/plain = current-SESSION status string ──┘
  ▼
printf '%s' "$body"  →  in-terminal footer: "Opus 4.8 (1M context)  in:… out:…  ctx:…%"

server (status-telemetry-routes.ts):
  parse rate_limits  → (if changed) store last-known + broadcast SSE session:statusTelemetry  → header chip
  parse model/tokens/ctx → return the session-status footer string
  ▼
app.js: _onSessionStatusTelemetry → chip (per-window colors) + localStorage save
        handleInit → chip from init-snapshot planUsage (fresh-load replay)

1. The exporter — generateStatusLineCommand() in hooks-config.ts

Mirrors the hook curlCmd(). Reads the stdin JSON, POSTs {sessionId, data} to a fixed loopback path, and prints the response body back to stdout (print-through, so the footer stays useful). The managed-session env carries $CODEMAN_SESSION_ID / $CODEMAN_API_URL / $CODEMAN_HOOK_SECRET_FILE (from tmux-manager.buildEnvExports()).

INPUT=$(cat 2>/dev/null || echo '{}'); \
printf '{"sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$INPUT" | \
curl -sk -X POST "$CODEMAN_API_URL/api/status-telemetry" \
  -H 'Content-Type: application/json' \
  -H "X-Codeman-Hook-Secret: $(cat "$CODEMAN_HOOK_SECRET_FILE" 2>/dev/null)" \
  --data @- 2>/dev/null || echo codeman

⚠️ curl -sk, not curl -s. Prod is loopback HTTPS with a self-signed cert; without -k, curl returns 000 and the statusline silently shows nothing. -k is safe (loopback only). (The existing hook curls use -s without -k and have the same latent issue on HTTPS installs — a known, separate follow-up.)

2. Endpoint — POST /api/status-telemetry (status-telemetry-routes.ts)

Fixed path (sessionId in the body, not the URL) so the auth exemption is an exact-match like /api/hook-event (middleware/auth.ts: loopback-only; X-Codeman-Hook-Secret-gated while a tunnel runs). Schema StatusTelemetrySchema in schemas.ts validates the subset; unknown keys are stripped. Pure parsing/formatting in usage-telemetry.ts:

• parseStatusTelemetry(data) → { fiveHour, sevenDay, … } or null. On change (signature dedup; statusline fires often), store last-known (plan-usage-latest.ts) and broadcast('session:statusTelemetry', { sessionId, …telemetry }).
• parseSessionStatus(data) + formatSessionStatusText() → the footer string Opus 4.8 (1M context) in:562,411 out:1,188 ctx:56% (returned as text/plain). Available from the first render, even before rate_limits appears.

3. SSE + frontend chip

session:statusTelemetry registered in sse-events.ts + constants.js. app.js:

• _onSessionStatusTelemetry → updatePlanUsageChip(data) + save to localStorage['codeman:planUsage'].
• updatePlanUsageChip renders two 5h/7d windows; per-window color by usage — green <60%, yellow 60–84%, red ≥85% (pu-green/pu-yellow/pu-red); bold labels/values; reset times in the tooltip. resets_at*1000 → Date.
• Chip element ships hidden (header-plan-usage--hidden); applyHeaderVisibilitySettings() reveals it client-side when the setting is on (response-viewer pattern — no renderIndexHtml strip, which kept the "title-only" render contract intact).

4. Chip data robustness — three layers

1. Live: session:statusTelemetry SSE on every distinct render.
2. Fresh load / reconnect: server stores the latest in plan-usage-latest.ts; getLightState() includes it as planUsage; the per-connection init snapshot replays it; handleInit paints the chip immediately (authoritative over localStorage). Null until the first telemetry of the process.
3. Offline / cross-restart: restorePlanUsageChip() reads localStorage on load (12h freshness guard).

5. Injection lifecycle — works for any user, never self-destructs

The setting showPlanUsageLimits is synced (in settings.json, not a per-device displayKey).

• On toggle (PUT /api/settings, system-routes.ts): reconcile the exporter across all active Claude sessions' working dirs — inject on enable, remove on disable. Server-side and authoritative, so existing sessions get the footer + feed the chip immediately, no new session needed, no dependency on a client's synced localStorage.
• On session create (session-routes.ts): ADD-ONLY — inject when statusLineTelemetry is true; never remove. Sessions in a repo share one settings.local.json, so a single create-with-false (e.g. a client whose synced setting hadn't loaded) must not yank the statusLine out from under other live sessions. Removal happens only via the explicit toggle.
• applyStatusLineConfig() is isOurs-guarded (matches /api/status-telemetry), so a user's own hand-authored statusLine is never touched, and it updates an out-of-date ours-command so fixes (e.g. -k) propagate. No CASES_DIR gate — runs for linked cases / real repos (where sessions actually run), mirroring updateCaseModel.

Codeman-specific considerations

1. Account-global limits. The 5h/7d pools are shared across all sessions on the account → one shared header chip (freshest sample wins), not a per-tab bar.
2. The footer is owned, by necessity. A statusLine command always replaces Claude's default footer. Since rate_limits only arrives via statusLine, we reconstruct a useful session-status footer (model · tokens · ctx %) from the same payload rather than showing the limits there.
3. isOurs-guarded. Never removes/overwrites a user's own statusLine on disable; only manages the Codeman exporter.
4. Security envelope unchanged. The exporter runs arbitrary shell every render — same trust model as the hook curls (localhost + $CODEMAN_HOOK_SECRET_FILE); reuses the hook-secret gate.
5. Claude-only. OpenCode/Codex emit no rate_limits JSON; injection is gated to mode === 'claude'.
6. Future — auto-resume synergy. Live percentages would let SessionAutoOps pre-arm before the wall instead of reacting to the stall footer. Not built.

Files shipped

• src/usage-telemetry.ts — pure parse/format (parseStatusTelemetry, parseSessionStatus, formatSessionStatusText, telemetrySignature) + test/usage-telemetry.test.ts.
• src/hooks-config.ts — generateStatusLineCommand() (curl -sk), applyStatusLineConfig() (add/update/remove, isOurs-guarded).
• src/web/routes/status-telemetry-routes.ts — POST /api/status-telemetry.
• src/web/plan-usage-latest.ts — process-wide last-known store for init replay.
• src/web/schemas.ts — StatusTelemetrySchema + showPlanUsageLimits + create-payload statusLineTelemetry.
• src/web/middleware/auth.ts — exemption extended to /api/status-telemetry.
• src/web/routes/session-routes.ts — add-only create-time injection.
• src/web/routes/system-routes.ts — settings-toggle reconcile.
• src/web/server.ts — getLightState().planUsage (init snapshot).
• src/web/sse-events.ts + constants.js — session:statusTelemetry.
• Frontend: app.js (_onSessionStatusTelemetry, updatePlanUsageChip, restorePlanUsageChip, handleInit), settings-ui.js (toggle + applyHeaderVisibilitySettings), index.html (chip + toggle row), styles.css (chip + colors), session-ui.js (create payload).

Bugs E2E testing caught (that unit tests didn't)

The first "shipped" build passed every test and was broken in practice. End-to-end testing on the real install (the lesson: drive a REAL session, observe the REAL output) surfaced:

1. CASES_DIR injection gate excluded the user's whole workflow — sessions run in linked cases / real repos, not under ~/codeman-cases. → dropped the gate.
2. curl -s → 000 on the loopback self-signed HTTPS cert; statusline silently empty. → curl -sk.
3. Remove-on-create-false + shared settings.local.json let a single stale client yank the statusLine out from under all sessions in a repo. → add-only on create; removal only via the toggle reconcile.
4. Chip blank after reload (localStorage-only, lost on restart/fresh browser). → server-side last-known in the init snapshot.

Open questions / future

• Schema stability. rate_limits is officially shipped but undocumented in exact shape; the parser is tolerant (renders whatever windows exist, ignores unknown).
• Hook curl -s parity. Hooks share the no--k issue on HTTPS installs — worth fixing the hook curl too (separate change; covered by cod54 tests).
• Disable cleanliness. Disabling removes the statusLine from active sessions; a brand-new session created by a stale client could re-add it (chip still hidden, footer benign). Fully server-authoritative create-time injection (read the setting server-side instead of the payload flag) would close this — deferred.

Verification appendix — how the schema was captured (reproducible)

Captured without touching global settings or any real session:

1. Throwaway dir /tmp/sl-capture with an exporter dump.sh that appends stdin to payloads.jsonl and prints cap; a settings.json pointing statusLine.command at it.
2. --print mode does not render a statusline → no capture (confirms TUI-only). Must use interactive.
3. Launch interactive Claude in an isolated tmux socket (tmux -L slcap, never -L codeman) inside the temp dir, --settings /tmp/sl-capture/settings.json (no global mutation). Confirm the workspace-trust dialog (appears even with --dangerously-skip-permissions), then send a one-line prompt (literal text + Enter separately, Ink-style).
4. After the first response, rate_limits appears in the second captured record (absent in the first). Inspect with jq '.rate_limits'.
5. Tear down: tmux -L slcap kill-server + rm -rf /tmp/sl-capture; verify the codeman socket is untouched.

Related: docs/claude-code-hooks-reference.md (hook callback pattern), src/usage-limit-patterns.ts (reactive fallback), docs/respawn-state-machine.md (auto-resume interplay).