AlexandrAI AGENTS.md
agents-md

Codex Token Webview Dashboard Agent Guide

Agent guide for Codex Token Count webview message handling, escaping, CSP, charts, and tables.

AGENTS.md

Guidance for coding agents working on Codex Token Webview Dashboard in the codexTokencount project.

Project overview

This guide covers the VS Code webview in src/extension.ts plus media/dashboard.js and media/dashboard.css. The dashboard renders cards, rate-limit meters, token and cost split bars, daily charts, project tables, model tables, and warnings from DashboardData.

Primary source files

  • src/extension.ts owns showDashboard and getHtml.
  • media/dashboard.js owns message handling and rendering.
  • media/dashboard.css owns VS Code theme-token styling.
  • src/types.ts defines DashboardData.

Setup commands

npm install npm test 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 <sessions-dir>

Change rules

  • Keep webview scripts behind a nonce and a restrictive CSP.
  • Use webview.asWebviewUri for local dashboard assets.
  • Escape all model, project, warning, label, and tooltip text before using innerHTML.
  • Keep the message protocol narrow: ready, setWindow, refresh, and openSettings.
  • Preserve resize rerendering so charts stay correctly sized.

Testing

Use fixture DashboardData for empty data, many models, many projects, warnings, rate limit snapshots, daily series, and untrusted text. Verify escaping and project detail toggle behavior.

PR checklist

  • No dashboard data field is injected without escaping.
  • VS Code theme variables still drive visual styling.
  • npm test, npm run compile, and npm run check-types pass.