MCP server that saves 70-95% tokens for AI coding assistants — without losing functionality.
TokenJar sits between your AI coding assistant and your codebase, intelligently compressing code reads, terminal outputs, and file operations to dramatically reduce token consumption, context compaction, and latency.
Works with Claude Code, Cursor, Antigravity (AGY), Windsurf, Continue.dev, and any MCP-compatible AI assistant.
✨ Features & Architecture
| Module | What It Does | Token Savings |
|---|
| 🦴 Code Skeletonizer | Extracts structural skeleton (signatures, types, docstrings) via Tree-sitter AST | 80-95% |
| 📖 Smart File Reader & Slicing Cache | L1 RAM + L2 Persistent SQLite cache with targeted line/symbol slicing (#L1-30) & auto-paging ceiling (MAX_OUTPUT_LINES = 80) | 90-99.8% |
| 🛡️ Lockfile & Asset Shield | Intercepts massive lockfiles & minified bundles with surgical version queries (query="react") | 99% |
| 🎯 Blast Radius & Hybrid Fuzzy Symbols | Instant global symbol lookup with AST parser and fuzzy Levenshtein + Trigram fallback suggestions (find_symbol_global) | 85-95% |
| 🖥️ Terminal Pruner | Compresses test/build/git terminal streams, keeps errors and summary info | 60-90% |
| 🗺️ Repo Map | PageRank & Graph Centrality codebase overview fitted into custom token budgets | Budget-fitted |
| 🔄 Post-Update Auto-Sync | Automatically syncs IDE configs, slash commands, and project rules in a single command (tokenjar update) | Zero-maintenance |
| 🧹 Zero-Trace Surgical Uninstall | Safely reverts IDE configs, purges caches, and cleans rules without touching user code | Safe & Zero-trace |
| 🎨 On-Demand UI Dashboard | Lightweight standalone control panel (tokenjar ui) with Zero Background RAM | Instant |
🛡️ Built-in Guardrails & Reliability
- Lockfile & Giant Asset Shield: Prevents context window destruction from 50,000-line lockfiles; supports 5-line surgical version queries.
- L1 RAM + L2 SQLite Persistent Cache: Survives MCP server restarts and IDE reboots (
~/.tokenjar/cache.db with WAL mode).
- Fallback Safety Guard: If a test or command fails (
exit_code != 0), TokenJar guarantees tracebacks and error contexts are preserved intact.
- Tiny File Anomaly Guard: If a diff header would consume more tokens than the file itself, the full content is returned to prevent token inflation.
- Runaway Stream Protection: Protects host memory from infinite loops by capping raw terminal buffers at 2MB with graceful truncation.
- SQLite Database Bloat Guard: Files larger than 5MB are cached by hash reference without bloating disk space.
🚀 Quick Start & Installation (v1.1.0 GA)
TokenJar is distributed in two official editions:
- 🦀 Rust Native Engine (Recommended): High-performance, self-contained single binary with microsecond AST, 14 MB RAM, and zero Python dependencies.
- 🐍 Python Edition: Pure Python FastMCP package for pip and virtual environments.
💡 Recommended Workflow (Best Practice — 3 Simple Steps)
[!TIP]
Prevent broken paths when cleaning temporary files:
- Place in a Permanent Folder: If downloading the standalone binary or zip manually, extract
tokenjar into a permanent, safe directory that won't be accidentally deleted (e.g. C:\Users\<username>\.tokenjar\bin on Windows or ~/.local/bin on Linux/macOS). Avoid temporary folders like Downloads or Temp. (Note: The 1-click terminal scripts in Option 1 handle this placement automatically).
- Run One-Time Install: Open a terminal in that folder and run:
tokenjar install
This automatically adds TokenJar to your system PATH, configures MCP across all detected AI assistants (Cursor, Claude Desktop, Antigravity, Windsurf, Claude Code), and sets up slash commands.
- Activate in Your Project (CLI Recommended): Open a terminal in your project repository and run:
tokenjar on
(Running tokenjar on directly in your terminal/CLI is strongly recommended over typing /tokenjar on in the chat, as it creates rules before the assistant session starts and consumes zero conversation tokens). This injects repository steering rules (AGENTS.md) so your assistant automatically routes through TokenJar's token-saving MCP tools from turn 1.
📥 1-Click Direct Downloads (Precompiled Binaries)
Click your operating system below to download the latest v1.1.0 release:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
