feat(usage): plan usage limits header chip via statusLine telemetry

Surface Claude subscription plan usage limits (5-hour rolling + 7-day
weekly: percent used + reset time) in the header, opt-in via App Settings
→ Display → "Plan Usage Limits" (default OFF, no behavior change when off).

A Codeman-managed Claude statusLine exporter forwards the rate_limits JSON
to a new auth-exempt POST /api/status-telemetry (same loopback + hook-secret
gate as /api/hook-event); parsed telemetry broadcasts over SSE
session:statusTelemetry to a header chip (amber >=80%, red >=95%, reset
times on hover). The exporter prints the same summary back as the
in-terminal footer (print-through).

- src/usage-telemetry.ts: pure parser/formatter (epoch-sec -> ms, clamp,
  change signature) + test/usage-telemetry.test.ts
- hooks-config.ts: generateStatusLineCommand + applyStatusLineConfig
  (add/remove; never clobbers a user's own statusLine)
- session-routes.ts: inject gate (Claude-only, Codeman-managed cases),
  driven by create-payload statusLineTelemetry (session-ui.js)
- schemas.ts: StatusTelemetrySchema + showPlanUsageLimits + payload field
- frontend: header chip, applyHeaderVisibilitySettings toggle,
  renderIndexHtml strip, _onSessionStatusTelemetry handler

Schema empirically confirmed against Claude Code 2.1.177 (Claude Max):
only five_hour/seven_day windows exist (no Opus-weekly field); rate_limits
is absent before the first API response and for non-subscriber auth. Design
+ verification method in docs/usage-limits-display-plan.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/hooks-config.ts

@@ -213,3 +213,59 @@ export async function writeHooksConfig(casePath: string): Promise<void> {
 
   await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n');
 }
+
+/** Unique marker identifying Codeman's own statusLine command (vs a user's). */
+const STATUSLINE_MARKER = '/api/status-telemetry';
+
+/**
+ * The plan-usage statusLine exporter command. Mirrors the hook `curlCmd` pattern:
+ * reads Claude Code's statusline stdin JSON, POSTs `{sessionId,data}` to Codeman,
+ * and prints the response body (a compact "⟳ 5h 15% · 7d 34%" footer) back to
+ * stdout so the in-terminal statusline stays useful. Env vars resolve at runtime
+ * (present in every managed session via tmux setenv), so the config is static.
+ */
+export function generateStatusLineCommand(): string {
+  return (
+    `INPUT=$(cat 2>/dev/null || echo '{}'); ` +
+    `printf '{"sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$INPUT" | ` +
+    `curl -s -X POST "$CODEMAN_API_URL${STATUSLINE_MARKER}" ` +
+    `-H 'Content-Type: application/json' ` +
+    `-H "X-Codeman-Hook-Secret: $(cat "$CODEMAN_HOOK_SECRET_FILE" 2>/dev/null)" ` +
+    `--data @- 2>/dev/null || true`
+  );
+}
+
+/**
+ * Add or remove Codeman's plan-usage statusLine exporter in
+ * `.claude/settings.local.json`. Only ever touches a statusLine that is OURS
+ * (command targets `/api/status-telemetry`), so a user's hand-authored
+ * statusLine is never removed. Callers gate on Claude mode + a Codeman-managed
+ * case path. Merges, preserving all other keys (hooks, env, model).
+ */
+export async function applyStatusLineConfig(casePath: string, enabled: boolean): Promise<void> {
+  const claudeDir = join(casePath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  let existing: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      existing = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      return; // Malformed — don't rewrite it
+    }
+  }
+
+  const current = existing.statusLine as { command?: unknown } | undefined;
+  const isOurs = !!current && typeof current.command === 'string' && current.command.includes(STATUSLINE_MARKER);
+
+  if (enabled) {
+    if (isOurs) return; // already configured — avoid rewriting on every session create
+    if (!existsSync(claudeDir)) await mkdir(claudeDir, { recursive: true });
+    existing.statusLine = { type: 'command', command: generateStatusLineCommand() };
+  } else {
+    if (!isOurs) return; // nothing of ours to remove (leave a user's own statusLine alone)
+    delete existing.statusLine;
+  }
+
+  await writeFile(settingsPath, JSON.stringify(existing, null, 2) + '\n');
+}

src/usage-telemetry.ts

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Pure parsing + formatting of Claude Code statusline telemetry.
+ *
+ * Claude Code (v2.1.80+) pipes a JSON blob to a configured `statusLine.command`
+ * on each render. On Pro/Max subscriptions that blob carries a `rate_limits`
+ * object with the 5-hour rolling and 7-day weekly plan windows. The
+ * Codeman-managed statusLine exporter (see `hooks-config.generateStatusLineCommand`)
+ * POSTs that blob to `/api/status-telemetry`; these helpers normalize the subset
+ * Codeman displays and format the compact in-terminal footer string.
+ *
+ * Confirmed schema (empirically captured, CC 2.1.177, Claude Max — see
+ * `docs/usage-limits-display-plan.md`):
+ *   rate_limits.{five_hour,seven_day}.{used_percentage: number 0-100,
+ *                                      resets_at: number EPOCH-SECONDS}
+ * Only those two windows exist (no Opus-weekly field). `rate_limits` is absent
+ * before the first API response and for non-subscriber auth — both yield null.
+ *
+ * All functions are pure for testability. See `test/usage-telemetry.test.ts`.
+ *
+ * @module usage-telemetry
+ */
+
+/** A single normalized plan-usage window. */
+export interface UsageWindow {
+  /** Percent of the window consumed, 0–100. */
+  usedPercentage: number;
+  /** Epoch MILLISECONDS when the window resets (statusline reports seconds). */
+  resetAt: number;
+}
+
+/** Normalized telemetry Codeman broadcasts to the UI. */
+export interface StatusTelemetry {
+  fiveHour?: UsageWindow;
+  sevenDay?: UsageWindow;
+  /** Context-window percent used, 0–100 (bonus field from the same payload). */
+  contextUsedPercentage?: number;
+  /** Session cost in USD (bonus field). */
+  costUsd?: number;
+  /** Model display name, e.g. "Opus 4.8 (1M context)" (bonus field). */
+  modelDisplayName?: string;
+}
+
+/** Raw subset of the statusline stdin JSON (snake_case, as Claude emits it). */
+export interface RawStatuslinePayload {
+  rate_limits?: {
+    five_hour?: { used_percentage?: number; resets_at?: number };
+    seven_day?: { used_percentage?: number; resets_at?: number };
+  };
+  context_window?: { used_percentage?: number };
+  cost?: { total_cost_usd?: number };
+  model?: { display_name?: string };
+}
+
+function clampPct(n: number): number {
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(100, n));
+}
+
+function parseWindow(w?: { used_percentage?: number; resets_at?: number }): UsageWindow | undefined {
+  if (!w || typeof w.used_percentage !== 'number' || typeof w.resets_at !== 'number') return undefined;
+  if (!Number.isFinite(w.resets_at) || w.resets_at <= 0) return undefined;
+  return { usedPercentage: clampPct(w.used_percentage), resetAt: Math.round(w.resets_at * 1000) };
+}
+
+/**
+ * Normalize a raw statusline payload to the telemetry Codeman displays. Returns
+ * null when there is no plan-limit data to show (pre-first-response or a
+ * non-subscriber account) so the caller can skip broadcasting.
+ */
+export function parseStatusTelemetry(data: RawStatuslinePayload | undefined): StatusTelemetry | null {
+  if (!data) return null;
+  const fiveHour = parseWindow(data.rate_limits?.five_hour);
+  const sevenDay = parseWindow(data.rate_limits?.seven_day);
+  if (!fiveHour && !sevenDay) return null;
+
+  const t: StatusTelemetry = {};
+  if (fiveHour) t.fiveHour = fiveHour;
+  if (sevenDay) t.sevenDay = sevenDay;
+  if (typeof data.context_window?.used_percentage === 'number') {
+    t.contextUsedPercentage = clampPct(data.context_window.used_percentage);
+  }
+  if (typeof data.cost?.total_cost_usd === 'number' && Number.isFinite(data.cost.total_cost_usd)) {
+    t.costUsd = data.cost.total_cost_usd;
+  }
+  if (typeof data.model?.display_name === 'string' && data.model.display_name) {
+    t.modelDisplayName = data.model.display_name.slice(0, 60);
+  }
+  return t;
+}
+
+/** Compact in-terminal footer text (statusLine stdout / print-through). */
+export function formatStatusLineText(t: StatusTelemetry | null): string {
+  if (!t) return 'codeman';
+  const parts: string[] = [];
+  if (t.fiveHour) parts.push(`5h ${Math.round(t.fiveHour.usedPercentage)}%`);
+  if (t.sevenDay) parts.push(`7d ${Math.round(t.sevenDay.usedPercentage)}%`);
+  return parts.length ? `⟳ ${parts.join(' · ')}` : 'codeman';
+}
+
+/**
+ * Stable signature for change-detection — the statusline fires on every
+ * assistant message, so the route only rebroadcasts when this value changes.
+ */
+export function telemetrySignature(t: StatusTelemetry): string {
+  return JSON.stringify([
+    t.fiveHour?.usedPercentage ?? null,
+    t.fiveHour?.resetAt ?? null,
+    t.sevenDay?.usedPercentage ?? null,
+    t.sevenDay?.resetAt ?? null,
+    t.contextUsedPercentage ?? null,
+  ]);
+}

src/web/middleware/auth.ts

@@ -107,8 +107,9 @@ export function registerAuthMiddleware(
   }
 
   app.addHook('onRequest', (req, reply, done) => {
-    // Hook events come from local Claude Code hooks (curl from localhost) — no
-    // Basic-Auth credentials available. Validated downstream by HookEventSchema.
+    // Hook events + statusline telemetry come from local Claude Code (curl from
+    // localhost) — no Basic-Auth credentials available. Validated downstream by
+    // HookEventSchema / StatusTelemetrySchema. Same loopback+hook-secret gate.
     //
     // COD-54: the bare localhost bypass is unsafe while a tunnel is running, because
     // `cloudflared --url http://127.0.0.1:port` proxies internet traffic INTO the
@@ -119,7 +120,7 @@ export function registerAuthMiddleware(
     //   - tunnel not running (loopback-only, the normal case) → keep the plain
     //     localhost bypass so already-deployed (pre-secret) hooks + the loop's own
     //     credential-less hook channel keep working.
-    if (req.url === '/api/hook-event' && req.method === 'POST') {
+    if ((req.url === '/api/hook-event' || req.url === '/api/status-telemetry') && req.method === 'POST') {
       const ip = req.ip;
       const isLoopback = ip === '127.0.0.1' || ip === '::1' || ip === '::ffff:127.0.0.1';
       if (isLoopback) {

src/web/public/app.js

@@ -157,6 +157,7 @@ const _SSE_HANDLER_MAP = [
   [SSE_EVENTS.SESSION_LIMIT_RESUME, '_onSessionLimitResume'],
   [SSE_EVENTS.SESSION_LIMIT_RESUME_CANCELLED, '_onSessionLimitResumeCancelled'],
   [SSE_EVENTS.SESSION_CLI_INFO, '_onSessionCliInfo'],
+  [SSE_EVENTS.SESSION_STATUS_TELEMETRY, '_onSessionStatusTelemetry'],
 
   // Scheduled runs
   [SSE_EVENTS.SCHEDULED_CREATED, '_onScheduledCreated'],
@@ -1812,6 +1813,35 @@ class CodemanApp {
     }
   }
 
+  // Claude plan usage limits (5-hour + weekly) — account-global, so the latest
+  // sample from any session drives the shared header chip.
+  _onSessionStatusTelemetry(data) {
+    this._latestPlanUsage = data;
+    this.updatePlanUsageChip(data);
+  }
+
+  updatePlanUsageChip(data) {
+    const chip = document.getElementById('planUsageChip');
+    if (!chip || !data) return;
+    const pct = (w) => (w && typeof w.usedPercentage === 'number' ? Math.round(w.usedPercentage) : null);
+    const five = pct(data.fiveHour);
+    const seven = pct(data.sevenDay);
+    if (five === null && seven === null) return;
+    const parts = [];
+    if (five !== null) parts.push(`5h ${five}%`);
+    if (seven !== null) parts.push(`7d ${seven}%`);
+    chip.textContent = parts.join(' · ');
+    // Color hint as a window nears exhaustion.
+    const max = Math.max(five ?? 0, seven ?? 0);
+    chip.classList.toggle('header-plan-usage--warn', max >= 80 && max < 95);
+    chip.classList.toggle('header-plan-usage--crit', max >= 95);
+    const resetStr = (w) => (w && w.resetAt ? new Date(w.resetAt).toLocaleString() : '—');
+    chip.title =
+      `Claude plan usage\n` +
+      `5-hour: ${five ?? '—'}% (resets ${resetStr(data.fiveHour)})\n` +
+      `Weekly: ${seven ?? '—'}% (resets ${resetStr(data.sevenDay)})`;
+  }
+
   // Scheduled runs
   _onScheduledCreated(data) {
     this.currentRun = data;

src/web/public/constants.js

@@ -251,6 +251,7 @@ const SSE_EVENTS = {
   SESSION_MESSAGE: 'session:message',
   SESSION_INTERACTIVE: 'session:interactive',
   SESSION_RUNNING: 'session:running',
+  SESSION_STATUS_TELEMETRY: 'session:statusTelemetry',
 
   // Scheduled runs
   SCHEDULED_CREATED: 'scheduled:created',

src/web/public/index.html

@@ -115,6 +115,7 @@
         </div>
         <button class="btn-icon-header btn-response-viewer-header btn-response-viewer-header--hidden" onclick="app.toggleResponseViewer()" title="View last response" aria-label="View last response"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z"/><circle cx="12" cy="12" r="3"/></svg></button>
         <button class="btn-icon-header btn-multimonitor btn-multimonitor--hidden" onclick="app.launchMultiMonitor()" title="Open Codeman across all displays" aria-label="Open Codeman across all displays"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="4" width="13" height="9" rx="1.5"/><rect x="11" y="9" width="11" height="8" rx="1.5"/></svg></button>
+        <div class="header-plan-usage header-plan-usage--hidden" id="planUsageChip" title="Claude plan usage limits">—</div>
         <button class="btn-icon-header btn-notifications" onclick="app.toggleNotifications()" title="Notifications" aria-label="Toggle notifications" style="display:none;">
           <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/><path d="M13.73 21a2 2 0 0 1-3.46 0"/></svg>
           <span class="notification-badge" id="notifBadge" style="display:none;">0</span>
@@ -1025,6 +1026,13 @@
                   <span class="slider"></span>
                 </label>
               </div>
+              <div class="settings-item" title="Show Claude plan usage limits (5-hour & weekly) in the header. Applies to newly created sessions.">
+                <span class="settings-item-label">Plan Usage Limits</span>
+                <label class="switch switch-sm">
+                  <input type="checkbox" id="appSettingsShowPlanUsageLimits">
+                  <span class="slider"></span>
+                </label>
+              </div>
 
               <!-- Tab Bar Section -->
               <div class="settings-section-header">Tab Bar</div>

src/web/public/session-ui.js

@@ -370,6 +370,9 @@ Object.assign(CodemanApp.prototype, {
             ...(hasEnvOverrides ? { envOverrides } : {}),
             ...(effort ? { effort } : {}),
             ...(modelOverride !== undefined ? { modelOverride } : {}),
+            // Plan-usage statusLine exporter (App Settings → Display). Always
+            // sent so toggling the setting off removes our exporter on next create.
+            statusLineTelemetry: globalSettings.showPlanUsageLimits === true,
           })
         }).then(r => r.json())
       );

src/web/public/settings-ui.js

@@ -315,6 +315,7 @@ Object.assign(CodemanApp.prototype, {
     document.getElementById('appSettingsShowFileBrowser').checked = settings.showFileBrowser ?? defaults.showFileBrowser ?? false;
     document.getElementById('appSettingsShowSubagents').checked = settings.showSubagents ?? defaults.showSubagents ?? false;
     document.getElementById('appSettingsShowMultiMonitorButton').checked = settings.showMultiMonitorButton ?? defaults.showMultiMonitorButton ?? false;
+    document.getElementById('appSettingsShowPlanUsageLimits').checked = settings.showPlanUsageLimits ?? defaults.showPlanUsageLimits ?? false;
     // Gesture control lives in the Input section (alongside Local Echo / CJK Input)
     // but is only available when the instance runs with CODEMAN_GESTURE=1 (server sets
     // window.__codemanGestureAvailable). Hide just this item otherwise so the toggle
@@ -1369,6 +1370,7 @@ Object.assign(CodemanApp.prototype, {
       showFileBrowser: document.getElementById('appSettingsShowFileBrowser').checked,
       showSubagents: document.getElementById('appSettingsShowSubagents').checked,
       showMultiMonitorButton: document.getElementById('appSettingsShowMultiMonitorButton').checked,
+      showPlanUsageLimits: document.getElementById('appSettingsShowPlanUsageLimits').checked,
       gestureControlEnabled: document.getElementById('appSettingsGestureControl').checked,
       subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
       subagentActiveTabOnly: document.getElementById('appSettingsSubagentActiveTabOnly').checked,
@@ -1658,6 +1660,7 @@ Object.assign(CodemanApp.prototype, {
         showFileBrowser: false,
         showSubagents: false,
         showMultiMonitorButton: false,
+        showPlanUsageLimits: false,
         // Input
         gestureControlEnabled: false,
         // Feature toggles - keep tracking on even on mobile
@@ -1770,6 +1773,16 @@ Object.assign(CodemanApp.prototype, {
       multiMonitorBtn.classList.toggle('btn-multimonitor--hidden', !showMultiMonitorButton);
     }
 
+    // Plan-usage chip — hidden by default (App Settings → Display → "Plan Usage
+    // Limits"). Server renders the initial state on reload; this handles a live
+    // toggle from a settings save. Marker class (base is display:inline-flex
+    // !important), matching the response-viewer/multimonitor pattern.
+    const showPlanUsageLimits = settings.showPlanUsageLimits ?? defaults.showPlanUsageLimits ?? false;
+    const planUsageChip = document.getElementById('planUsageChip');
+    if (planUsageChip) {
+      planUsageChip.classList.toggle('header-plan-usage--hidden', !showPlanUsageLimits);
+    }
+
     // Notification bell is retired (notifications live in Settings → Notifications
     // + the drawer); keep it hidden regardless of the notification-enabled state.
     const notifBtn = document.querySelector('.btn-notifications');

src/web/public/styles.css

@@ -1107,6 +1107,7 @@ body.solo-mode .header-system-stats,
 body.solo-mode .header-tokens,
 body.solo-mode .btn-notifications,
 body.solo-mode .btn-multimonitor,
+body.solo-mode .header-plan-usage,
 body.solo-mode .btn-lifecycle-log {
   display: none !important;
 }
@@ -8321,6 +8322,38 @@ kbd {
   display: none !important;
 }
 
+/* Plan-usage chip (App Settings → Display → "Plan Usage Limits"). Shows the
+   live 5-hour + weekly plan limits parsed from the Claude statusline. Hidden by
+   default via the marker class below; the server strips it at render when the
+   setting is on and the client toggles it live on save. */
+.header-plan-usage {
+  display: inline-flex !important;
+  align-items: center;
+  height: 22px;
+  padding: 0 0.5rem;
+  border-radius: 11px;
+  font-size: 0.7rem;
+  font-weight: 500;
+  font-family: 'SF Mono', Monaco, monospace;
+  color: var(--text-dim);
+  background: rgba(255, 255, 255, 0.05);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  white-space: nowrap;
+  cursor: default;
+}
+.header-plan-usage--warn {
+  color: #e6b800;
+  border-color: rgba(230, 184, 0, 0.4);
+}
+.header-plan-usage--crit {
+  color: var(--danger, #ff5c5c);
+  border-color: rgba(255, 92, 92, 0.5);
+}
+/* Marker class must out-specify the display:inline-flex !important above. */
+.header-plan-usage.header-plan-usage--hidden {
+  display: none !important;
+}
+
 .response-viewer {
   display: none;
   position: fixed;

src/web/routes/index.ts

@@ -9,6 +9,7 @@ export { registerFileRoutes } from './file-routes.js';
 export { registerScheduledRoutes } from './scheduled-routes.js';
 export { registerSystemRoutes } from './system-routes.js';
 export { registerHookEventRoutes } from './hook-event-routes.js';
+export { registerStatusTelemetryRoutes } from './status-telemetry-routes.js';
 export { registerCaseRoutes } from './case-routes.js';
 export { registerSessionRoutes } from './session-routes.js';
 export { registerRespawnRoutes } from './respawn-routes.js';

src/web/routes/session-routes.ts

@@ -45,7 +45,7 @@ import {
   validatePathWithinBase,
 } from '../route-helpers.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
-import { writeHooksConfig, updateCaseModel, stripCaseEnvKeys } from '../../hooks-config.js';
+import { writeHooksConfig, updateCaseModel, stripCaseEnvKeys, applyStatusLineConfig } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { getLifecycleLog } from '../../session-lifecycle-log.js';
@@ -297,6 +297,14 @@ export function registerSessionRoutes(
       await updateCaseModel(workingDir, body.modelOverride || null);
     }
 
+    // Plan-usage statusLine exporter (App Settings → Display → "Plan Usage
+    // Limits"). Claude-only, and only inside Codeman-managed cases (never
+    // arbitrary user repos, which may carry a hand-authored statusLine). Adds or
+    // removes our exporter so toggling the setting off cleans up on next create.
+    if ((body.mode ?? 'claude') === 'claude' && workingDir.startsWith(CASES_DIR + '/')) {
+      await applyStatusLineConfig(workingDir, body.statusLineTelemetry === true);
+    }
+
     // Check OpenCode availability if requested
     if (body.mode === 'opencode') {
       const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');

src/web/routes/status-telemetry-routes.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Status-telemetry route.
+ *
+ * Receives Claude Code statusline payloads POSTed by the Codeman-managed
+ * statusLine exporter (see `hooks-config.generateStatusLineCommand`) and
+ * broadcasts the parsed plan-usage limits (5-hour + weekly) to SSE clients for
+ * the header "Plan Usage Limits" chip. Auth-exempt like `/api/hook-event`
+ * (localhost-only; hook-secret-gated while a tunnel runs — see middleware/auth).
+ *
+ * Returns a compact plain-text status string for the exporter to print as the
+ * in-terminal footer (print-through), so injecting our statusLine doesn't leave
+ * the terminal footer blank.
+ */
+
+import { FastifyInstance } from 'fastify';
+import { StatusTelemetrySchema } from '../schemas.js';
+import { parseBody } from '../route-helpers.js';
+import {
+  parseStatusTelemetry,
+  formatStatusLineText,
+  telemetrySignature,
+  type RawStatuslinePayload,
+} from '../../usage-telemetry.js';
+import { SessionStatusTelemetry } from '../sse-events.js';
+import type { SessionPort, EventPort } from '../ports/index.js';
+
+export function registerStatusTelemetryRoutes(app: FastifyInstance, ctx: SessionPort & EventPort): void {
+  // Last broadcast telemetry signature per session — the statusline fires on
+  // every assistant message, so we only rebroadcast when the value changes.
+  const lastSig = new Map<string, string>();
+
+  app.post('/api/status-telemetry', async (req, reply) => {
+    const { sessionId, data } = parseBody(StatusTelemetrySchema, req.body);
+
+    reply.type('text/plain; charset=utf-8');
+
+    // Unknown session — minimal footer, no broadcast.
+    if (!ctx.sessions.has(sessionId)) {
+      lastSig.delete(sessionId);
+      return 'codeman';
+    }
+
+    const telemetry = parseStatusTelemetry(data as RawStatuslinePayload | undefined);
+    if (!telemetry) {
+      // No plan-limit data yet (pre-first-response or non-subscriber auth).
+      return 'codeman';
+    }
+
+    const sig = telemetrySignature(telemetry);
+    if (lastSig.get(sessionId) !== sig) {
+      lastSig.set(sessionId, sig);
+      // Bound the map across long multi-session runs: prune dead sessions.
+      if (lastSig.size > 256) {
+        for (const id of [...lastSig.keys()]) {
+          if (!ctx.sessions.has(id)) lastSig.delete(id);
+        }
+      }
+      ctx.broadcast(SessionStatusTelemetry, { sessionId, ...telemetry });
+    }
+
+    return formatStatusLineText(telemetry);
+  });
+}

src/web/schemas.ts

@@ -158,6 +158,8 @@ export const CreateSessionSchema = z.object({
   effort: effortLevelSchema,
   /** Model override to write to .claude/settings.local.json (e.g., "opus[1m]"). Empty string clears. */
   modelOverride: z.string().max(50).optional(),
+  /** Inject the plan-usage statusLine exporter into the case (App Settings → Display → "Plan Usage Limits"). Claude-only. */
+  statusLineTelemetry: z.boolean().optional(),
   openCodeConfig: OpenCodeConfigSchema,
   codexConfig: CodexConfigSchema,
   /** Resume a previous Claude conversation by its session ID (used for reboot recovery) */
@@ -186,6 +188,37 @@ export const ResizeSchema = z.object({
   viewportType: z.enum(['mobile', 'tablet', 'desktop']).optional(),
 });
 
+/**
+ * Schema for POST /api/status-telemetry
+ * Claude Code statusline payload forwarded by the Codeman-managed statusLine
+ * exporter (see hooks-config.generateStatusLineCommand). Validates only the
+ * subset Codeman displays; unknown keys (session_id, transcript_path, cwd, …)
+ * are stripped by z.object. Auth-exempt like /api/hook-event.
+ */
+const RateLimitWindowSchema = z
+  .object({
+    used_percentage: z.number().optional(),
+    resets_at: z.number().optional(),
+  })
+  .optional();
+
+export const StatusTelemetrySchema = z.object({
+  sessionId: z.string().min(1).max(100),
+  data: z
+    .object({
+      rate_limits: z
+        .object({
+          five_hour: RateLimitWindowSchema,
+          seven_day: RateLimitWindowSchema,
+        })
+        .optional(),
+      context_window: z.object({ used_percentage: z.number().optional() }).optional(),
+      cost: z.object({ total_cost_usd: z.number().optional() }).optional(),
+      model: z.object({ display_name: z.string().max(100).optional() }).optional(),
+    })
+    .optional(),
+});
+
 // ========== Case Routes ==========
 
 /**
@@ -321,6 +354,7 @@ export const SettingsUpdateSchema = z
     showFileBrowser: z.boolean().optional(),
     showSubagents: z.boolean().optional(),
     showMultiMonitorButton: z.boolean().optional(),
+    showPlanUsageLimits: z.boolean().optional(),
     // Input
     gestureControlEnabled: z.boolean().optional(),
     // Claude CLI settings

src/web/server.ts

@@ -135,6 +135,7 @@ import {
   registerFileRoutes,
   registerScheduledRoutes,
   registerHookEventRoutes,
+  registerStatusTelemetryRoutes,
   registerSystemRoutes,
   registerCaseRoutes,
   registerSessionRoutes,
@@ -811,6 +812,7 @@ export class WebServer extends EventEmitter {
     registerFileRoutes(this.app, ctx);
     registerScheduledRoutes(this.app, ctx);
     registerHookEventRoutes(this.app, ctx);
+    registerStatusTelemetryRoutes(this.app, ctx);
     registerSystemRoutes(this.app, ctx);
     registerCaseRoutes(this.app, ctx);
     registerSessionRoutes(this.app, ctx);
@@ -1121,6 +1123,13 @@ export class WebServer extends EventEmitter {
     if (settings.showMultiMonitorButton === true) {
       html = html.replace(' btn-multimonitor--hidden', '');
     }
+    // Plan-usage chip: carries `header-plan-usage--hidden` by default (App
+    // Settings → Display → "Plan Usage Limits"); reveal by stripping the marker
+    // class when the user enabled it, so the chip paints in the right state on
+    // every normal reload (the client toggles the same class live on save).
+    if (settings.showPlanUsageLimits === true) {
+      html = html.replace(' header-plan-usage--hidden', '');
+    }
     // Detached single-session ("solo") window: inject the target session id so
     // the client can enter solo mode even if a (network-first) service worker
     // later serves a cached shell. The client primarily detects solo mode from

src/web/sse-events.ts

@@ -87,6 +87,8 @@ export const SessionMessage = 'session:message' as const;
 export const SessionInteractive = 'session:interactive' as const;
 /** Prompt sent to session for execution. */
 export const SessionRunning = 'session:running' as const;
+/** Claude plan-usage telemetry (5-hour + weekly limits) parsed from the statusline. */
+export const SessionStatusTelemetry = 'session:statusTelemetry' as const;
 
 // ─── Session: Ralph ──────────────────────────────────────────────────────────
 
@@ -376,6 +378,7 @@ export const SseEvent = {
   SessionMessage,
   SessionInteractive,
   SessionRunning,
+  SessionStatusTelemetry,
 
   // Session: Ralph
   SessionRalphLoopUpdate,