ai-engineering-fluency: Instructions file for GitHub Copilot

VS Code Extension — Architecture & Development Guide

Architecture Overview

The extension's entry point and orchestration live in the CopilotTokenTracker class in vscode-extension/src/extension.ts, which is still very large (see the decomposition status in the repo-root AGENTS.md); supporting logic lives in sibling modules under vscode-extension/src/ and in the shared repo-root src/. Put new logic in a module and call it from there rather than adding it to extension.ts. Its primary function is to track GitHub Copilot token usage by reading and parsing session log files.

• Activation: The extension activates on VS Code startup via the onStartupFinished event in vscode-extension/package.json. The activate function in vscode-extension/src/extension.ts instantiates CopilotTokenTracker.

• Data Source: The core data comes from .json log files generated by the GitHub Copilot Chat extension. The getCopilotSessionFiles method locates these files in the user's OS-specific AppData directory for VS Code (e.g., .../Code/User/workspaceStorage/.../chatSessions and .../Code/User/globalStorage/emptyWindowChatSessions).

• Data Flow:

  1. A timer in the constructor calls updateTokenStats() every 5 minutes.
  2. updateTokenStats() calls calculateDetailedStats() to aggregate data.
  3. calculateDetailedStats() reads all session files found by getCopilotSessionFiles().
  4. For each file, it calculates token counts (estimateTokensFromSession), interactions (countInteractionsInSession), and per-model usage (getModelUsageFromSession).
  5. Token counts are estimated using character-to-token ratios defined in the tokenEstimators class property. This is a key convention.

• Thinking Token Tracking: Models that use extended thinking (e.g., Claude) produce kind: "thinking" response items in session logs. These are tracked separately:

  • estimateTokensFromSession and estimateTokensFromJsonlSession return { tokens, thinkingTokens }. The tokens field is the grand total (input + output + thinking). The thinkingTokens field is a breakdown showing what portion of the total was thinking — it is NOT subtracted from tokens.
  • SessionFileCache stores thinkingTokens alongside tokens.
  • extractResponseData separates responseText and thinkingText so the logviewer can display them independently per turn.
  • getModelUsageFromSession does NOT separate thinking — thinking tokens are counted as outputTokens in the per-model breakdown. This is intentional since it keeps cost estimation simple.
  • Critical invariant: When computing token totals for display (per-turn, per-session, per-period), always include thinking tokens. In the logviewer, totalTokens = input + output + thinking. In stats aggregation, sessionData.tokens already includes thinking. Never subtract thinking from a total.
  • CACHE_VERSION must be bumped when changing how tokens are counted so stale caches are invalidated.