Load Cache Data

Load Cache Data Skill

Use --json for output; don't pretty-print or write extra files — this data feeds analysis, not display.

This skill helps you access and inspect the AI Engineering Fluency's local session file cache. The cache stores pre-computed statistics for session files to avoid re-processing unchanged files.

Overview

The extension maintains a local cache of session file statistics in VS Code's globalState. This cache contains:

• Token counts (total and per-model)
• Interaction counts
• Model usage breakdowns
• File modification times (for cache validation)
• Usage analysis data (tool calls, mode usage, context references)

When to Use This Skill

Use this skill when you need to:

• Inspect cached session file data
• Debug cache behavior or validation logic
• Understand what data is being cached
• Work with real cached data for testing or development
• Iterate on features that rely on cached statistics

Cache Structure

The cache is stored in VS Code's global state under the key 'sessionFileCache'. Each cache entry is keyed by the absolute file path and contains:

interface SessionFileCache {
  tokens: number;                      // Total token count
  interactions: number;                // Number of interactions
  modelUsage: ModelUsage;              // Per-model token breakdown
  mtime: number;                       // File modification timestamp
  usageAnalysis?: SessionUsageAnalysis; // Detailed usage statistics
  subAgentCalls?: number;               // Sub-agent/delegation tool calls (absent when 0)
}

interface ModelUsage {
  [model: string]: {
    inputTokens: number;
    outputTokens: number;
  };
}

interface SessionUsageAnalysis {
  toolCalls: ToolCallUsage;            // Tool usage statistics
  modeUsage: ModeUsage;                // Mode distribution
  contextReferences: ContextReferenceUsage; // Context reference counts
  mcpTools: McpToolUsage;              // MCP tool usage
}

Location

Cache Storage: VS Code globalState → 'sessionFileCache'

• Accessed via: context.globalState.get<Record<string, SessionFileCache>>('sessionFileCache')
• Persisted automatically by VS Code
• Lives in VS Code's internal database (state.vscdb)

Implementation: src/extension.ts (see CacheManager in src/cacheManager.ts below for the actual persistence logic)

How to Access the Cache

From Within the Extension

The cache can be accessed through the extension's context at runtime:

// Load cache from global state
const cacheData = context.globalState.get<Record<string, SessionFileCache>>('sessionFileCache');
const cacheEntries = Object.entries(cacheData || {});

// Get last 10 entries (sorted by modification time)
const last10 = cacheEntries
  .sort((a, b) => (b[1].mtime || 0) - (a[1].mtime || 0))
  .slice(0, 10);

// Display cache entries
for (const [filePath, cacheEntry] of last10) {
  console.log({
    file: filePath,
    tokens: cacheEntry.tokens,
    interactions: cacheEntry.interactions,
    modelUsage: cacheEntry.modelUsage,
    lastModified: new Date(cacheEntry.mtime).toISOString()
  });
}

Using the Provided Script

This skill includes an executable script that loads and displays actual cache data from disk:

Location: .github/skills/load-cache-data/load-cache-data.js

Usage:

# RECOMMENDED: Always use --json for raw JSON output
node .github/skills/load-cache-data/load-cache-data.js --json

# Show last N entries as JSON (default is 10)
node .github/skills/load-cache-data/load-cache-data.js --last 5 --json

# Show help
node .github/skills/load-cache-data/load-cache-data.js --help

Note: The script supports human-readable output without --json, but for LLM skills, always use --json to get structured data.

What it does:

• Searches for cache export files in known locations
• Reads actual cache data if a file exists
• Displays cache entries sorted by most recent modification
• Shows detailed token counts, model usage, and usage analysis

Cache File Locations:

The script searches for cache export files in these locations:

1. VS Code globalStorage: %APPDATA%\Code\User\globalStorage\rajbos.copilot-token-tracker\cache.json (Windows)
   • Also checks other VS Code variants (Insiders, Cursor, VSCodium, etc.)
2. Temp directory: %TEMP%\copilot-token-tracker-cache.json
3. Current directory: ./cache-export.json

Creating Cache Export Files:

Since the extension stores cache in VS Code's globalState (internal SQLite database), the cache data must be explicitly exported to one of the above locations for this script to access it. This can be done:

1. Via Extension: The extension can be enhanced to export cache on demand
2. Via Tests: Test code can write cache data to disk for inspection
3. Manually: Copy cache data from extension's globalState and save to one of the expected locations

Exit Codes:

• 0: Cache file found and displayed successfully
• 1: No cache file found

Note: If no cache file is found, the script will display the searched locations and instructions for exporting cache data.

Cache Management Methods

All cache persistence and validation logic lives in CacheManager (src/cacheManager.ts), not extension.ts — extension.ts only holds a thin private trySaveCacheToStorage() wrapper that delegates to it.

Loading Cache

Method: CacheManager.loadCacheFromStorage() Location: src/cacheManager.ts

Loads the cache from the shared on-disk snapshot file (not VS Code's global state — the cache moved off globalState to avoid its ~2-3 MB size warning):

const snapshotPath = this.getSharedSnapshotPath(); // globalStorageUri/cache_<id>.snapshot.json
const content = await fs.promises.readFile(snapshotPath, 'utf-8');
const envelope = JSON.parse(content);
// ...validates schema/cache version, then populates this.sessionFileCache

Saving Cache

Method: CacheManager.trySaveCacheToStorage() Location: src/cacheManager.ts

Writes the shared on-disk snapshot, guarded by a cross-window file lock so concurrent VS Code windows never corrupt each other's write. Returns false (never throws) when the lock is held by another window or the write fails, so callers can tell "skipped/failed" from "persisted":

async trySaveCacheToStorage(): Promise<boolean> {
  const acquired = await this.acquireCacheLock();
  if (!acquired) { return false; } // another window holds the lock
  try { return await this.writeSharedSnapshot(); }
  finally { await this.releaseCacheLock(); }
}

Cache Validation

Method: CacheManager.isCacheValid() Location: src/cacheManager.ts

Validates cache entries by comparing both modification time and file size:

isCacheValid(filePath: string, currentMtime: number, currentSize: number): boolean {
  const cached = this.sessionFileCache.get(filePath);
  if (!cached) { return false; }
  return this.policy.isValid(cached, currentMtime, currentSize);
}

Clearing Cache

Method: CacheManager.clearExpiredCache() Location: src/cacheManager.ts

Removes cache entries for files that no longer exist on disk (batched, async, and skips virtual session paths like <db-file>#<session-id> that fs.access() can't validate):

const filesToCheck = Array.from(this.sessionFileCache.keys());
for (const filePath of filesToCheck) {
  if (CacheManager.isVirtualSessionPath(filePath)) { continue; }
  try { await fs.promises.access(filePath); }
  catch { /* only ENOENT/ENOTDIR tombstone the entry — see the method's own doc comment */ }
}