AlexandrAI AGENTS.md
agents-md

Codex Token Count Agent Guide

Project-specific AGENTS.md guidance for the Codex Token Count VS Code extension.

AGENTS.md

Guidance for coding agents working on Codex Token Count, a VS Code extension that reads local Codex session logs and shows token usage dashboards.

Project Overview

The extension scans Codex session JSONL logs, aggregates token usage by period, splits input/cached-input/output/reasoning-output categories, deduplicates repeated total snapshots, and displays model-level charts plus an OpenAI API-rate equivalent USD estimate. The estimate is not a subscription billing claim.

Main files:

  • src/extension.ts: VS Code activation, commands, status bar, dashboard lifecycle.
  • src/parser.ts: session JSONL parsing and aggregation.
  • src/parser.test.ts: parser tests.
  • src/pricing.ts: model pricing table and override handling.
  • src/types.ts: shared extension types.
  • media/dashboard.js and media/dashboard.css: webview behavior and styling.
  • esbuild.js: extension bundle build.

Setup Commands

bashnpm install
npm test
npm run check-types
npm run compile
npm run package

The default session directory is configurable through codexTokenCount.sessionsDir; examples should use <codex-sessions-dir> rather than a local home path.

Extension Rules

  • Keep parsing local-only. Do not upload session content.
  • Preserve status bar activation on startup and command activation for dashboard/refresh.
  • Keep duplicate snapshot removal conservative. Prefer retaining the larger complete token snapshot when duplicate message ids appear.
  • Keep pricing overrides additive and explicit; never imply that API-rate estimates equal subscription charges.

VS Code Surface

Contributed commands:

  • codexTokenCount.showDashboard
  • codexTokenCount.refresh

Settings:

  • codexTokenCount.sessionsDir
  • codexTokenCount.autoRefresh
  • codexTokenCount.statusBarMetric
  • codexTokenCount.pricingOverride

If changing settings, update both package.json contribution metadata and runtime handling.

Testing

Use:

bashnpm test
npm run check-types
npm run compile

Parser changes require focused tests in src/parser.test.ts. Pricing changes need cases for default model matches, unknown models, overrides, cached token categories, and long-context fields when applicable.

Security And Privacy

  • Treat session logs as private local telemetry.
  • Do not log raw prompts, responses, or file paths from session content.
  • Keep the dashboard webview content security policy tight.
  • Avoid external webview assets.

Commit And PR Rules

  • Pair parser changes with tests.
  • Pair user-facing setting changes with README updates.
  • Before packaging, confirm the version and VSIX artifact name match the intended release.