AI Token Optimizer

A VS Code extension that reduces token consumption for Claude Code, GitHub Copilot, and OpenAI Codex by injecting token-efficiency instructions into the config files those tools already read, installing the supporting CLI tools, and wiring up MCP servers — automatically, on workspace open.

The extension has zero runtime dependencies (devDependencies only). Everything is written against Node's fs/child_process APIs and the vscode API.

Table of Contents

• How It Works
• The Five Strategies (CAP-1 – CAP-5)
• Profiles
• Semantic Answer Cache (MCP Server)
• Telemetry & Dashboard
• Commands
• Settings
• Installation
• Development
• Architecture
• Observability Honesty Rule
• Contributing
• Owners
• License

How It Works

The extension activates on onStartupFinished and runs an auto-apply pass:

1. Generate instruction files — writes CAP-1 – CAP-5 rules into whichever AI tool config files are targeted:

   File	Read by
   .github/copilot-instructions.md	GitHub Copilot
   CLAUDE.md	Claude Code
   .codex/instructions.md	OpenAI Codex

2. Install supporting tools — checks for and (with your consent) installs the real CLI tools the instructions reference.

3. Configure MCP servers — writes context7, codegraph, and token-cache server entries into .vscode/settings.json and the Claude MCP config.

4. Start the CodeGraph watcher — watches source files per configured project, debounces 30s, then runs codegraph init (first run) or codegraph sync (incremental).

5. Show status — a status bar item reflects the active profile and strategy count.

Marker-based merge, never overwrite

Only the content between these markers is managed by the extension:

<!-- AI-TOKEN-OPTIMIZER:START -->
   ... managed block ...
<!-- AI-TOKEN-OPTIMIZER:END -->

Anything you write outside the markers is preserved untouched. If the markers are absent, the block is appended to the end of the file. Setting preserveExistingInstructions to false overwrites the whole file instead.

Graceful degradation

If the codegraph or rtk binaries aren't installed, instruction files are still generated with full CAP guidance (telling the AI to invoke those commands directly). Nothing hard-fails activation because a binary is missing.

The Five Strategies (CAP-1 – CAP-5)

RTK is hooks, not MCP. The MCP configurator actively deletes any stray rtk MCP entry it finds — RTK integrates through the PreToolUse hook, not through MCP.

Installing CodeGraph and exposing it over MCP are two separate steps. The npm install puts the codegraph binary on $PATH; adding the MCP server entry is what lets Copilot/Claude actually call codegraph_explore. Both must happen.

Task-type routing

The generated instructions also teach the AI when to downshift models:

• Lightweight (use a lighter model): file navigation, renames/moves, formatting and lint fixes, boilerplate from templates, docs lookups.
• Full-power (keep the current model): architectural decisions, multi-file debugging, security review, performance work, multi-step refactors.

Profiles

Profiles gate which strategies are active — strategy behavior is never hardcoded in generators, it always flows through getEffectiveStrategies(profile).

Switch profiles from the status bar (⚡ Full (5/5)) or via AI Token Optimizer: Select Optimization Profile.

Standing constraints

Regardless of profile, the generated instructions state:

• Never compress error messages, stack traces, or security warnings.
• Disable output compression during active debugging.
• Disable verbosity control during architectural planning.
• Re-index CodeGraph after significant code changes.

Semantic Answer Cache (MCP Server)

The token-cache MCP server (src/mcp-server/cache-server.ts, bundled to dist/cache-server.js) is a standalone stdio JSON-RPC 2.0 server launched by your AI tool as node cache-server.js <workspaceRoot>. It never imports vscode.

Tools it exposes:

Matching is exact-key first, then fuzzy: queries are lowercased, camelCase-split, stopword-filtered and lightly stemmed, then compared with IDF-weighted cosine (≥ 0.7) and Jaccard (≥ 0.5). Single-token queries are exact-match only, by design — one shared token would otherwise match every question on that topic.

Staleness is scope-driven:

• scope: "code" (default) — the entry records the git HEAD it was stored at; when HEAD moves, hits come back stale: true so the AI verifies before reusing.
• scope: "durable" — concept explanations and how-tos that don't depend on code state; never go stale.

Storage lives at .aicache/semantic-cache.json, capped at 300 entries / 1 MB, with entries evicted 14 days after last access. Clear it any time with AI Token Optimizer: Clear Semantic Cache.

Answers about uncommitted or actively changing code should not be cached — the generated instructions say so explicitly.

Telemetry & Dashboard

AI Token Optimizer: Show Savings Dashboard opens a webview (scripts disabled — all charts are static inline SVG) with:

• Repository Intelligence — real structural facts read straight from .codegraph/codegraph.db via the sqlite3 CLI: files, directories, classes, interfaces, enums, methods, functions, graph nodes, graph relationships, index size, and per-language file counts. When sqlite3 isn't available it falls back to codegraph status totals.
• Modeled savings estimate — a whole-repo baseline vs. graph-scoped-slice comparison. Always tagged modeled: true and labeled as an estimate in the UI.
• Real RTK savings — read from rtk gain --format json --all --project: total commands, input/output tokens, tokens saved, average savings %. These are actual recorded usage, not a benchmark.
• Cache stats — entries, lifetime hits, estimated tokens saved.
• Growth trends — the persisted history windowed into 24h / 7d / 30d / lifetime, rendered as sparklines. These trends are real repository growth, not inferred LLM data.

Snapshots persist to .aicache/telemetry/ (a latest snapshot plus an append-only history.jsonl).

Export via AI Token Optimizer: Export Telemetry in JSON, CSV, or Markdown. Excel and PDF are intentionally omitted — both need third-party runtime libraries this extension forbids, and CSV opens directly in Excel/Sheets.

Disable collection entirely with aiTokenOptimizer.telemetry.enabled: false.

Commands

Status bar

The ⚡ Full (5/5) item shows the active profile and how many strategies are live. Click it to switch profiles. It turns amber when fewer than five strategies are active, and reads ⚡ Token Opt: OFF when the extension is disabled. Hover for a per-strategy ✓/✗ breakdown.

Settings

Installation

Requirements

• VS Code 1.85.0+
• Node.js (for the global npm install of CodeGraph)
• At least one AI coding tool: GitHub Copilot, Claude Code, or Codex
• Optional: Homebrew (macOS) for RTK — otherwise the upstream install script is used
• Optional: sqlite3 CLI for the full telemetry breakdown (falls back to codegraph status totals without it)

From VSIX

code --install-extension ai-token-optimizer-0.1.0.vsix

From source

git clone https://github.com/sbaala/ai-token-optimize-vscode.git
cd ai-token-optimize-vscode
npm install
npm run build
npx vsce package
code --install-extension ai-token-optimizer-0.1.0.vsix

Tools installed by the extension

Both are installed only after you confirm the prompt.

Development

npm install          # install dependencies
npm run watch        # esbuild watch mode → dist/extension.js
npm run build        # production build (minified, no sourcemaps)
npm run compile      # tsc -p ./ — type-checks src/ and test/ (required before npm test)
npm run lint         # eslint src --ext ts
npm run compile && npm test   # compile, then run the VS Code integration suite
npm run package      # vsce package → .vsix

Press F5 in VS Code to launch the Extension Development Host for manual testing.

Testing note: there's no single-test filter. npm test runs dist/test/suite/index.js (Mocha, via @vscode/test-electron), which downloads and launches a VS Code instance and runs every suite under test/suite/. To iterate on one suite, temporarily narrow the files glob in test/suite/index.ts or .only() a suite()/test() block.

Templates: templates/*.md hold the raw markdown fragments the generators assemble. Change wording there rather than hunting for inline strings in generator code.

Architecture

src/
├── extension.ts              # Entry point — activation, commands, auto-apply
├── config.ts                 # Configuration + profile → strategy mapping
├── constants.ts              # Markers, paths, tool install entries, descriptions
├── cache/
│   ├── store.ts              # SemanticCacheStore — disk-backed answer cache
│   ├── similarity.ts         # Tokenization, IDF, cosine + Jaccard matching
│   ├── callLog.ts            # MCP tool call log
│   └── ttlCache.ts           # Small TTL memoizer (e.g. `which` lookups)
├── mcp-server/
│   └── cache-server.ts       # Standalone token-cache MCP stdio server
├── generators/
│   ├── base.ts               # Abstract generator + marker merge logic
│   ├── copilot.ts            # .github/copilot-instructions.md
│   ├── claude.ts             # CLAUDE.md
│   ├── codex.ts              # .codex/instructions.md
│   └── index.ts              # Orchestration
├── installer/
│   ├── installer.ts          # Binary detection + consented install
│   ├── packageManager.ts     # npm/yarn/pnpm detection
│   └── index.ts
├── mcp/
│   ├── configurator.ts       # Writes context7/codegraph/token-cache entries; removes stray rtk
│   └── index.ts
├── session/
│   └── tracker.ts            # Per-window session stats
├── strategies/
│   ├── codegraph.ts          # File watcher, debounced init/sync, status
│   ├── validator.ts          # Verifies all five CAPs are actually active
│   ├── measurement.ts        # Real vs. unobservable measurement boundary
│   ├── rtkGain.ts            # Parses `rtk gain --format json`
│   └── index.ts
├── telemetry/
│   ├── repositoryCollector.ts # Tier-A: real metrics from codegraph.db
│   ├── codegraphDb.ts        # sqlite3 CLI access layer
│   ├── estimator.ts          # Modeled savings estimate (always tagged modeled)
│   ├── store.ts              # Latest snapshot + append-only history.jsonl
│   ├── analytics.ts          # 24h/7d/30d/lifetime windowing
│   ├── sparkline.ts          # Static inline SVG trends
│   ├── export.ts             # JSON / CSV / Markdown serialization
│   ├── types.ts
│   └── index.ts
└── ui/
    ├── statusBar.ts          # Profile + strategy-count indicator
    ├── quickPick.ts          # Profile / strategy picker
    ├── projectPicker.ts      # Multi-repo index scoping
    ├── dashboard.ts          # Webview (scripts disabled, static SVG)
    └── exportTelemetry.ts    # Export command driver

Full data-flow and sequence diagrams for activation, the installer, MCP configuration, and the CodeGraph watcher live in ARCHITECTURE.md — read that before making non-trivial changes to those paths.

Observability Honesty Rule

This extension is not in the LLM request path. The actual model call and CodeGraph retrieval happen inside Copilot / Claude Code / Codex, which it cannot instrument. Therefore:

• Per-request LLM metrics (prompt/completion tokens, latency, cost) and per-query retrieval metrics are not observable and are never fabricated.
• Real numbers are read from local state (codegraph.db, rtk gain, the cache store) and reported as measured.
• Unobservable numbers are reported as null / n/a.
• Anything derived from assumptions is tagged modeled and labeled as an estimate in the UI and in exports.

Preserve this distinction in any contribution — do not turn an estimate into a number that reads as measured.

Contributing

1. Branch off main — direct pushes to main are blocked.
2. Open a pull request. At least one approving review is required before merge.
3. Run npm run lint and npm run compile && npm test before requesting review.
4. Keep the architectural rules above intact: marker-based merge, profiles gating strategies, RTK-via-hooks (never MCP), graceful degradation, and the observability honesty rule.

Owners

Credits & Acknowledgments

The concept and approach behind this extension were inspired by the token-optimization techniques presented in this video:

📺 Watch on YouTube

Full credit to the original creator for the ideas that shaped these strategies. This extension packages those techniques into an automated VS Code workflow.

It also builds on these open-source tools:

• CodeGraph (@colbymchenry/codegraph) — semantic code-graph indexing (CAP-1)
• RTK — CLI output compression, Apache 2.0 (CAP-2)

License

MIT