tokensafe
Your coding agent isn't getting dumber. Your context is just full of trash. Local context firewall & zero-loss runtime for Cursor, Claude Code, and autonomous agents.
Install / Use
claude mcp add tokensafe-dev -- npx -y github:tokensafe-dev/tokensafeIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Tags
Our assessment of tokensafe
tokensafe scores 87/100 on our quality scale, 487th of 947 AI & Machine Learning skills we index.
Its MCP Server is 36 KB long, well organised into 27 sections with 10 code examples: a thorough specification that gives an agent plenty to work with.
It has 44 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so tokensafe is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). An AI review of the same text found nothing harmful.
- noteInstalls by piping a downloaded script into a shellline 67
curl -fsSL https://tokensafe.dev/install.sh | bash
AI review by kimi-k2.7-code on 2026-11-16. Automated pattern scan on 2026-11-16. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
tokensafe compared with similar skills
All 4 of these similar skills score higher than tokensafe; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| tokensafe (this skill)by tokensafe-dev | 87 | 44 | today | MCP Server |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install tokensafe?
- Run
claude mcp add tokensafe-dev -- npx -y github:tokensafe-dev/tokensafe. The install tabs above show the steps for each supported agent. - Which AI agents does tokensafe work with?
- It is written for Claude Code, Claude Desktop, Cursor and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is tokensafe safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands (1 minor note below). An AI review of the same text found nothing harmful. It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is tokensafe still maintained?
- The repository was last updated today, so tokensafe is actively maintained.
Skill content
View source on GitHubWhat's New in v4.0
TokenSafe 4.0 is a major architecture release designed for Zero Mid-Day Lockouts, 3-Second Turn Latency, Exact Code Context (Zero Loss), and Developer Flow:
- ⚡ SQLite FTS5 BM25 Code Indexer & Search (
scoped_search,tokensafe search): Native SQLite full-text search with trigram tokenization and BM25 relevance ranking (<1ms) across the repository. Replaces raw terminal grep entirely with zero-token-waste search. - 🔗 SQLite Graph Cache & Cross-Boundary Route Linking: Persistent SQLite caching (
.tokensafe/cache/graph.db) with bidirectional semantic linking between frontend client endpoints (fetch,axios,apiClient) and backend HTTP routes (FastAPI,Express,Flask,Next.js). - 🖼️ Vision Image Downscaler (
optimize_image,tokensafe optimize-image): Automatically scales down oversized screenshots, architecture diagrams, and mockups (>1024px) via Pillow or macOSsips, saving 50–75% vision tokens while keeping original files intact. - 🧠 Anti-Stuck Dead-Ends Ledger (
get_mistakes,tokensafe mistakes): Persistent project memory tracking failed hypotheses, loop guard trips, and git reverts to prevent agents from cycling through already-failed solutions. - 🧹 Transcript Superseded Output Pruning (
prune_superseded,tokensafe prune-superseded): Prunes obsolete intermediate tool reads that were superseded by subsequent edits or re-reads in long agent transcripts (-30-40% context). - 🧼 ANSI Escape Sequence Stripper: Cleans all ANSI/VT100 escape codes from tool outputs, test runners, and proxy streams before they enter model context.
- 👻 Ghost Tokens Auditor (
tokensafe doctor): Detects and cleans redundant multi-IDE configuration files (.cursorrules,CLAUDE.md,.windsurfrules,.clinerules) and oversized rule files, saving 2,000–5,000 wasted ghost tokens on every turn. - 🛡️ Exact Code Context & Reversible Stash (
expand_ref): 100% byte-exact target symbol preservation with reversible 8-char hash anchors (#a1b2c3d4) to instantly recover any folded block. - 🌲 C# Tree-sitter Support: Native AST slicing and God Nodes detection for C# (
tree-sitter-c-sharp) alongside TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, and PHP.
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.
| Agent | Integration |
|---|---|
| Google Antigravity | Plugin symlink + hooks + skills + MCP (loaded automatically on startup) |
| Claude Code CLI | MCP + SessionStart / UserPromptSubmit / PreToolUse hooks |
| Cursor | MCP + beforeShellExecution / beforeReadFile hooks |
| Claude Desktop | MCP registration (claude_desktop_config.json) |
| Windsurf | MCP registration + global rules |
| OpenAI Codex | MCP in ~/.codex/config.toml (stdio + cloud HTTP natively) |
| Cline / Roo Code | MCP registration (VS Code) |
| GitHub Copilot | MCP registration |
| Z.ai Code | MCP registration |
| ChatGPT | Cloud connector, nothing to install |
| Gemini CLI | MCP 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:
- 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.
- Secret leaks and unsafe shortcuts: static prompt rules in
.cursorruleswear off mid-session. Agents hardcode fallback credentials, disable TLS checks, or stage.envfiles withgit add .. - 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.
| Outcome | What changes for your team | How it is enforced |
|---|---|---|
| Clean code on the first pass | Agents 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 git | Hardcoded 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 & ROI | Teammates 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 agents | How TokenSafe fixes it | The 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:
| Capability | What it solves | How it works | Impact |
|---|---|---|---|
| 1. Architecture Graph<br>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<br>smart_read_file | F
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
