TokenSafe MCP

ลดการใช้โทเค็นของ AI coding agent ได้สูงสุด 90% ด้วยการแบ่งไฟล์ตาม AST, กราฟการพึ่งพา 1-hop, การกรอง diff/คำสั่ง, การค้นหาแบบจำกัดขอบเขต และระบบป้องกันความปลอดภัยก่อนดำเนินการ

เอกสาร

TokenSafe Logo

TokenSafe

Make AI coding agents 3x faster without burning team quotas.
Exact code context. Fewer tokens. Safer changes.
TokenSafe intercepts AI tool calls locally, replacing thousands of lines of irrelevant code with precise function bodies and typed signatures. Preserve prompt caches and protect secrets before they reach your AI transcripts.
Works with Cursor, Claude Code, Codex, Windsurf, Google Antigravity, Gemini CLI, and ChatGPT.

Tests npm npm downloads PyPI Stars License Trial

Install • Quickstart • Why TokenSafe • Benchmarks • Pricing • FAQ • Reference • Website & Docs


Install & Agents

Connect TokenSafe to the AI coding agents on your workstation in one command:

# Option 1: Zero-Install via npx (recommended)
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

The installer detects which agents live on your machine, registers the TokenSafe MCP server, injects project rules, and wires lifecycle hooks where the agent supports them.

AgentIntegration
Google AntigravityPlugin symlink + hooks + skills + MCP (loaded automatically on startup)
Claude Code CLIMCP + SessionStart / UserPromptSubmit / PreToolUse hooks
CursorMCP + beforeShellExecution / beforeReadFile hooks
Claude DesktopMCP registration (claude_desktop_config.json)
WindsurfMCP registration + global rules
OpenAI CodexMCP in ~/.codex/config.toml (stdio + cloud HTTP natively)
Cline / Roo CodeMCP registration (VS Code)
GitHub CopilotMCP registration
Z.ai CodeMCP registration
ChatGPTCloud connector, nothing to install
Gemini CLIMCP registration

Claude Desktop / Cursor MCP config:

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

Cloud features (team metrics, managed distillation, shared team cache, billing) run on the remote endpoint https://api.tokensafe.dev/mcp with Authorization: Bearer <TS2. license key>. Four public tools work without a key, so ChatGPT connects with authentication set to None.

Full per-agent configuration, hook details, and the Codex/ChatGPT setup live in docs/AGENT_SETUP.md.

CLI Quickstart

# View live savings dashboard in your terminal
tokensafe stats
⚡ TOKENSAFE CONTEXT OPTIMIZER DASHBOARD
Total Tokens Saved:   4,524,156 tokens
Efficiency Gain:      [████████████████████████░░] 92.5%
Context Traffic:      4,889,255 raw → 370,574 optimized (2,132 events)

• Command Sanitizer (CLI)        :   727,300 tokens saved (263 events)
• Architecture Graph             :   758,256 tokens saved (13 events)
• Multi-turn History Fold        : 2,897,897 tokens saved (471 events)
• Prompt Compactor (local+cache) :    43,502 tokens saved (1,255 events)
# Audit your environment: MCP tool overhead, skills tax, risky settings
tokensafe doctor

# Recursive security & hygiene audit of a repository
tokensafe guard audit

# Preview prompt compaction on custom input
tokensafe test "fix the validate_token method in src/auth.py to check jwt expiration"

# Map architectural hotspots before multi-file changes
tokensafe graph

# Disable a heavy MCP server without editing JSON
tokensafe mcp disable <server>

# Compile and preview the Friday team ROI digest
tokensafe digest

# Activate a Team or Solo license key
tokensafe activate TS2.eyJlbWFpbCI6...

The full command reference (24 commands) is in Reference.

Why TokenSafe

Giving coding agents raw access to entire repositories creates three daily costs:

  1. Senior hours burned on AI PRs: reading 2,000-line modules for a 10-line fix makes models forget imports, invent methods, and regress adjacent code.
  2. Secret leaks and unsafe shortcuts: static prompt rules in .cursorrules wear off mid-session. Agents hardcode fallback credentials, disable TLS checks, or stage .env files with git add ..
  3. Mid-sprint quota stops and blind spend: bloated diffs, lockfiles, and verbose MCP schemas burn 5-hour limits while engineering leads lack per-seat ROI visibility.
OutcomeWhat changes for your teamHow it is enforced
Clean code on the first passAgents read only target functions, design tokens, and 1-hop dependencies instead of 2,000 lines of noise.Sub-30ms local AST skeletonizer, architecture graph, predictive signature prefetch, lockfile-stripping diff slicer, loop guard.
Zero leaked secrets in gitHardcoded password fallbacks, TLS bypasses, raw SQL interpolation, and .env commits are stopped before reaching disk or staging.Deterministic TokenSafe Guard on every tool call, output guard on large writes, local PII/key redaction.
Predictable sprint velocity & ROITeammates get warm cache hits, and CTOs receive a Friday ROI digest separating measured and estimated savings.Shared team cache, live context budget HUD, per-seat dashboard.

A $29 seat pays for itself by saving one hour of senior code review or preventing one leaked key. Typical payback: 1 to 3 days of team usage.

Before and After

One contrast: an agent asked to change one helper in a 1,420-line file receives 94 lines of target logic and type contracts instead of the whole module. The same principle applies to terminal output, diffs, and session history.

What breaks coding agentsHow TokenSafe fixes itThe outcome
"Lost in the Middle" context fade: an agent reads a 2,000-line file to change one 10-line helper, forgets imports, and invents methods.AST skeletonizer folds inert bodies into typed signatures while keeping the target symbol and 1-hop callees intact.Focused signal: the model keeps full type contracts without drowning in unrelated logic.
Terminal log flooding: npm test or pytest fails and dumps 4,000 lines of stack traces and lockfile diffs into context.Command sanitizer strips lockfile noise and trims output to the failing assertion and stack frame.Root-cause fixes instead of unrelated rewrites.
Infinite wait on background tests: yarn test hangs in watch mode, or jest finishes but unclosed handles keep the process alive.Test-runner guard forces run-once mode (CI=true, --watch=false, --forceExit) and peeks at <cwd>/package.json to identify the runner behind opaque scripts.The test run terminates with an exit code and the agent moves on.
5-attempt retry loops: an agent repeats the same broken edit until the context budget runs dry.Loop guard detects repeated identical tool calls and halts the cycle.Stuck loops stop before damaging working modules.
Unsafe edits & secret leaks: fallback keys, verify=False, SQL string interpolation, or git add . with .env present.TokenSafe Guard audits writes and shell commands locally before execution.Credentials, SQLi patterns, and destructive commands are blocked locally.

When an operation is blocked, the agent sees an explicit, constructive message:

🛡️ TokenSafe Guard: Blocked a hardcoded secret fallback in config.py.
   Leave the default empty or read from os.environ at runtime.

10 Core Engine Capabilities

Why TokenSafe agents ship working code on the first pass without burning quotas or leaking keys:

CapabilityWhat it solvesHow it worksImpact
1. Architecture Graph
get_architecture_graph
Agents open an unfamiliar repo and burn 45k tokens blindly crawling files.Analyzes dependency centrality, import hubs, and critical call paths in memory.< 250 tokens to map God Nodes (vs ~45k blind crawl)
2. Smart Code Slicing
smart_read_file
Feeding 3,000 lines into context causes models to hallucinate fake methods.Preserves target method logic while folding uncalled helpers into typed contracts.-95.0% tokens (192 vs 3,840) across 11 languages
3. Pre-Git Security Guard
guard_inspect
Autonomous agents read .env secrets or hardcode fallback keys in edits.Sub-millisecond pre-flight interception blocks secrets, TLS bypasses, and dangerous commands.0 leaked keys in LLM logs or git history
4. Lockfile & Noise Shield
schema_slicer
Reading package-lock.json or uv.lock dumps 360k+ tokens in one turn.Intercepts lockfiles and massive schemas, returning a queryable dependency summary.-99.8% tokens (855 vs 367,410 tokens)
5. Monorepo API Surface Map
get_api_surface
Agents guess interfaces or crawl dozens of modules to find exported types.Extracts all exported types, interfaces, and contracts across the repo in one pass.1 tool call vs 50 separate file reads
6. Subagent Pointer Cache
SUBAGENT_DEDUP
Multi-turn chats and swarms pay full price to re-read the same shared utilities.In-memory content hashes return 1-line pointer hits for unchanged files.0 tokens wasted on repeat file reads
7. Shared Team Cache
team_cache
10 to 50 engineers repeatedly parse the same core libraries from scratch.L3 monorepo pool shares stripped signatures and package contracts across teammates.72% team hits with 0ms turnaround
8. KV-Cache Prefix Locking
cache_normalizer
Shifting timestamps and reordered tools break provider prompt cache hits.Locks prefix order, sorts schemas, and injects breakpoints for Anthropic, DeepSeek, and OpenAI.92% cache hit rate at 0.10x provider rates
9. Compact Test Runner
sanitize_command
Test suites spew 1,000 lines of passing dots that crowd out instructions.Forces run-once mode (CI=true) and collapses passing runs to a single line.1 line vs 1,200 lines (traces kept on failure)
10. Context Governor & Ledger
compact_conversation
Models suffer needle-in-a-haystack amnesia after 70% context saturation.Monitors context thresholds and compacts chat sprawl into an actionable State Ledger.50+ turns without regression or amnesia

Deeper mechanics (language matrix, AST syntax trees, cache tiers, governor) live in docs/ARCHITECTURE.md.

Benchmarks

Reference run across 10 production engineering scenarios (169,761 baseline tokens down to 8,173 tokens, -95.2% net context reduction, -99.4% peak single-scenario reduction, +30.6% turn latency speedup with 100% accuracy retention):

Prompt compaction, graph topology (SWE-06), dep_mode="signature" slicing (SWE-07), repeat-read pointer dedup (SWE-09), and parametric slot cache hits (SWE-10) are measured live (1,368 optimized tokens) while baselines (169,761), turn counts, and output estimates (6,805 tokens) are modeled constants. See METRICS.md and BENCHMARK_REPORT.md.

Benchmark ScenarioTask ComplexityBaseline TokensTokenSafe TokensReductionTurn SpeedupAccuracy
SWE-06: Zero-Token Architecture DiscoveryGod Node indexing vs. crawl49,716312-99.4%6 → 1 turns (+83%)100% Pass
SWE-09: Repeat-Read Pointer DedupAgentFirewall unchanged pointer17,388208-98.8%2 → 1 turns (+50%)100% Pass
SWE-03: Monorepo Lockfile Git DiffMonorepo branch diff18,911761-96.0%2 turns100% Pass
SWE-07: Graph-Guided AST Symbol Slicingdep_mode="signature" + collapsed imports26,0231,194-95.4%4 → 2 turns (+50%)100% Pass
SWE-10: Parametric Distillation Slot CacheSlot template hit (0 LLM tokens)2,814133-95.3%2 → 1 turns (+50%)100% Pass
SWE-08: Monorepo Lockfile Grep Leakgit grep across lockfiles10,111491-95.1%2 turns100% Pass
SWE-01: Race Condition / Distributed LockAST query & Redis redlock5,046414-91.8%4 → 3 turns (+25%)100% Pass
SWE-05: Multi-Turn History Compaction8-turn session history fold31,0103,130-89.9%8 turns100% Pass
SWE-02: OAuth JWT Expiration TriageController bug investigation3,733403-89.2%3 → 2 turns (+33%)100% Pass
SWE-04: CI Test Failure ExtractionFull test log & stack trace5,0091,127-77.5%3 turns100% Pass

Why "Up to 99%" (Multiplicative Math & Honest Boundaries)

TokenSafe combines two multiplicative savings layers rather than relying on AST compression alone:

  1. Context Token Reduction (-85% to -99.4%): Graph-guided dep_mode="signature" keeps only the edited symbol body intact while collapsing imports and 1-hop dependency implementations into signatures (-95.4% in SWE-07), Architecture Discovery maps repos in < 350 tokens vs. full crawls (-99.4% in SWE-06), and repeat reads resolve to ~75-token integrity pointers (-98.8% in SWE-09, or -99.56% on raw file re-reads).
  2. KV-Cache Prefix Locking (90.8% hit rate at 0.10x cached-read rate): The Append-Only Epoch Governor (ContextGovernor) freezes history prefixes monotonically up to 80% of the model context window while PromptCacheNormalizer strips volatile metadata, sorts tool schemas, and injects provider cache_control breakpoints / prompt_cache_key. In a live 20-turn replay over src/*.py (BENCHMARK_REPORT.md):
Multi-Turn 20-Turn Replay MetricValueComparison
Byte-Identical KV-Cache Prefix Hit Rate90.8%535,491 / 589,846 input tokens
20-Turn Context Input Tokens-84.6%3,837,648 ➔ 589,846
Claude Sonnet 4.5 Input Bill (vs. Uncached)-96.8%Cached input reads @ $0.30/M (0.10x)
Claude Sonnet 4.5 Total Bill (vs. Uncached)-96.6%$11.6779 ➔ $0.4005 (includes uncached $15/M outputs)
Claude Sonnet 4.5 Total Bill (vs. Naive Mid-Trim Cache)-84.6%$2.5984 ➔ $0.4005
DeepSeek V3 Total Bill (vs. Uncached)-96.9%Cached reads $0.028/M (0.10x), outputs $1.10/M

Honest bounds: When ~85–95% fewer context tokens combine with a 90%+ KV-cache hit rate billed at 0.10x, cached input spend approaches 1–2% of uncached cost (up to ~99% savings) on graph-first, repeat-read, and cache-warm workflows. Total session invoices typically fall 80–97% because newly generated output tokens and first-turn cache writes are never discounted by KV-caching.

How to read these numbers: this benchmark is a simulated harness. Compression ratios and 20-turn KV-prefix byte matches are computed live from real files, while baselines and turn speedups are modeled. Production events in TokenSafe are explicitly labeled measured or estimated (see METRICS.md).

Real-Repository Benchmark (measured on live clones)

No modeling: fifteen popular repositories across 10 languages (Python, TypeScript, JavaScript, Go, Rust, Java, Ruby, PHP, C#, Swift, C) cloned at HEAD, scenarios pre-registered before measurement (src/bench_scenarios.json), every token counted on real bytes, and deterministic zero-loss gates that disqualify any scenario they fail. Curated rows (all rows in docs/BENCHMARK_REAL.md):

Repo (language)ScenarioBaseline tokTokenSafe tokReductionGates
lodash (JS)Symbol read (AST skeleton)515,843855-99.8%PASS
lodash (JS)Multi-turn + repeat reads1,640,6744,233-99.7%PASS
lodash (JS)Architecture discovery802,825178-99.98%PASS
lodash (JS)Junk-read guard87,4751,745-98.0%PASS
lodash (JS)KV-cache 10-turn bill7,390,3471,567,062-78.8%PASS
fastapi (Py)Junk-read guard (uv.lock cap)367,129855-99.8%PASS
flask (Py)Architecture discovery53,237176-99.7%PASS
sinatra (Ruby)Architecture discovery28,165199-99.3%PASS
composer (PHP)Junk-read guard (composer.lock)33,1031,645-95.0%PASS
flask (Py)Write egress (output axis, $15/M)7,10644-99.4%PASS
flask (Py)Multi-turn + repeat reads45,3365,304-88.3%PASS
curl (C)Symbol read (AST skeleton)125,16831,174-75.1%PASS
rich (Py)Multi-turn + repeat reads80,03612,329-84.6%PASS
requests (Py)Multi-turn + repeat reads59,3809,561-83.9%PASS
flask (Py)Symbol read (AST skeleton)18,8643,784-79.9%PASS
rich (Py)Symbol read (AST skeleton)28,6757,710-73.1%PASS
requests (Py)Symbol read (AST skeleton)9,7432,849-70.8%PASS
sinatra (Ruby)KV-cache 10-turn bill303,85063,393-79.1%PASS
retrofit (Java)KV-cache 10-turn bill3,312,375673,361-79.7%PASS
gin (Go)KV-cache 10-turn bill317,63865,036-79.5%PASS
zod (TS)KV-cache 10-turn bill1,905,787431,857-77.3%PASS
serde (Rust)KV-cache 10-turn bill1,307,460300,472-77.0%PASS
curl (C)KV-cache 10-turn bill1,586,875423,360-73.3%PASS
newtonsoft (C#)Symbol read (AST skeleton)56,07617,871-68.1%PASS
alamofire (Swift)Symbol read (AST skeleton)13,9098,100-41.8%PASS
serde (Rust)Symbol read (AST skeleton)69,61042,671-38.7%PASS
gin (Go)Symbol read (AST skeleton)23,56714,938-36.6%PASS
flask (Py)Secret guard (cat .env -> deny, 0 leak)15382-46.4%PASS
rich (Py)Verbose test output (noise strip)746385-48.4%PASS
composer (PHP)Prompt compaction (TOCP)13846-66.7%FAIL
flask (Py)Full-suite pytest output6,4026,191-3.3%PASS
fastapi (Py)Git diff churn -> slice416393-5.5%PASS

Aggregate: ~25.7M measured tokens saved per traced pass over all 15 repositories in 10 languages (142 gated-OK rows; input at $3/M, output axis at $15/M, KV-cache hits billed at $0.30/M). Clean pytest suites honestly score ~0-3% — savings are never invented. 17 gate-FAILs and 21 skips are published with reasons on the live page (e.g. fastapi's test-output: strict warning filters escalate a pytest-asyncio deprecation into a pytest INTERNALERROR; whole-repo API surfaces bigger than hub crawls for fastapi/httpie; httpie's core.py refuses skeletonization — one function is most of the file). Full table + raw JSON: docs/BENCHMARK_REAL.md · live page: https://tokensafe.dev/bench · methodology post: https://tokensafe.dev/blog/real-repo-benchmark-5-repos. Reproduce:

tokensafe bench --real                        # all 15 pre-registered repos
tokensafe bench --real --repo=pallets/flask   # one repo
tokensafe bench --real --here                 # your current repository

Metrics Honesty

TokenSafe labels every savings event as one of:

  • measured: the model literally received fewer bytes than the tool produced (sliced file reads, filtered command output, AST skeletons).
  • estimated: the model received a compact artifact and saved tokens are counted against a reasonable baseline (architecture graph vs. a full repo crawl; folded history digest injected while raw history stays in context).

Totals always display the split (X metered · Y est.). When a live metric is missing, the UI shows — rather than a placeholder number. USD figures are derived approximations (tokens × $1.5 / 1M), not provider invoices. Full contract: METRICS.md.

Pricing and 7-Day Team Trial

TokenSafe follows an open-core model: verify local context savings and guardrails on your own repo first, then roll out team caching, org policies, and per-seat ROI.

PlanPriceMonthly AllowanceIncluded Capabilities
Developer Sandbox$0 forever500,000 tokens / mo9-language local regex compactor, local AST slicer CLI, local secret & .env guard, SQLite & terminal dashboard
Engineering Team (Recommended)$29 / seat / mo (~$24 / seat / mo billed $290/yr)Unlimited7-Day Free Trial, shared team cache (L3 monorepo hits), org-wide guard & git leak shield, Friday per-seat ROI digest, centralized seat provisioning & revoke, managed cloud distillation (zero keys needed)
Enterprise & VPCCustomUnlimitedOrg audit log (guard forensics: who / what / when, CSV & SIEM export), central guard policies, self-hosted VPC proxy (private BYOK), zero-telemetry / air-gapped mode, SAML / OIDC SSO, dedicated onboarding & SLA

Working solo? Individual Solo plans start at $9 / mo ($89 / yr).

7-Day Free Trial · Offline Ed25519 Seat Keys (TS2.*) · Zero Source Code Transmitted · Cancel anytime

Start a 7-Day Team Trial    Run Free Locally

FAQ

Does my source code leave my machine? No. Slicing, guarding, compaction, and metrics run locally. The cloud receives only counters (token totals and event types), never file contents or prompts. Set TOKENSAFE_TELEMETRY_DISABLED=1 to disable all telemetry sync; local features keep working.

How does offline license verification work? License keys are TS2.* tokens signed with Ed25519. Your client verifies the signature offline against an embedded public key and caches the result for up to an hour. Enforcement never requires a network round trip.

What do measured and estimated mean? measured means the model literally received fewer bytes than the tool produced. estimated means savings are counted against a reasonable modeled baseline. The dashboard always shows the split and never invents numbers for missing data.

What exactly does the $29/seat plan include? Unlimited compaction and managed cloud distillation (zero API keys for developers), the shared L3 monorepo cache, org-wide guard policies, the Friday per-seat ROI digest, and centralized seat provisioning and revocation. Billed annually it is $290/seat/year (~$24/seat/mo).

Can we self-host? The Enterprise & VPC plan covers a private VPC Docker proxy with BYOK provider keys, zero-telemetry / air-gapped mode, and SAML/OIDC SSO, deployed together with the TokenSafe engineering team: corp@tokensafe.dev.

What happens if a hook fails? All hook adapters fail open: an internal error never stalls your agent. Failures are logged locally so they can be reported and fixed, not silently swallowed.

Reference

Local MCP tools (13)
ToolWhat it does
get_architecture_graphArchitectural hotspots and dependency topology before multi-file reading; shared team symbol index reuse
get_api_surfaceCompact markdown map of all exported interfaces, classes, and types
smart_read_fileAST-skeletonized file read preserving a target symbol and 1-hop dependencies; OpenAPI/Prisma/GraphQL/SQL files auto-slice (symbol = spec path / model / type / table)
smart_bundle3–8 related symbols across files in one call: merged skeletons, deduplicated shared imports, unified 1-hop signatures
scoped_searchToken-bounded symbol and text search with line-numbered matches
list_dirClean directory tree without permissions, timestamps, or lockfiles
slice_diffUnified diff slicing omitting lockfiles and minimizing context lines
sanitize_commandPer-stage shell command rewrites with bounded output
guard_inspectPre-flight security and hygiene audit for commands or code snippets
context_budgetContext window usage estimate with thresholds and recommendations
compress_promptCompiles a verbose developer prompt into a compact S-expression
compact_conversationFolds a long agent transcript into a compact state ledger
get_token_savings_metricsCumulative token and cost savings analytics
Cloud MCP tools (13)

Endpoint: https://api.tokensafe.dev/mcp, auth Authorization: Bearer <TS1./TS2. key>.

ToolAccessWhat it does
get_public_statsPublicAggregate product statistics
check_latest_versionPublicLatest published version and update banner
get_setup_instructionsPublicCopy-paste MCP snippets per agent
search_docsPublicSearch public documentation
get_license_statusLicensedActive tier, seat, and trial state
get_team_metricsLicensedTeam savings metrics with measured / estimated split
distill_promptLicensedManaged cloud prompt distillation (zero API keys)
team_cache_lookupLicensedShared L3 team cache lookup
team_cache_storeLicensedShared L3 team cache store
list_invoicesLicensedBilling history
generate_team_seatLicensedProvision a signed TS2.* seat key
revoke_team_seatLicensedRevoke an active seat key
preview_weekly_digestLicensedPreview the Friday team ROI digest
Full CLI reference (24 commands)
tokensafe stats / markdown / html   Savings analytics (terminal / .md report / dashboard)
tokensafe benchmark                 Zero-context-loss benchmark suite (simulated harness)
tokensafe graph / map / skeleton    Architecture graph / API surface / AST skeleton of a file
tokensafe test "<prompt>"           Preview prompt compaction on custom input
tokensafe guard "<command>"         Pre-flight safety check for a shell command
tokensafe guard audit [path]        Recursive source audit for secrets & vulnerabilities
tokensafe doctor                    Audit MCP tool overhead and context token tax
tokensafe digest [--send]           Compile (and optionally dispatch) the weekly team digest
tokensafe mcp list|disable|enable   Manage configured MCP servers
tokensafe proxy [port]              Local transparent AI proxy (127.0.0.1:8765/v1; host via TOKENSAFE_HOST)
tokensafe proxy on/off/status       Daemon + agent wiring with one-command rollback
tokensafe install / setup [--all]   Configure detected agent environments
tokensafe update / check-update     Self-update / check for a newer version
tokensafe activate <KEY>            Activate a Team or Solo license key
tokensafe license                   Show active tier and trial state
tokensafe providers                 List distillation providers and active mode
tokensafe sync                      Sync local telemetry with the cloud dashboard
tokensafe prune [--days N]          Compact metrics database (roll old events)
tokensafe vacuum                    Reclaim SQLite disk space
tokensafe tests [pytest]            Run the unit test suite (compact failure report)
tokensafe reset                     Reset all local token metrics
tokensafe --version                 Print version and exit

Proxy mode & agent coverage (v3.0.0)

One command wires everything it safely can:

tokensafe proxy on      # installs a keep-alive daemon (launchd/systemd), wires Claude Code, prints manual steps for the rest
tokensafe proxy status  # health, wiring state, last traffic
tokensafe proxy off     # rollback: unwires agents (previous base URL restored) and removes the daemon

The daemon keeps the proxy alive on 127.0.0.1:8765, on rewires agents only after a verified /health answer (a dead proxy never bricks an agent), and every wiring is backed up for off. tokensafe install and tokensafe update ask interactively whether to enable the proxy (skipped in non-TTY/scripted runs); prefer manual? Run tokensafe proxy in a terminal and point your agent's base URL at http://127.0.0.1:8765 yourself:

AgentRoute through proxy?How
Claude Code✅ auto (tokensafe proxy on)ANTHROPIC_BASE_URL=http://127.0.0.1:8765 — the proxy ingests native Anthropic /v1/messages shape
Cline / Roo Code✅ manualAPI Provider → OpenAI-compatible → Base URL http://127.0.0.1:8765/v1
Aider✅ manual--openai-api-base http://127.0.0.1:8765/v1
Cursor (custom models)✅ manualAdd an OpenAI-compatible model with override base URL
Cursor (built-in models)❌Routed via Cursor's own backend — hooks only
Antigravity / ZCode❌Hooks only (lifecycle adapters)
Codex CLI❌stdio MCP + AGENTS.md (no proxy transport)

What runs where:

  • Proxy-only (A/B/D): Tool Result Ledger (folds aged tool results in-flight, TOKENSAFE_TOOL_LEDGER=0 to disable), session-stable cold-tool pruning (opt-in: TOKENSAFE_TOOL_PRUNING=1, TOKENSAFE_TOOL_PRUNE_KEEP, TOKENSAFE_TOOL_PRUNE_ALLOWLIST), managed-cloud history distillation (paid, opt-in: TOKENSAFE_HISTORY_DISTILL=1).
  • Hooks (all agents): PostToolUse stdout compaction, PreToolUse shell/secret guards, Output Guard steering full-file writes to surgical edits, prompt compaction, history folding.
  • Folded originals are archived under ~/.tokensafe/data/tool_ledger/ and every fold carries a deterministic re-hydration anchor — nothing is destroyed, and already-folded results are never re-processed (KV-cache stable).

More documentation: docs/AGENT_SETUP.md · docs/ARCHITECTURE.md · docs/API.md · METRICS.md · BENCHMARK_REPORT.md

Development and License

The client runs on Python 3.10+ with cryptography>=42.0 as its sole runtime dependency for Ed25519 license checks; all AST slicing, SQLite metrics, MCP tooling, and guardrails run on the standard library (details).

# Run the unit test suite (compact failure report; full: --traceback / -v)
tokensafe tests

MIT License. Commercial licenses are available for self-hosted B2B and enterprise VPC deployments. Questions: corp@tokensafe.dev · tokensafe.dev