https://github.com/anvanster/compressor-vscode
Save tokens in GitHub Copilot agent mode: compressed read/search/outline tools, a savings ticker and report, and instruction-pack management for the compressor toolchain. No network calls.
https://github.com/anvanster/compressor-vscode
ai-coding-assistant claude context-compression copilot developer-tools github-copilot language-model-tools llm token-optimization vscode vscode-extension
Last synced: 22 days ago
JSON representation
Save tokens in GitHub Copilot agent mode: compressed read/search/outline tools, a savings ticker and report, and instruction-pack management for the compressor toolchain. No network calls.
- Host: GitHub
- URL: https://github.com/anvanster/compressor-vscode
- Owner: anvanster
- License: mit
- Created: 2026-06-13T18:42:50.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-13T19:40:04.000Z (about 1 month ago)
- Last Synced: 2026-06-13T21:10:44.448Z (about 1 month ago)
- Topics: ai-coding-assistant, claude, context-compression, copilot, developer-tools, github-copilot, language-model-tools, llm, token-optimization, vscode, vscode-extension
- Language: TypeScript
- Size: 144 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Compressor — AI Token Savings (VS Code)
[](https://marketplace.visualstudio.com/items?itemName=aStudioPlus.compressor-vscode)
Companion extension for
[compressor](https://github.com/anvanster/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: ` — 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`](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](https://github.com/anvanster/compressor).
- 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](https://marketplace.visualstudio.com/items?itemName=aStudioPlus.compressor-vscode)
— search **"Compressor — AI Token Savings"** in the Extensions view, or from a
terminal:
```sh
code --install-extension aStudioPlus.compressor-vscode
```
Or build and install the VSIX locally:
```sh
npm run package # produces compressor-vscode-.vsix
code --install-extension compressor-vscode-.vsix
```
Usage guide and example prompts: [`docs/USAGE.md`](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):
```sh
(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
```