# TokenSafe — Full Technical Documentation & LLM Reference > Official Website: https://tokensafe.dev > Documentation & Setup: https://tokensafe.dev/docs > Real-Repo Benchmarks: https://tokensafe.dev/bench > Blog: https://tokensafe.dev/blog > Pricing: https://tokensafe.dev/pricing > Founder: Oleg Savelev (https://www.linkedin.com/in/oleg-savelev) > GitHub: https://github.com/tokensafe-dev/tokensafe > Security & Telemetry Contract: https://github.com/tokensafe-dev/tokensafe/blob/main/METRICS.md --- ## 1. Executive Summary & Purpose TokenSafe is a local runtime firewall and AST context engine designed for AI coding agents (Claude Code, Cursor Composer, Windsurf Cascade, OpenAI Codex, Google Antigravity, Kimi Code, GitHub Copilot). Fixed context windows, bulky repository helper code, noisy test outputs, and drifting prompt caches cause agents to exhaust daily quotas and suffer mid-session hallucination. TokenSafe runs locally on the developer's machine, filtering context down to what the model actually touches before sending it over the wire, while deterministically blocking secret leaks before they reach git. --- ## 2. Core Capabilities & Mechanics ### 2.1. Polyglot AST Context Slicing (< 30ms, 10+ Languages) - **Engine**: Standard-library deterministic parser and native Tree-sitter grammars. - **Languages**: Python, TypeScript/React, JavaScript, Go, Rust, Java, C#, C/C++, PHP, Kotlin, Swift, and CSS/SCSS/LESS/Tailwind design tokens. - **Behavior**: When an agent targets a function or symbol, TokenSafe preserves the full executable body of that symbol and folds surrounding helpers into 1-line typed signatures (`dep_mode="signature"`). - **CSS Preservation**: Automatically keeps all design tokens (`:root`, `@theme`, CSS variables) in full while folding component selectors. - **Zero-Loss Reversible Anchors**: Every folded block receives an 8-character Blake2b hash anchor (`[TokenSafe folded: #a1b2c3d4 ...]`). Any agent can restore bit-exact original bytes in 0ms via `tokensafe:expand_ref(hash="a1b2c3d4")`. ### 2.2. Prompt Cache Prefix Normalizer & KV Locking - Locks conversation prefixes monotonically up to 80% of the model context window. - Normalizes volatile metadata, sorts tool schemas deterministically, and injects multi-breakpoint Anthropic `cache_control` / OpenAI `prompt_cache_key`. - In a 20-turn live replay over `src/*.py`, achieved a 90.8% byte-identical KV-cache prefix hit rate (reducing token costs by up to 96.5% on cached read-heavy workflows). ### 2.3. Pre-Commit Secret & Security Guardrails (`TokenSafe Guard`) - **Hardcoded Secret Fallback Blocker**: Intercepts code modifications attempting to inject default credentials in `os.environ.get(..., "secret")` or `process.env.VAR || "secret"`. - **TLS Verification Bypass Blocker**: Rejects `verify=False` (Python requests) or `rejectUnauthorized: false` (Node.js). - **SQL Injection Prevention**: Blocks raw SQL f-string concatenation (`cursor.execute(f"SELECT ... {id}")`). - **CORS Wildcard with Credentials**: Flags `Access-Control-Allow-Origin: *` paired with credentials. - **Destructive Command & Blanket Staging Shield**: Halts `rm -rf /` commands and prevents `git add .` when `.env` or private keys are in the working tree. ### 2.4. MCP Context Tax Doctor (`tokensafe doctor`) - Measures the exact system-prompt token overhead injected by enabled Model Context Protocol (MCP) tool schemas. - Lets engineers inspect overhead and disable heavyweight servers with a single command. ### 2.5. Three-Tier Caching Architecture - **L1 (In-Memory LRU)**: Sub-millisecond hit inside active sessions. - **L2 (Persistent SQLite)**: Normalized SHA-256 hash cache in `metrics.db` across restarts. - **L3 (Shared Team Cache)**: Team-wide monorepo pool (`/api/team/cache`) so teammates never re-buy the same immutable context. --- ## 3. Supported AI Coding Agents - **Cursor Composer** (`beforeShellExecution`, `beforeReadFile` hooks) - **Claude Code & Claude Desktop** (`SessionStart`, `UserPromptSubmit`, `PreToolUse` lifecycle adapters) - **Windsurf Cascade** - **OpenAI Codex & Copilot CLI** - **Google Antigravity** - **Kimi Code & ZCode** - **ChatGPT** (via remote streamable-HTTP MCP endpoint `https://api.tokensafe.dev/mcp`) --- ## 4. CLI Command Reference - `npx tokensafe init` / `tokensafe init`: Auto-detects installed coding agents and registers lifecycle hooks and MCP configuration. - `tokensafe doctor`: Audits active agent hooks, verifies MCP tool schema overhead, and validates local SQLite metrics. - `tokensafe stats`: Displays real-time session and historical token savings, cache hit rates, and estimated USD cost reductions. - `tokensafe bench --real --repo=`: Runs reproducible zero-loss AST benchmark against popular open-source repositories. - `tokensafe bench --real --here`: Runs reproducible benchmark against the current repository. - `tokensafe expand-ref `: Expands an 8-character folded hash anchor back into original raw source bytes. - `tokensafe web `: Fetches and cleans web pages/documentation, stripping boilerplate and ads for minimal token footprint. - `tokensafe login`: Initiates device authorization grant (RFC 8628) to activate free Community tier (500,000 tokens/mo). - `tokensafe activate `: Activates Team or Enterprise Ed25519 offline seat license. --- ## 5. Metrics & Telemetry Honesty TokenSafe strictly enforces separate reporting categories: - **`measured`**: Actual bytes kept off the wire by local file slicing, skeleton folding, diff slicing, and command sanitization. - **`estimated`**: Counterfactual estimates (e.g. architecture graph onboarding vs. recursive directory crawl). - **Privacy Assurance**: Source code NEVER leaves developer workstations. Telemetry packets send only aggregate counters (`saved_tokens`, `tool_name`, `timestamp`). Zero code transmission. --- ## 6. Real-Repository Benchmark Results Measured against real production repositories under pre-registered zero-loss gates: - **Flask** (`app.py`, target `full_dispatch_request`): -70.8% tokens (`18,864 -> 5,506`). - **Requests** (`sessions.py`, target `Session.request`): -52.2% tokens (`9,743 -> 4,657`). - **FastAPI** (`routing.py`, target `add_api_route`): -46.5% tokens (`73,721 -> 39,441`). - **Rich** (`console.py`, target `Console.print`): -67.1% tokens (`28,675 -> 9,434`). - **Httpie** (`core.py`, target `main`): -76.5% tokens (`2,933 -> 689`). - **Architecture Discovery**: God-node topological map replaces recursive crawling with -99.1% to -99.8% token reduction. --- ## 7. Pricing & Licensing - **Developer Sandbox**: $0 forever (500K tokens/mo, local AST slicing, secret guards, terminal dashboard). - **Engineering Team**: $29/seat/mo ($24/seat/mo billed annually) with 7-day free trial. Unlimited compression, L3 Shared Team Cache, org-wide Guard policies, Friday Team ROI Digest, central Ed25519 seat licensing. - **Enterprise & VPC**: Custom annual agreements. Private self-hosted Docker VPC proxy (BYOK), zero-telemetry isolation, SAML SSO, SLAs.