# TokenSafe

> Zero-Loss Context Compression & AST Distillation Engine for AI Coding Agents.
> Official Website: https://tokensafe.dev
> GitHub Repository: https://github.com/NekoSin4eG/tokensafe

## Overview

TokenSafe reduces LLM token consumption by 60% to 90% across autonomous coding agents (Claude 3.7 Sonnet, Cursor Composer, Codex, Google Antigravity, Aider) without code quality loss or syntax errors.

Autonomous agents frequently re-read entire dependency trees and static modules across multi-turn sessions. TokenSafe intercepts context payloads locally, replaces implementation logic with Abstract Syntax Tree (AST) skeletons, strips secrets before dispatch, and serves cached dependencies with sub-2ms latency.

## Core Capabilities

- **AST Syntax Skeletonizer**: Parses Python (`ast`), TypeScript/JavaScript, Go, and Rust. Collapses function and method bodies into `{ ... }` or `...` placeholders while retaining full type signatures, docstrings, and exported interfaces.
- **TOCP Prompt Distillation & Arbitrage Guard**: Distills verbose prompts into lean S-Expressions via Google Gemini Flash-Lite (`gemini-flash-lite-latest`, $0.075/M in, 1,500 free req/day) and DeepSeek. Prompts < 100 tokens use instant zero-cost local regex ($0, <1ms); LLM output is clamped to 60 tokens max.
- **Two-Tier Distillation Cache**: In-Memory LRU + Persistent SQLite cache (`metrics.db`) with SHA-256 keys eliminates duplicate LLM calls on recurring prompts with 0ms replay.
- **Turn-to-Turn Context Distillation**: Eliminates repeated directory listings, unchanged test stdout, and redundant tool calls between conversation steps.
- **Local Secret & PII Scrubbing**: Detects Stripe secrets, AWS credentials, JWT tokens, and `.env` variables locally, replacing them with deterministic anchors before prompt transmission.
- **Zero-Latency Proxy & CLI**: Drop-in HTTP proxy running on `localhost:8765` or transparent CLI wrapper (`tokensafe run ...`).

## SWE-bench Verified Benchmarks

- **Claude 3.7 Sonnet (SWE-bench verified)**: Baseline 131,604 tokens -> TokenSafe 7,251 tokens (-94.5% context reduction, 100% test pass rate).
- **Cursor Composer (AST Slicing + Pre-fetch)**: Baseline 146,200 tokens -> TokenSafe 11,690 tokens (-92.0% context reduction, 100% test pass rate).
- **Google Antigravity Multi-Agent Workflow**: Baseline 240,000 tokens -> TokenSafe 14,400 tokens (-94.0% context reduction, 100% test pass rate).
- **OpenAI Codex & Copilot CLI**: Baseline 98,500 tokens -> TokenSafe 7,880 tokens (-92.0% context reduction, 100% test pass rate).

## Installation & Ecosystem

### 1-Click NPM Zero-Install (Recommended for Cursor & Claude)
```bash
npx tokensafe
```

### Python PyPI
```bash
pip install tokensafe && tokensafe
```

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

### Universal MCP Server
```json
{
  "mcpServers": {
    "tokensafe": {
      "command": "npx",
      "args": ["-y", "tokensafe", "mcp"]
    }
  }
}
```

### Activate License
```bash
tokensafe activate <YOUR_LICENSE_KEY>
tokensafe stats
```

## Cloud Backend API Reference

- `GET https://api.tokensafe.dev/health`: Service health check.
- `GET https://api.tokensafe.dev/api/dashboard?email=<email>`: Authenticated customer telemetry and team console.
- `POST https://api.tokensafe.dev/api/team/seat/create`: Issue teammate license key within seat quota.
- `POST https://api.tokensafe.dev/api/team/seat/revoke`: Revoke developer seat key.
- `POST https://api.tokensafe.dev/api/telemetry/push`: Ingest local compression metrics batch.
- `POST https://api.tokensafe.dev/webhook/stripe`: Stripe subscription fulfillment and cancellation webhook.

## Licensing & Pricing

- **Open Source Community**: Free ($0/mo), local AST skeletonizer, CLI proxy, unlimited personal use.
- **Solo Developer**: $9/mo (7-day free trial), multi-provider distillation (Gemini, Claude, GPT, DeepSeek), Cursor & Claude Desktop extensions, cloud analytics sync.
- **Engineering Team**: $29/seat/mo (7-day free trial), from 1 seat with flexible scaling, team seat quota management, centralized telemetry console, self-hosted Docker proxy.