⚡ TokenSafe (tokensafe)

Autonomous Zero-Loss Token Economy & Context Optimizer for AI Coding Agents.
Slashes LLM token costs by 60%–90% with zero quality loss. Built for Google Antigravity, OpenAI Codex, Cursor, Claude Desktop, Z.ai Code, Windsurf & Cline.

🌐 Official Website: https://tokensafe.dev

⚡ 1-Click Universal Install

Connect TokenSafe to all detected AI coding agents on your machine in seconds:

# Option 1: Zero-Install via npx (Recommended for Cursor & Claude Desktop)
npx tokensafe

# Option 2: Python / PyPI
pip install tokensafe && tokensafe

# Option 3: Direct Shell Script (macOS / Linux)
curl -fsSL https://tokensafe.dev/install.sh | bash

🔌 Universal MCP Server Configuration

Connect TokenSafe directly to Claude Desktop (claude_desktop_config.json) or Cursor MCP Settings:

{
  "mcpServers": {
    "tokensafe": {
      "command": "npx",
      "args": ["-y", "tokensafe", "mcp"]
    }
  }
}

🚀 The Breakthrough: How It Saves 60%–90% Tokens

Traditional AI code interactions suffer from massive context bloat:

1. The BPE Token Penalty: Verbose natural language prompts and filler waste 40%–70% of ingress context.
2. Bulk Tool Dumps: Reading whole 800+ line files burns 5,000+ tokens per turn when only 20 lines are needed.
3. Stuck Loops & Bloated Diffs: Terminal git diff and repetitive failed commands spiral context into overflow.

TokenSafe Solves All Three Autonomously:

• Graph-Guided AST Skeletonization: Folds inactive function bodies into signatures, keeping target functions and 1-hop dependencies full while collapsing unrelated code (-85% to -92%).
• God Nodes & Architectural Hub Detection: Calculates Degree Centrality to identify structural project hubs and injects topology awareness into agent sessions without expensive file crawling.
• TOCP Prompt Distillation: Intercepts prompts and distills intent into lean S-Expressions via Google Gemini (2.0 Flash-Lite), OpenAI ChatGPT (gpt-4o-mini), or DeepSeek-Flash (-40% to -70%). Automatically detects GEMINI_API_KEY, OPENAI_API_KEY, or DEEPSEEK_API_KEY.
• API Surface Map Generator: Generates high-density tokensafe-out/API_SURFACE.md (~1.5k tokens) for instant agent codebase onboarding.
• Predictive Dependency Prefetcher: Attaches imported symbol signatures to eliminate downstream exploratory read_file roundtrips.
• Local Secret Redactor: Sanitizes Stripe, AWS, JWT, and database credentials before network transmission.
• Output Guard & Loop Guard: Blocks destructive full-file rewrites on files $\ge 40$ lines and halts command loops.

⚡ TokenSafe vs. Graphify: Dynamic In-Flight Defense vs. Static Reports

How TokenSafe complements or supersedes static graph tools like Graphify (graphify-labs/graphify):

Complements & Replaces: If you already use Graphify for repository mapping, TokenSafe works alongside it by compressing real-time agent tool reads on the wire. Or use TokenSafe standalone for a zero-configuration, zero-cost, sub-30ms architecture engine out of the box.

🤖 Universal LLM Distillation Providers

TokenSafe supports any key you already have:

Check active providers anytime with:

tokensafe providers

📊 Zero-Loss SWE-bench Benchmark Results

Verified across 5 real-world production scenarios:

💎 Pricing & 7-Day Free Trial

👉 Start your 7-Day Free Trial on our website

🛠️ CLI Quickstart

# Analyze repository God Nodes and dependency topology
tokensafe graph

# Generate compact tokensafe-out/API_SURFACE.md interface snapshot
tokensafe map

# View live savings dashboard in your terminal
tokensafe stats

# Open interactive Apple dark-mode HTML dashboard
tokensafe html

# Run the 5-scenario benchmark suite
tokensafe benchmark

# Run the local transparent AI proxy (127.0.0.1:8765/v1)
tokensafe proxy

# Activate your Pro License key
tokensafe activate TS1.eyJlbWFpbCI6...

🧪 Unit Testing

python3 -m unittest discover tests

Zero external runtime dependencies — runs on standard Python 3.10+.

📄 License

MIT License. Commercial enterprise licenses available for on-premise B2B deployments.

Export Markdown Report

./bin/agy-tokens markdown

📂 Project Structure

agy-token-optimizer/
├── plugin.json                 # Antigravity plugin manifest
├── hooks.json                  # Lifecycle hook declarations (PreInvocation, PreToolUse, PostToolUse)
├── rules/
│   └── AGENTS.md               # TOCP Protocol directives for LLM (prompt-cached)
├── skills/
│   └── token-optimizer/
│       └── SKILL.md            # On-demand Antigravity skill
├── proto/
│   └── tocp.proto              # Protocol Buffers contract
├── src/
│   ├── tokenizer.py            # Zero-dependency calibrated BPE token counter
│   ├── compactor.py            # Semantic compactor (Natural Language -> TOCP S-Expr)
│   ├── slicer.py               # AST & Line windowing tool optimizer
│   ├── metrics.py              # Persistent SQLite metrics engine
│   └── dashboard.py            # Visual ANSI terminal & Markdown generator
├── hooks/
│   ├── pre_invocation.py       # PreInvocation hook entry point
│   ├── pre_tool_use.py         # PreToolUse hook entry point
│   └── post_tool_use.py        # PostToolUse hook entry point
├── bin/
│   └── agy-tokens              # Executable CLI
├── tests/                      # Unit test suite (100% passing)
├── install.sh                  # One-click installer for Antigravity
└── README.md

🛠️ Installation & Antigravity Setup

Run the installer:

./install.sh

This symlinks the plugin directly into ~/.gemini/config/plugins/agy-token-optimizer.
Antigravity automatically loads it on startup.

🧪 Running Unit Tests

python3 -m unittest discover tests

No external packages required — runs on standard Python 3.10+.