Compressor — AI Token Savings (VS Code)

Companion extension for compressor: compressed read/search/outline tools for Copilot agent mode, a savings ticker/report over the compressor ledger (~/.compressor/ledger, override with COMPRESSOR_LEDGER_DIR), and manage commands for instruction packs. No network calls.

Features

• Three language-model tools for Copilot agent mode, all confined to the open workspace folders and all recording worthwhile compressions to the ledger as agent vscode:
  • #compressorRead — reads a file through the engine: comment-stripping that preserves line numbers, repeated-line dedupe, and recoverable [compressor:] markers stating the exact offset/limit to retrieve omitted lines. Pass offset/limit for an exact uncompressed range.
  • #compressorSearch — workspace text/regex search returning compressed grep-style results (file, line, match). Accepts isRegex, ignoreCase, an include glob, and maxResults. Find where something is used without reading whole files.
  • #compressorOutline — a file's imports and signatures with bodies collapsed into recoverable markers (TypeScript/JavaScript, Rust, Python, Go). Understand a large file's shape cheaply, then expand a body with #compressorRead.
• Copilot steering — Compressor: Enable/Disable Copilot Steering installs/removes three extension-owned files. VS Code has no API to force tool choice or override the built-in read, and instructions don't route tools, so the deterministic lever is a tools: allowlist that omits the built-in read:
  • .github/agents/compressor.agent.md — a custom agent ("compressor") whose toolset is the compressor read/search/outline tools plus edit, with the built-in read/codebase-search left out. Pick it from the Chat agents dropdown and every read in that session goes through the compressor tools.
  • .github/prompts/compressor.prompt.md — the /compressor prompt, the same scoping for one-shot tasks.
  • a marker-fenced section in .github/copilot-instructions.md — a best-effort nudge for the default agent (instructions are advisory for tool routing, so this alone is unreliable; the agent/prompt are the real lever). It is fenced in distinct compressor-vscode:steering comments so it updates and removes cleanly and coexists with a compressor init pack section in the same file.
• Ticker (status bar): ≈12.3k tok saved (30d) — estimated tokens saved in the configured window. Chars are exact; token figures are estimates from the cheap estimator, never billable counts. Click it for the report.
• Compressor: Show Savings — the savings report (by day / agent / tool / mode) in a webview, themed to the active color scheme. Static HTML, scripts disabled. Optionally (set compressor.showActualUsage, off by default) appends an actual-usage section parsed from this project's Claude Code session transcripts (~/.claude) — authoritative token counts, clearly labeled not savings and not billable dollars (Claude Code only).
• Mode indicator (status bar): $(fold) compressor: <mode> — click to switch the read tool's compression mode without the command palette.
• Compressor: Count Tokens — exact chars and an estimated token count for the active file or selection (chars/3.5; never billable).
• Compressor: Preview Compression — runs the engine over the active file or selection exactly as compressor_read would and opens a side-by-side diff (numbered original vs compressed). No file writes.
• Compressor: Status — per-adapter install status for the first workspace folder, steering state, and ledger recency.
• Compressor: Init / Set Instruction-Pack Mode / Uninstall — plan instruction-pack changes with the library adapters, review the rendered diff, confirm, apply. Changed files are backed up first (under ~/.compressor/backups) — undo from a terminal with compressor restore. claude-code/copilot (hook-bearing) are offered only when compressor-hook resolves on PATH; otherwise use the compressor CLI.

Settings: compressor.savingsWindow (7d | 30d | all, default 30d), compressor.mode (full | optimized | slim, default optimized — the read tool's compression mode; full = passthrough), and compressor.showActualUsage (default false — show the Claude Code transcript usage section in the report).

Try it

New install? Open the Get started with Compressor walkthrough (VS Code Welcome page, or run Welcome: Open Walkthrough).

After Compressor: Enable Copilot Steering, the strongest path is to pick the compressor agent from the Chat agents dropdown (or run /compressor) — the built-in read is out of scope there, so the agent must use the compressor tools. You can also #-reference them explicitly in any agent-mode chat:

Read #compressorRead src/server/router.ts and explain the route table.

Summarize the failures in #compressorRead logs/test-run.txt — just the failing
assertions and the final count.

In the default agent the model only tends to pick compressor_read on its own (no API forces it); the compressor agent and /compressor make it deterministic. More examples and the full command list are in docs/USAGE.md.

What it does NOT do

• It cannot compress VS Code Copilot's built-in tool output. VS Code hooks cannot replace tool output (doc-verified 2026-06-12); in-IDE compression happens only when the agent uses #compressorRead. Instruction packs reach Copilot via .github/copilot-instructions.md / AGENTS.md — see the compressor docs.
• It makes no network calls and reads no file contents beyond the ledger JSONL, this project's Claude Code session transcripts (for the usage report), and files explicitly requested through compressor_read / the preview and count commands.
• It shows no percentage claims; measured savings come from compressor benchmark, not this view.

Install

From the VS Code Marketplace — search "Compressor — AI Token Savings" in the Extensions view, or from a terminal:

code --install-extension aStudioPlus.compressor-vscode

Or build and install the VSIX locally:

npm run package            # produces compressor-vscode-<version>.vsix
code --install-extension compressor-vscode-<version>.vsix

Usage guide and example prompts: docs/USAGE.md.

Development

Requires VS Code ≥ 1.95 (LanguageModelTool API) and a built ../compressor checkout next to this directory (the library is a file: dependency):

(cd ../compressor && npm install && npm run build)
npm install
npm run typecheck
npm run build      # esbuild bundle → out/extension.js
npm test           # vitest ('vscode' is aliased to a local mock)
npm run package    # vsce → .vsix