@jlongo78/agent-spaces 0.9.8 → 0.9.9

package/.next/standalone/docs/superpowers/plans/2026-04-22-claude-usage-display.md

@@ -0,0 +1,749 @@
+# Claude Usage Display Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show a compact Anthropic plan-usage readout (mirroring `/usage` in Claude Code) in the Spaces terminal page header, visible when the active workspace has at least one Claude pane.
+
+**Architecture:** Spaces reads the OAuth access token from `~/.claude/.credentials.json` (already maintained by Claude Code), calls `https://api.anthropic.com/api/oauth/usage`, caches 30s server-side, and polls the route every 60s from a React hook. A three-bar strip component renders in the header; clicking expands a popover with all windows. Passive refresh: if the access token is expired or missing, the strip shows a "sign in via Claude Code" hint.
+
+**Tech Stack:** Next.js App Router, React 18 client components, Node `fetch` with `AbortController`, TypeScript, Tailwind, lucide-react.
+
+**Spec:** `docs/superpowers/specs/2026-04-22-claude-usage-display-design.md`
+
+**Repo workflow note:** Commit directly to `main`. No feature branch, no PR. Each task ends with a commit.
+
+---
+
+## File Structure
+
+**Create:**
+- `src/lib/claude/credentials.ts` — reads `.credentials.json`, extracts and validates the `claudeAiOauth` block.
+- `src/lib/claude/usage.ts` — calls Anthropic's `/api/oauth/usage`, caches 30s.
+- `src/app/api/claude/usage/route.ts` — `GET` handler wiring the above together.
+- `src/hooks/use-claude-usage.ts` — 60s polling hook.
+- `src/components/claude/claude-usage-strip.tsx` — compact 3-bar strip + expanded popover.
+- `docs/features/claude-usage.md` — feature doc.
+
+**Modify:**
+- `src/types/claude.ts` — add `RateLimit`, `ExtraUsage`, `Utilization`, `UsageResponse` types.
+- `src/app/(desktop)/terminal/page.tsx` — mount `<ClaudeUsageStrip>` conditionally in the header.
+
+---
+
+## Task 1: Types + credentials reader
+
+**Files:**
+- Modify: `src/types/claude.ts`
+- Create: `src/lib/claude/credentials.ts`
+
+- [ ] **Step 1: Add types to `src/types/claude.ts`**
+
+Append at the end of the file:
+
+```ts
+// ─── Claude plan-usage (mirrors /usage in Claude Code) ───────
+
+export interface RateLimit {
+  utilization: number | null; // 0-100
+  resets_at: string | null;   // ISO 8601
+}
+
+export interface ExtraUsage {
+  is_enabled: boolean;
+  monthly_limit: number | null;
+  used_credits: number | null;
+  utilization: number | null;
+}
+
+export interface Utilization {
+  five_hour?: RateLimit | null;
+  seven_day?: RateLimit | null;
+  seven_day_oauth_apps?: RateLimit | null;
+  seven_day_opus?: RateLimit | null;
+  seven_day_sonnet?: RateLimit | null;
+  extra_usage?: ExtraUsage | null;
+}
+
+export type UsageResponse =
+  | { status: 'ok'; data: Utilization }
+  | { status: 'unauthenticated' }
+  | { status: 'expired' }
+  | { status: 'upstream_error' };
+```
+
+- [ ] **Step 2: Create `src/lib/claude/credentials.ts`**
+
+```ts
+import path from 'path';
+import os from 'os';
+import { readFile } from 'fs/promises';
+
+export interface ClaudeAiOAuthTokens {
+  accessToken: string;
+  refreshToken: string | null;
+  expiresAt: number | null; // epoch ms
+  scopes?: string[];
+}
+
+function getCredentialsPath(): string {
+  const home = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+  return path.join(home, '.credentials.json');
+}
+
+/**
+ * Reads ~/.claude/.credentials.json and returns the claudeAiOauth block.
+ * Returns null on any read/parse failure or if the block is absent.
+ */
+export async function readClaudeAiOauthTokens(): Promise<ClaudeAiOAuthTokens | null> {
+  try {
+    const raw = await readFile(getCredentialsPath(), 'utf8');
+    const parsed = JSON.parse(raw) as { claudeAiOauth?: ClaudeAiOAuthTokens };
+    const tokens = parsed.claudeAiOauth;
+    if (!tokens?.accessToken) return null;
+    return tokens;
+  } catch {
+    return null;
+  }
+}
+
+export function isTokenExpired(tokens: ClaudeAiOAuthTokens, nowMs = Date.now()): boolean {
+  if (!tokens.expiresAt) return false; // no expiry set → treat as valid
+  return nowMs >= tokens.expiresAt;
+}
+```
+
+- [ ] **Step 3: Type-check**
+
+```bash
+cd /home/jlongo/development/spaces && npx tsc --noEmit
+```
+
+Expected: no new errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add src/types/claude.ts src/lib/claude/credentials.ts
+git commit -m "feat(claude): read OAuth tokens from .credentials.json"
+```
+
+---
+
+## Task 2: Anthropic usage fetcher + cache
+
+**Files:**
+- Create: `src/lib/claude/usage.ts`
+
+- [ ] **Step 1: Create the fetcher**
+
+```ts
+import type { Utilization } from '@/types/claude';
+
+const ANTHROPIC_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
+const REQUEST_TIMEOUT_MS = 5_000;
+const CACHE_TTL_MS = 30_000;
+
+// UA matches the Claude Code format because Anthropic's endpoint classifies
+// the caller by UA. Kept in sync manually if upstream ever changes.
+const USER_AGENT = 'claude-code/spaces-integration';
+
+interface CacheEntry {
+  fetchedAt: number;
+  data: Utilization;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+function cacheKey(accessToken: string): string {
+  return accessToken.slice(0, 16);
+}
+
+export type FetchOutcome =
+  | { ok: true; data: Utilization }
+  | { ok: false; reason: 'upstream_error' };
+
+export async function fetchUtilization(accessToken: string): Promise<FetchOutcome> {
+  const key = cacheKey(accessToken);
+  const cached = cache.get(key);
+  if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+    return { ok: true, data: cached.data };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(ANTHROPIC_USAGE_URL, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+        'User-Agent': USER_AGENT,
+      },
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      return { ok: false, reason: 'upstream_error' };
+    }
+
+    const data = (await res.json()) as Utilization;
+    cache.set(key, { fetchedAt: Date.now(), data });
+    return { ok: true, data };
+  } catch {
+    return { ok: false, reason: 'upstream_error' };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Testing/hot-reload helper. */
+export function __clearUsageCache() {
+  cache.clear();
+}
+```
+
+- [ ] **Step 2: Type-check**
+
+```bash
+cd /home/jlongo/development/spaces && npx tsc --noEmit
+```
+
+Expected: no new errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add src/lib/claude/usage.ts
+git commit -m "feat(claude): fetch Anthropic plan-usage with 30s cache"
+```
+
+---
+
+## Task 3: API route `GET /api/claude/usage`
+
+**Files:**
+- Create: `src/app/api/claude/usage/route.ts`
+
+- [ ] **Step 1: Create the route**
+
+```ts
+import { NextRequest, NextResponse } from 'next/server';
+import { getAuthUser, withUser } from '@/lib/auth';
+import { ensureInitialized } from '@/lib/db/init';
+import { readClaudeAiOauthTokens, isTokenExpired } from '@/lib/claude/credentials';
+import { fetchUtilization } from '@/lib/claude/usage';
+import type { UsageResponse } from '@/types/claude';
+
+export async function GET(request: NextRequest) {
+  const user = getAuthUser(request);
+  return withUser(user, async () => {
+    await ensureInitialized();
+
+    const tokens = await readClaudeAiOauthTokens();
+    if (!tokens) {
+      const body: UsageResponse = { status: 'unauthenticated' };
+      return NextResponse.json(body);
+    }
+
+    if (isTokenExpired(tokens)) {
+      const body: UsageResponse = { status: 'expired' };
+      return NextResponse.json(body);
+    }
+
+    const outcome = await fetchUtilization(tokens.accessToken);
+    if (!outcome.ok) {
+      const body: UsageResponse = { status: 'upstream_error' };
+      return NextResponse.json(body);
+    }
+
+    const body: UsageResponse = { status: 'ok', data: outcome.data };
+    return NextResponse.json(body);
+  });
+}
+```
+
+- [ ] **Step 2: Smoke test against the running dev server**
+
+Determine which dev server is listening (3458 for turbopack is typical; 3457 for production build):
+
+```bash
+curl -sS http://localhost:3458/api/workspaces -o /dev/null -w '%{http_code}\n' 2>/dev/null
+curl -sS http://localhost:3457/api/workspaces -o /dev/null -w '%{http_code}\n' 2>/dev/null
+```
+
+Use whichever returns `200`. Then:
+
+```bash
+BASE=http://localhost:3458
+curl -s "$BASE/api/claude/usage"
+```
+
+Expected: JSON with one of the four statuses. If you're logged in, it should be `{"status":"ok","data":{...}}` with `five_hour`, `seven_day_opus`, etc. If logged out or no credentials file, it should be `{"status":"unauthenticated"}`.
+
+Don't start a new dev server; use whatever is already running. If the only listener is a production build that won't hot-reload, report BLOCKED.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add src/app/api/claude/usage/route.ts
+git commit -m "feat(api): add GET /api/claude/usage"
+```
+
+---
+
+## Task 4: `useClaudeUsage` hook
+
+**Files:**
+- Create: `src/hooks/use-claude-usage.ts`
+
+- [ ] **Step 1: Create the hook**
+
+```ts
+'use client';
+
+import { useEffect, useState } from 'react';
+import { api } from '@/lib/api';
+import type { UsageResponse } from '@/types/claude';
+
+const POLL_INTERVAL_MS = 60_000;
+
+export function useClaudeUsage(enabled: boolean): UsageResponse | null {
+  const [response, setResponse] = useState<UsageResponse | null>(null);
+
+  useEffect(() => {
+    if (!enabled) {
+      setResponse(null);
+      return;
+    }
+
+    let cancelled = false;
+
+    async function load() {
+      try {
+        const res = await fetch(api('/api/claude/usage'));
+        if (!res.ok) return;
+        const data: UsageResponse = await res.json();
+        if (!cancelled) setResponse(data);
+      } catch {
+        // Silent — the UI handles undefined state gracefully.
+      }
+    }
+
+    load();
+    const timer = setInterval(load, POLL_INTERVAL_MS);
+
+    return () => {
+      cancelled = true;
+      clearInterval(timer);
+    };
+  }, [enabled]);
+
+  return response;
+}
+```
+
+- [ ] **Step 2: Type-check**
+
+```bash
+cd /home/jlongo/development/spaces && npx tsc --noEmit
+```
+
+Expected: no new errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add src/hooks/use-claude-usage.ts
+git commit -m "feat(hooks): add useClaudeUsage polling hook"
+```
+
+---
+
+## Task 5: `<ClaudeUsageStrip />` component
+
+**Files:**
+- Create: `src/components/claude/claude-usage-strip.tsx`
+
+- [ ] **Step 1: Create the component**
+
+```tsx
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { Zap, LogIn } from 'lucide-react';
+import { useClaudeUsage } from '@/hooks/use-claude-usage';
+import type { RateLimit } from '@/types/claude';
+
+interface Props {
+  enabled: boolean;
+}
+
+function utilizationColor(pct: number | null): string {
+  if (pct == null) return '#52525b'; // zinc-600 — unknown
+  if (pct <= 70) return '#22c55e';    // green-500
+  if (pct <= 90) return '#f59e0b';    // amber-500
+  return '#ef4444';                    // red-500
+}
+
+function formatReset(resetsAt: string | null): string {
+  if (!resetsAt) return '';
+  const ms = new Date(resetsAt).getTime() - Date.now();
+  if (ms <= 0) return 'now';
+  const h = Math.floor(ms / 3_600_000);
+  const m = Math.floor((ms % 3_600_000) / 60_000);
+  if (h >= 24) {
+    const d = Math.floor(h / 24);
+    const rh = h - d * 24;
+    return `${d}d ${rh}h`;
+  }
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+function Bar({ label, limit }: { label: string; limit: RateLimit | null | undefined }) {
+  if (!limit || limit.utilization == null) return null;
+  const pct = Math.min(100, Math.max(0, limit.utilization));
+  const color = utilizationColor(pct);
+  const reset = formatReset(limit.resets_at);
+  return (
+    <div
+      className="flex items-center gap-1.5 text-[10px]"
+      title={reset ? `${label}: ${Math.floor(pct)}% used · resets in ${reset}` : `${label}: ${Math.floor(pct)}% used`}
+    >
+      <span className="text-zinc-400 font-medium">{label}</span>
+      <div className="w-12 h-1 bg-zinc-800 rounded-full overflow-hidden">
+        <div
+          className="h-full transition-all"
+          style={{ width: `${pct}%`, backgroundColor: color }}
+        />
+      </div>
+      <span className="text-zinc-500 tabular-nums w-7 text-right">{Math.floor(pct)}%</span>
+    </div>
+  );
+}
+
+export function ClaudeUsageStrip({ enabled }: Props) {
+  const response = useClaudeUsage(enabled);
+  const [expanded, setExpanded] = useState(false);
+  const popoverRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!expanded) return;
+    function handleClick(e: MouseEvent) {
+      if (popoverRef.current && !popoverRef.current.contains(e.target as Node)) {
+        setExpanded(false);
+      }
+    }
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [expanded]);
+
+  if (!enabled || !response) return null;
+
+  if (response.status === 'unauthenticated' || response.status === 'expired') {
+    return (
+      <div
+        className="flex items-center gap-1.5 px-2 py-1 text-[10px] text-zinc-500 border border-zinc-800 rounded-md"
+        title={response.status === 'expired' ? 'OAuth token expired — run any Claude Code command to refresh' : 'No Claude.ai credentials found'}
+      >
+        <LogIn className="w-3 h-3" />
+        sign in via Claude Code
+      </div>
+    );
+  }
+
+  if (response.status === 'upstream_error') {
+    return null; // Silent — per spec.
+  }
+
+  const { data } = response;
+  const extra = data.extra_usage;
+  const hasOverage = !!(extra?.is_enabled && extra?.used_credits && extra.used_credits > 0);
+
+  return (
+    <div className="relative">
+      <button
+        onClick={() => setExpanded(v => !v)}
+        className="flex items-center gap-2.5 px-2.5 py-1 border border-zinc-800 rounded-md hover:border-zinc-700 transition-colors"
+        title="Click for full usage detail"
+      >
+        <Zap className="w-3 h-3 text-amber-400" />
+        <Bar label="5h" limit={data.five_hour} />
+        <Bar label="Opus" limit={data.seven_day_opus} />
+        <Bar label="Sonnet" limit={data.seven_day_sonnet} />
+        {hasOverage && extra?.used_credits != null && (
+          <span className="text-[10px] text-amber-400 border-l border-zinc-800 pl-2">
+            +${extra.used_credits.toFixed(2)} overage
+          </span>
+        )}
+      </button>
+
+      {expanded && (
+        <div
+          ref={popoverRef}
+          className="absolute top-full right-0 mt-1.5 z-50 w-80 p-3 bg-zinc-900 border border-zinc-700 rounded-md shadow-xl"
+        >
+          <div className="text-[10px] uppercase tracking-wider text-zinc-500 font-medium mb-2">
+            Plan Usage
+          </div>
+          <div className="space-y-2">
+            <ExpandedRow label="5-hour window" limit={data.five_hour} />
+            <ExpandedRow label="7-day (overall)" limit={data.seven_day} />
+            <ExpandedRow label="7-day · Opus" limit={data.seven_day_opus} />
+            <ExpandedRow label="7-day · Sonnet" limit={data.seven_day_sonnet} />
+            <ExpandedRow label="7-day · OAuth apps" limit={data.seven_day_oauth_apps} />
+          </div>
+          {extra?.is_enabled && (
+            <div className="mt-3 pt-3 border-t border-zinc-800">
+              <div className="text-[10px] uppercase tracking-wider text-zinc-500 font-medium mb-1.5">
+                Overage credits
+              </div>
+              <div className="text-xs text-zinc-300">
+                {extra.used_credits != null ? `$${extra.used_credits.toFixed(2)}` : '—'}
+                {extra.monthly_limit != null && (
+                  <span className="text-zinc-500"> / ${extra.monthly_limit.toFixed(2)} monthly</span>
+                )}
+              </div>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function ExpandedRow({ label, limit }: { label: string; limit: RateLimit | null | undefined }) {
+  if (!limit || limit.utilization == null) {
+    return (
+      <div className="flex items-center justify-between text-xs">
+        <span className="text-zinc-400">{label}</span>
+        <span className="text-zinc-600">—</span>
+      </div>
+    );
+  }
+  const pct = Math.min(100, Math.max(0, limit.utilization));
+  const color = utilizationColor(pct);
+  const reset = formatReset(limit.resets_at);
+  return (
+    <div>
+      <div className="flex items-center justify-between text-xs mb-1">
+        <span className="text-zinc-300">{label}</span>
+        <span className="text-zinc-500 tabular-nums">
+          {Math.floor(pct)}%{reset && <span className="ml-1.5 text-zinc-600">· {reset}</span>}
+        </span>
+      </div>
+      <div className="h-1.5 bg-zinc-800 rounded-full overflow-hidden">
+        <div
+          className="h-full transition-all"
+          style={{ width: `${pct}%`, backgroundColor: color }}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Type-check**
+
+```bash
+cd /home/jlongo/development/spaces && npx tsc --noEmit
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add src/components/claude/claude-usage-strip.tsx
+git commit -m "feat(ui): add ClaudeUsageStrip component"
+```
+
+---
+
+## Task 6: Mount `<ClaudeUsageStrip />` in the terminal header
+
+**Files:**
+- Modify: `src/app/(desktop)/terminal/page.tsx`
+
+- [ ] **Step 1: Add the import**
+
+At the top of `src/app/(desktop)/terminal/page.tsx`, near the other component imports (around the `WorkspaceTodos` / `ProjectWizard` imports), add:
+
+```tsx
+import { ClaudeUsageStrip } from '@/components/claude/claude-usage-strip';
+```
+
+- [ ] **Step 2: Mount conditionally in the header**
+
+Find the header's right-hand button cluster — the `<div className="flex items-center gap-2">` that contains the `Files`, `Collab`, `Close`, and `Add Pane` buttons (around lines 863-922, inside the entered-workspace `return`). Insert the strip **as the first child** of that cluster, before the `Files` button:
+
+```tsx
+        <div className="flex items-center gap-2">
+          <ClaudeUsageStrip enabled={panes.some(p => p.agentType === 'claude' && !poppedOut.has(p.id))} />
+          <button
+            onClick={() => setShowFiles(!showFiles)}
+            ...
+```
+
+The `enabled` prop is `true` when the current workspace has at least one visible (not popped-out) Claude pane. `panes` is already in scope in `TerminalPageInner`.
+
+- [ ] **Step 3: Type-check**
+
+```bash
+cd /home/jlongo/development/spaces && npx tsc --noEmit
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add "src/app/(desktop)/terminal/page.tsx"
+git commit -m "feat(terminal): mount ClaudeUsageStrip in header when Claude panes exist"
+```
+
+---
+
+## Task 7: Feature doc
+
+**Files:**
+- Create: `docs/features/claude-usage.md`
+
+- [ ] **Step 1: Write the doc**
+
+```markdown
+# Claude Plan-Usage Display
+
+**Status:** stable
+**Owner:** jlongo
+**Last updated:** 2026-04-22
+
+## Overview
+
+A compact readout of the user's Anthropic plan-usage rate limits, surfaced in the terminal page header whenever the active workspace has at least one Claude pane. Shows 5-hour, 7-day Opus, and 7-day Sonnet windows at a glance; click expands to all windows plus overage credits. Data matches what `/usage` shows inside Claude Code.
+
+## User-facing behavior
+
+- Open any workspace on `/terminal` that has a Claude pane.
+- A horizontal strip appears in the header (right side, before Files / Collab / Close / Add Pane).
+- Three thin progress bars: **5h**, **Opus**, **Sonnet** — each with a percent label and a color that escalates green → amber → red.
+- Hover a bar → tooltip `{label}: X% used · resets in 2h 14m`.
+- Click the strip → popover with all five rate-limit windows + an overage-credits block if the account has overage enabled.
+- If the OAuth token is missing or expired, the strip shows `sign in via Claude Code` with a small login icon. No auto-refresh.
+- If the Anthropic endpoint fails or times out, the strip hides silently.
+
+## Architecture
+
+UI (`src/components/claude/claude-usage-strip.tsx`) → polling hook (`src/hooks/use-claude-usage.ts`) → API route (`src/app/api/claude/usage/route.ts`) → credentials reader (`src/lib/claude/credentials.ts`) + Anthropic fetcher with 30s cache (`src/lib/claude/usage.ts`) → `https://api.anthropic.com/api/oauth/usage`.
+
+Polling: hook calls the route on mount and every 60s while the strip is enabled. Server caches the Anthropic response 30s per access-token prefix so rapid re-polls don't hammer Anthropic.
+
+## Key files
+
+| Path | Role |
+|---|---|
+| `src/lib/claude/credentials.ts` | Reads `~/.claude/.credentials.json`, extracts `claudeAiOauth`, exposes `isTokenExpired()`. |
+| `src/lib/claude/usage.ts` | Calls Anthropic's `/api/oauth/usage`, 5s timeout, 30s in-memory cache. |
+| `src/app/api/claude/usage/route.ts` | `GET` handler; returns one of `ok` / `unauthenticated` / `expired` / `upstream_error`. |
+| `src/hooks/use-claude-usage.ts` | 60s polling hook, toggled by `enabled` arg. |
+| `src/components/claude/claude-usage-strip.tsx` | Compact 3-bar strip + expanded popover. |
+| `src/app/(desktop)/terminal/page.tsx` | Mounts the strip conditionally in the header. |
+| `src/types/claude.ts` | `RateLimit`, `ExtraUsage`, `Utilization`, `UsageResponse`. |
+
+## Data model
+
+No DB tables. All state is transient:
+- Server-side: in-memory `Map<tokenPrefix, { fetchedAt, data }>` in `src/lib/claude/usage.ts` with 30s TTL. Process-local; resets on server restart.
+- Client-side: React state in the hook.
+
+## APIs / contracts
+
+### Internal endpoints
+
+- `GET /api/claude/usage` — returns `UsageResponse`:
+  - `200 { status: "ok", data: Utilization }` — happy path.
+  - `200 { status: "unauthenticated" }` — no credentials file or no `claudeAiOauth`.
+  - `200 { status: "expired" }` — access token past `expiresAt`.
+  - `200 { status: "upstream_error" }` — Anthropic non-2xx or timeout.
+
+Auth: same `withUser`/`getAuthUser` wrapping as every other `/api/*` route.
+
+### External calls
+
+- **Anthropic `GET https://api.anthropic.com/api/oauth/usage`** — uses the user's own OAuth access token read from `~/.claude/.credentials.json`. No secret of our own. User-Agent `claude-code/spaces-integration`.
+
+## Configuration & environment
+
+- `CLAUDE_CONFIG_DIR` — respected (defaults to `~/.claude`). Same semantics as Claude Code.
+- No env vars, feature flags, or tier gates specific to this feature.
+
+## How to run / test locally
+
+```bash
+npm install
+npm run build
+npm start
+# visit http://localhost:3457/terminal, enter a workspace, add a Claude pane
+```
+
+Manual QA checklist:
+
+1. With a valid OAuth session (logged in via any recent Claude Code run): the strip appears in the header; percents match `/usage` inside Claude Code.
+2. Hover each bar → tooltip shows the reset timing.
+3. Click → popover with all five windows and overage block (if applicable).
+4. Delete the Claude pane from the workspace → strip disappears.
+5. Set `claudeAiOauth.expiresAt` to a past timestamp in `.credentials.json`, reload → strip shows "sign in via Claude Code".
+6. Move `.credentials.json` aside temporarily, reload → same sign-in hint.
+7. Disconnect network → within ~90s the strip silently hides (`upstream_error` → null render).
+
+No automated tests for v1.
+
+## Known quirks & decisions
+
+- **Passive refresh.** We do not refresh the OAuth access token. Claude Code owns the refresh lifecycle and writes `.credentials.json`; racing with it would corrupt the shared file.
+- **Account-wide data, not per-pane.** The Anthropic endpoint returns account-level rate limits. Rendering once in the header (not per-pane) is intentional.
+- **User-Agent string.** Anthropic classifies callers by UA; we send `claude-code/spaces-integration`. If upstream changes expectations, bump the constant in `src/lib/claude/usage.ts`.
+- **30s cache + 60s poll.** Outer-bound staleness is ~90s; fine for windows that move in hours.
+- **Token-prefix cache key.** First 16 chars of `accessToken`. Collision probability is effectively nil; avoids holding full tokens in the cache structure beyond the single request.
+- **Silent upstream failure.** Errors hide the strip rather than showing a red toast — rate-limit info is nice-to-have, not mission-critical.
+- **Ships direct to `main`.** Per repo convention.
+
+## Open questions / TODOs
+
+- [ ] Active OAuth refresh — mirror Claude Code's `/oauth/token` dance to keep the widget live past expiry. Deferred for v1.
+- [ ] Session-cost complement using local JSONL token counts (different data source).
+- [ ] Consider surfacing 7-day-overall alongside the current three for users who care.
+
+## Changelog
+
+- 2026-04-22 — Initial implementation. v1 ships direct to `main`.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+cd /home/jlongo/development/spaces
+git add docs/features/claude-usage.md
+git commit -m "docs(features): add claude-usage feature doc"
+```
+
+---
+
+## Self-Review Notes
+
+**Spec coverage:** every section of `docs/superpowers/specs/2026-04-22-claude-usage-display-design.md` is implemented:
+- Types → Task 1
+- Credentials reader → Task 1
+- Anthropic fetcher + cache → Task 2
+- API route with four structured statuses → Task 3
+- 60s polling hook → Task 4
+- Component (compact + expanded) → Task 5
+- Conditional header mount → Task 6
+- Feature doc → Task 7
+
+**Placeholder scan:** no TBD/TODO outside the feature doc's explicit "Open questions / TODOs" section.
+
+**Type consistency:** `Utilization`, `RateLimit`, `ExtraUsage`, `UsageResponse` are defined once in Task 1 and referenced by the same names in Tasks 2 / 3 / 4 / 5 / 7.