Compress AI shell output automatically — zero setup. Install TokenSaver only. TokViz is bundled inside: hooks install silently on startup for Cursor, Copilot, and Gemini/Antigravity. No npm install, no manual commands.
Reduce token waste from verbose terminal output (git diff, test logs, grep results…) by 30–70%. Dashboard + status bar show how many tokens you saved — not how many you spent (that's TokGuess).
What TokenSaver does (and does not)
| Layer | Tool | Role |
|---|---|---|
| Compression | TokViz (bundled) | Hooks shrink shell output before the agent reads it |
| Visibility | TokenSaver | Dashboard + status bar from ~/.tokviz/events.json |
| Usage tracking | TokGuess | Real token counts from Copilot / Claude / Antigravity logs (separate extension) |
TokenSaver does not use RTK or Caveman directly. TokViz is an original implementation inspired by their patterns (shell hooks + optional prose skills).
How it works
flowchart LR
A[AI Agent] -->|runs: git diff| B[TokViz Hook]
B -->|compress| C[50KB → 8KB]
C -->|return| A
C -->|log stats| D[~/.tokviz/events.json]
D -->|read| E[TokenSaver Dashboard]
TokViz layer (automatic, invisible)
On extension startup, TokenSaver:
- Bundles TokViz CLI inside the extension — no npm, no global install
- Detects which agents are present on your machine
- Silently runs
tokviz init -g --agent <name>for each
| Detected | How | TokViz agent |
|---|---|---|
| Cursor IDE | App name or ~/.cursor |
cursor |
| GitHub Copilot | Extension or ~/.copilot/session-state |
copilot |
| Gemini / Antigravity | ~/.gemini or Antigravity brain paths |
gemini |
| Claude Code | ~/.claude/projects |
no hooks yet — use TokGuess for usage |
Hooks are written to:
- Cursor:
~/.cursor/hooks.json - Copilot:
~/.copilot/hooks/tokviz-tracker.json - Gemini:
~/.gemini/hooks.json
When an agent runs git diff, npm test, or any shell command in Agent mode, TokViz compresses the output and logs savings to ~/.tokviz/events.json.
TokenSaver layer (what you see)
- Sidebar dashboard — total saved, today, per-agent breakdown
- Status bar —
⚡ -12.6K tokens (38%) - Live refresh — file watcher on
~/.tokviz/events.json
Quick Start
Zero-setup (default)
- Install the extension (VS Code marketplace or
.vsix) - Reload the window
- Use your AI agent in Agent mode
That's it. No commands, no npm, no TokViz install.
code --install-extension tokensaver-0.4.0.vsix
Manual re-enable (optional)
If auto-detection missed an agent:
TokenSaver: Enable Token Tracking
Pick cursor, copilot, or gemini, then reload the window.
Commands
| Command | Description |
|---|---|
TokenSaver: Show Dashboard |
Open savings dashboard |
TokenSaver: Refresh |
Reload stats from disk |
TokenSaver: Enable Token Tracking |
Manually install hooks for an agent |
Settings
| Setting | Default | Description |
|---|---|---|
tokensaver.showStatusBar |
true |
Show savings in the status bar |
Requirements
- VS Code 1.85.0+
- Cursor, GitHub Copilot, Gemini CLI, or Antigravity CLI (at least one)
- Agent mode — manual terminal commands do not trigger hooks
How much can you save?
| Command | Before | After | Saved |
|---|---|---|---|
git diff |
50KB (~12.5K tokens) | 8KB (~2K tokens) | ~84% |
cargo test |
120KB (~30K tokens) | 15KB (~3.8K tokens) | ~87% |
npm run build |
80KB (~20K tokens) | 12KB (~3K tokens) | ~85% |
Numbers are estimates (~4 chars/token). Good for relative savings, not exact billing.
Troubleshooting
Dashboard shows no data?
- Use Agent mode (not the integrated terminal you type into)
- Reload VS Code after first install
- Check
~/.tokviz/events.jsonhas entries - Run
tokviz doctorif you have the CLI globally, or use Enable Token Tracking
Hooks not installed?
Check ~/.tokviz/cli-path points to the bundled CLI. Re-run Enable Token Tracking and reload.
Claude detected but no compression?
TokViz hooks are not available for Claude Code yet. Use TokGuess for Claude token visibility.
Development
git clone https://github.com/maazizit/tokensaver
cd tokensaver
npm install
npm run prepare-cli # copies CLI from sibling tok-viz repo
npm run compile
# F5 → Extension Development Host
Market research
We studied the landscape before building — Market Benchmark covers Eating Token, TokenLens AI, RTK, Caveman, and where TokenSaver + TokGuess fit. (Yes, there is a spreadsheet. Yes, the cat approved it.)
Related projects
- TokViz — compression engine (bundled inside TokenSaver)
- TokGuess — token usage dashboard for Copilot / Claude / Antigravity
- RTK — inspiration for shell compression pattern
- Caveman — inspiration for prose compression pattern
Credits
Built by Zahra Maaziz · Powered by TokViz
License
MIT