feat: add ProxyBudgetWidget for LiteLLM/OpenRouter/compatible proxies

[sagy101]

Summary

Adds a new opt-in proxy-budget widget that displays spend-vs-cap from a LiteLLM-compatible HTTP proxy, with green/yellow/red threshold tiers. Ships with two verified presets out of the box (LiteLLM and OpenRouter) plus full path-driven configuration for any other bearer-token JSON endpoint (Portkey, Helicone, custom proxies). Defaults to Claude Code's existing ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN env vars so the typical setup needs zero config.

Happy to rename, restructure, or close if scope doesn't fit. The implementation is included so the design is concrete to react to.

Display

Live render with the widget at the end of line 2 (Budget: $616.72/$1000.00 (62%) in green):

Format options via metadata.format:

Format	Output
spend-percent (default)	Budget: $5.00/$100.00 (5%)
percent	Budget: 5%
spend	Budget: $5.00

Color tiers (default 80% warning / 95% critical, configurable):

Range	Color
< warning	green
warning..critical	yellow
>= critical	red

Presets

Two verified presets ship in this PR. Both auth via Authorization: Bearer <token> from the env var named by tokenEnv.

Preset	Endpoint	Spend path	Cap path	Reset path
litellm (default)	${baseUrl}/key/info	info.spend	info.max_budget	info.budget_reset_at
openrouter	${baseUrl}/api/v1/key	data.usage	data.limit	data.limit_reset

The presets live in PROXY_BUDGET_PRESETS in src/utils/proxy-budget-fetch.ts. Adding a new one is a single object entry — the exported ProxyBudgetPreset type, the isProxyBudgetPreset runtime guard, the metadata validator in usage-prefetch.ts, and the test matrix all derive from the registry keys. A test iterates the registry to assert every entry has a fully-specified shape, so adding a malformed preset fails the suite immediately.

OpenRouter shape verified against openrouter.ai/docs/api/api-reference/api-keys/get-current-key.

Implementation notes

• Data flow. Adds prefetchProxyBudgetIfNeeded to src/utils/usage-prefetch.ts, called once per render in src/ccstatusline.ts (mirrors the existing prefetchUsageDataIfNeeded pattern for Anthropic usage). Result attached to RenderContext.proxyBudgetData; the widget reads synchronously.
• HTTP / cache. New src/utils/proxy-budget-fetch.ts uses Node stdlib https (no new deps). Caches at ~/.cache/ccstatusline/proxy-budget.json with default 60s TTL, plus stale-cache fallback up to 10× TTL on transient failures. Lock file pattern adapted from src/utils/usage-fetch.ts. Sanity guard (spend > 2 × budget) returns null to suppress display when the proxy returns nonsense.
• Configuration via metadata. All settings live in WidgetItem.metadata: Record<string, string> (preset, endpoint, baseUrlEnv, tokenEnv, authScheme, JSON paths, thresholds, cacheTtlSec, timeoutMs, format). v1 ships without a custom Ink editor — users configure in JSON. Matches early custom-command behavior; a renderEditor can be added in a follow-up if requested.
• Color tiers via embedded chalk. render() returns a chalk-wrapped string (chalk.green/yellow/red). The renderer at src/utils/renderer.ts:756 wraps with its own outer SGR but the embedded codes survive intact — same mechanism that already works for any colored content. No changes needed in the renderer.
• Forward compat. Implements the optional getNumericValue returning the percentage so future threshold-aware features in the renderer can consume it without re-implementing the widget.
• Tokens come from env, never from config. tokenEnv (default ANTHROPIC_AUTH_TOKEN) selects the variable name; the value never touches settings.json, the disk cache, error logs, or anywhere else.
• Defaults match Claude Code conventions. ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN are the env vars Claude Code itself sets when routing through any proxy. The typical setup needs nothing in metadata beyond "enabled": true.

Why a native widget vs CustomCommand?

The existing CustomCommand widget can run a shell script that hits the same endpoint, but:

1. Subprocess overhead per render. Status line refreshes ~every 1-3s; spawning a separate shell each time plus serializing JSON over stdin is meaningful overhead compared to a sync read of context.proxyBudgetData.
2. Cache and lock-file reimplementation. Each user installing the CustomCommand recipe has to reimplement the 60s TTL, stale fallback, and concurrent-fetch locking themselves in shell.
3. Loss of typed config and first-class features. Threshold-aware tier colors, raw-value mode, preview mode, editor display, and getNumericValue all become script bookkeeping instead of native widget features.

The native widget pays a one-time integration cost for repeated correctness.

Files changed

• src/utils/proxy-budget-fetch.ts (new) — fetch, cache, lock, sanity guard, preset registry, dotted JSON path resolver
• src/utils/usage-prefetch.ts — new hasProxyBudgetWidget / prefetchProxyBudgetIfNeeded exports
• src/types/RenderContext.ts — new proxyBudgetData? field
• src/ccstatusline.ts — two lines: call prefetch, attach to context
• src/widgets/ProxyBudget.ts (new) — the widget class
• src/widgets/index.ts — re-export
• src/utils/widget-manifest.ts — manifest entry proxy-budget in Usage cluster
• src/utils/__tests__/proxy-budget-fetch.test.ts (new) — 18 cases (LiteLLM happy path, OpenRouter preset, custom paths, missing env, non-2xx, malformed JSON, missing field, sanity guard, timeout, bearer/x-api-key headers, fresh/stale cache, network down, registry guard + shape)
• src/widgets/__tests__/ProxyBudget.test.ts (new) — 16 cases (null data, tier boundaries, custom thresholds, format variants, raw mode, preview mode, invalid format/threshold fallback, editor display, getNumericValue, supportsRawValue/supportsColors)
• docs/USAGE.md — new "Proxy Budget Widget" section under existing widget docs

Test plan

• bun tsc --noEmit clean
• bun run lint clean (eslint, 0 warnings)
• bun test — 1288 / 1288 passing (1254 baseline + 34 new)
• bun run build produces dist/ccstatusline.js cleanly
• Smoke-tested against a live LiteLLM proxy (built binary piped sample hook JSON):
  • Cold cache: fetches and renders Budget: $X.XX/$Y.YY (NN%) in green; cache written to ~/.cache/ccstatusline/proxy-budget.json
  • Warm cache: ~0.25s end-to-end, no network call (verified via wall-clock timing)
  • Missing token: segment silently absent, no errors on stdout
  • Black-hole IP (https://10.255.255.1): widget hides, lock file cleaned up
• Visually verified end-to-end inside Claude Code with a full layout (model, thinking-effort, context bar, tokens, session-clock, cwd, git-branch, git-status, proxy-budget) — see screenshot above

Scope notes

Out of scope for v1: cloud-native cost APIs that don't fit the bearer-token-JSON pattern (AWS Bedrock SigV4 + Cost Explorer, Vertex AI service-account JWT + Cloud Billing, Azure RBAC + Cost Management). Documented in docs/USAGE.md under the widget's "Out of scope" note. Future: separate provider-specific widgets if there's demand.