AlexandrAI AGENTS.md
agents-md

Claude Usage Webview Dashboard Agent Guide

Agent guide for dashboard webview HTML, message handling, rendering, escaping, and CSP.

AGENTS.md

Guidance for coding agents working on Claude Usage Webview Dashboard in the claude-usage-cost project.

Project overview

This guide covers the dashboard webview in src/extension.ts, media/dashboard.js, and media/dashboard.css. The extension creates a VS Code webview panel, injects a nonce-protected script, posts aggregate data, and the browser script renders cards, gauges, charts, tables, and warnings.

Primary source files

  • src/extension.ts owns showDashboard and getHtml.
  • media/dashboard.js owns rendering and webview message handling.
  • media/dashboard.css owns VS Code theme-token styling.
  • src/types.ts defines the data payload rendered by the webview.

Setup commands

npm install npm run compile npm run check-types npm run package npx esbuild src/selftest.ts --bundle --platform=node --format=cjs --outfile=out/selftest.js node out/selftest.js <transcript-dir>

Change rules

  • Keep enableScripts limited to this webview and keep a nonce on the script tag.
  • Use webview.asWebviewUri for local CSS and JavaScript assets.
  • Escape all model, warning, label, and tooltip text before injecting into innerHTML.
  • Keep command messages narrow: ready, setWindow, setDedupe, refresh, and openSettings.
  • Preserve VS Code theme variables so the dashboard follows user themes.

Testing

Use sample DashboardData payloads for empty data, one model, many models, warnings, cap gauge, daily series, and session data. Test that HTML-like model names and warnings render escaped.

PR checklist

  • Webview CSP remains restrictive.
  • All data-derived HTML is escaped.
  • Dashboard still works after resize and hidden-panel reveal.
  • npm run check-types and npm run compile pass.