VS Code Status Extension
Relevant source files
The following files were used as context for generating this wiki page:
The VS Code Status Extension is a visualization tool designed to surface critical health metrics, context efficiency, and usage limits from AI coding assistants like Claude Code and GitHub Copilot directly into the VS Code status bar. Its primary purpose is to provide real-time visibility into the "context health" of a session, helping developers avoid context window waste and stay within API usage limits.
The extension functions by reading cache files generated by the token-optimizer core logic. It acts as a lightweight companion to the terminal-based optimization tools, bridging data such as token fill percentages, quality grades, and rate limit resets into the IDE workspace.
Sources: vscode-extension/package.json:3-5, skills/token-optimizer/scripts/statusline.js:1-12
Architecture and Data Flow
The extension operates on a decoupled architecture where a background script (statusline.js) acts as a bridge between the AI runtime (Claude or Copilot) and the VS Code UI. The status line logic is installed via measure.py and periodically writes authoritative state to a global sidecar cache directory located at ~/.claude/token-optimizer/.
Component Relationships
The following diagram illustrates how the VS Code extension interacts with the underlying scripts and cache files.
The diagram shows the data flow from AI runtimes through the bridge script to JSON cache files, which are then consumed by the VS Code UI.
Sources: skills/token-optimizer/scripts/statusline.js:14-110, vscode-extension/package.json:44-60
Data Synchronization
The extension relies on specific JSON files to maintain an up-to-date view of the user's session. These files are updated by various hooks and core scripts within the token-optimizer system.
Key Cache Files
| File Name | Source | Purpose |
|---|---|---|
live-fill.json | statusline.js | Contains current context window used percentage and timestamp. |
rate-limits.json | statusline.js | Bridges account-global usage limits (5h/7d) to the extension. |
quality-cache-*.json | Hooks/measure.py | Stores session-specific quality scores, grades, and compaction counts. |
settings.json | ~/.claude/ | Used to read the effortLevel (low, medium, high) for display. |
Sources: skills/token-optimizer/scripts/statusline.js:68-150, skills/token-coach/SKILL.md:140-155
Rate Limit Bridging
Because rate limits are account-wide and often only available in specific API responses, the statusline.js script "bridges" this data to a sidecar file. This allows the VS Code extension to show reset times and usage percentages without having its own direct connection to the AI provider's API.
Sources: skills/token-optimizer/scripts/statusline.js:93-115
Configuration and Commands
The extension provides several configuration options to control which runtime data is displayed and how frequently it is considered stale.
Configuration Options
| Property | Type | Default | Description |
|---|---|---|---|
tokenOptimizer.runtime | string | auto | Determines whether to read from Claude, Copilot, or detect automatically. |
tokenOptimizer.staleAfterSeconds | number | 180 | Seconds before usage data is flagged as cached/stale. |
Sources: vscode-extension/package.json:54-72
Integrated Commands
Users can interact with the system through three primary commands:
- Show Status Panel: Opens a detailed view of the current context health.
- Open Dashboard: Launches the full web-based Token Optimizer dashboard.
- Refresh Now: Forces a local transcript estimate and re-reads cache files.
Sources: vscode-extension/package.json:45-53
Visual Indicators and Metrics
The extension's output is designed to be high-density, often displaying two rows of information in terminal environments or summarized icons in VS Code.
Status Bar Metrics
- Context Health (ContextQ): A grade (S, A, B, C, D, F) and score (0-100) based on the
resource_healthmetric. - Session Efficiency (Eff): A grade reflecting how effectively tokens are being used relative to the task.
- Context Bar: A visual bar indicating used percentage with degradation-aware colors (Green < 50%, Yellow < 70%, Orange < 80%, Red 80%+).
- Compaction Count: Shows how many times the session has been compacted and the estimated context loss (e.g.,
Compacts:2(~88% lost)). - Usage Limits: Real-time tracking of 5-hour and 7-day usage windows with reset timers (e.g.,
5h:45% ↺3:30p).
Sources: skills/token-optimizer/scripts/statusline.js:25-60, skills/token-optimizer/scripts/statusline.js:155-220
Staleness Protection
To ensure accuracy, the extension implements a staleness guard. If the quality cache is older than 5 minutes, the score is prefixed with a ~ character and dimmed, indicating that the displayed data may not reflect the most recent activity.
Sources: skills/token-optimizer/scripts/statusline.js:160-175
Conclusion
The VS Code Status Extension serves as the primary observability layer for the Token Optimizer project. By surfacing complex metrics like compaction loss, prompt cache hit rates, and multi-model usage trends into the status bar, it enables developers to maintain high-quality, cost-effective AI sessions without leaving their primary development environment.
Sources: skills/token-coach/SKILL.md:40-60, vscode-extension/package.json:3-10