Tokenectomy Razor

                                 ┌────────────────────────────────────────────────────────┐                                 │                   Autonomous Agents                    │                                 │  Claude Code • Cursor • Antigravity • Cline • Windsurf │                                 └───────────────────────────┬────────────────────────────┘                                                             │                                                             ▼ (HTTP / SSE Outbound Prompts)   ┌──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐   │                                 ⚡ TOKENECTOMY AI GATEWAY (127.0.0.1:8080)                                       │   │                                                                                                                  │   │  ┌─────────────────────────┐   ┌───────────────────────────┐   ┌──────────────────────────────────────────────┐  │   │  │   Zero-Cost Prompt      │   │   Zero-Leak Credential    │   │         Polyglot Trace Surgery               │  │   │  │         Cache           │   │         Redaction         │   │            (9 Languages)                     │  │   │  │  <1ms Hit • 100% Free   │   │  API Keys • JWTs • DB URIs│   │  node_modules • site-packages • .cargo       │  │   │  └───────────┬─────────────┘   └─────────────┬─────────────┘   └──────────────────────┬───────────────────────┘  │   │              │                               │                                        │                          │   │              └───────────────────────────────┼────────────────────────────────────────┘                          │   │                                              ▼                                                                   │   │                                 Smart Upstream Auto-Router                                                       │   │                         (Anthropic • OpenAI • Groq • Ollama Local)                                               │   └──────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────┘                                                  │                 ┌────────────────────────────────┼────────────────────────────────┐                 ▼                                ▼                                ▼       api.anthropic.com                  api.openai.com                   localhost:11434    (Claude 3.5 / 3.7 Sonnet)         (GPT-4o / o1 / o3-mini)              (DeepSeek / Llama)

⚡ Quick Start (10s)

0. Zero-Config One-Liner Wrapper (wrap)

Run any coding agent or test suite directly behind Tokenectomy's privacy & caching gateway with zero manual environment variable setup:

# Wrap Claude Code CLIrazor wrap -- claude
# Wrap Aider with DeepSeek or Ollama (Auto-Transpiled on the fly!)razor wrap -- aider --model deepseek/deepseek-chat
# Wrap test runs to scrub logs and prevent accidental credential leakagerazor wrap npm test

1. Launch the Standalone AI Gateway (Manual Mode)

npx -y tokenectomy-razor --proxy

💡 Smart Multi-Provider Auto-Routing & Universal LLM Transpiler ON by default! Tokenectomy automatically analyzes request paths and headers. Need to run Claude Code against DeepSeek or Ollama? Tokenectomy transparently transpiles Anthropic /v1/messages format into OpenAI /v1/chat/completions on-the-fly and vice-versa.

2. Connect Your Favorite Agent

Point your coding agent or CLI to the local gateway on 127.0.0.1:8080:

3. Real-Time FinOps & Security Dashboard

Open http://127.0.0.1:8080/dashboard in your browser to observe live token reductions, prompt cache hits, dollar savings, and redacted credentials in real time.

4. Companion MCP Server Setup (Sub-Cortex)

For agents calling deep diagnostic tools (get_error_context, analyze_code, apply_code_patch):

Claude Code CLI

claude mcp add tokenectomy npx -y tokenectomy-razor --mcp

Google Antigravity / Gemini CLI

agy mcp add tokenectomy-razor -- npx -y tokenectomy-razor --mcp

Cursor Composer (.cursor/mcp.json)

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

Claude Desktop (claude_desktop_config.json)

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

5. Terminal Piping & CLI Scrubbing

npm test 2>&1 | npx tokenectomy-razor

🛑 The Problem: Why Your AI Hits Rate Limits & Hallucinates

When your app crashes during development (Next.js, Express, FastAPI, Tokio), the runtime dumps hundreds of lines of third-party plumbing from node_modules or site-packages.

When you paste that raw crash dump into Cursor or Claude:

1. Eats Your 5-Hour Rate Limit: A single Express/Prisma error can dump 5,000 to 45,000 tokens of third-party library code you never wrote. A few crash loops easily burn your session limit.
2. Triggers AI Hallucinations: Claude gets lost in framework internals (node_modules/express/lib/router/layer.js or starlette/routing.py) and tries to edit library files instead of your actual application code.
3. Leaks Secrets & Credentials: Connection strings with raw database passwords, JWT bearer tokens, and cloud keys embedded in error traces get forwarded to external model servers.

Raw Terminal Crash (45,820 tokens + Leaked Secrets)     │     ▼  <0.2ms Local Rust DFA Engine[Redact Passwords & Keys] ──► [Strip Third-Party Framework Frames] ──► [Isolate Root Cause]     │     ▼Clean Context (118 tokens • Zero Secrets • Sub-millisecond)

🔍 Before & After Comparison

❌ Without Tokenectomy: AI Hallucinates & Burns Context

TypeError: Cannot read properties of undefined (reading 'token')    at loadComponents (/app/node_modules/next/dist/server/load-components.js:14:2)    at renderToHTML (/app/node_modules/next/dist/server/render.js:50:5)    at nextServer (/app/node_modules/next/dist/server/next-server.js:80:12)    at processTicksAndRejections (node:internal/process/task_queues:95:5)    at runMicrotasks (node:internal/process/task_queues:120:3)    at checkoutHandler (/app/pages/api/checkout.ts:42:15)Database connection failed: postgresql://admin:[email protected]:5432/primaryAPI key leaked: sk-ant-api03-abcdef1234567890abcdef1234567890

What Claude does: Analyzes load-components.js and next-server.js, speculates on Webpack / Next.js internals, and leaks connection credentials to remote inference logs.

✅ With Tokenectomy: Clean Context & Instant Fix

// [Tokenectomy Surgery: 5 internal framework frames pruned (83.3%)]// Source: /app/pages/api/checkout.ts:42:1542 |   const sessionToken = req.headers.authorization.token;   |                                                  ^ TypeError: Cannot read properties of undefined (reading 'token')🛡️ [CONNECTION_STRING_REDACTED]🛡️ [ANTHROPIC_KEY_REDACTED]

What Claude does: Instantly identifies that line 42 in checkout.ts attempted to access .token on undefined headers. Suggests optional chaining req.headers.authorization?.token immediately. Credentials redacted before transmission.

🔬 Verifiable Benchmarks

All performance claims are hardware-grounded and independently reproducible on physical hardware (measured on 10-Core Intel Core i5-1235U @ 15W running Arch Linux, Kernel 6.13):

Hardware Dependency Notice: Performance is hardware-dependent; reported throughput represents measured results on the specified test hardware (10-Core Intel Core i5-1235U @ 15W TDP). Throughput scales with higher TDP desktop/server CPUs and faster memory buses. Developers are encouraged to independently audit performance using the reproduction command below.

$ cargo test --release --test stress_benchmark -- --nocapture
=====================================================================================🧪 TOKENECTOMY OSS VERIFIABLE HEAVY STRESS BENCHMARK (100% REPRODUCIBLE IN OSS)   Hardware: 10-Core / 12-Thread Intel Core i5-1235U | OS: Arch Linux | Kernel Telemetry Active   Initial Baseline Process Memory (VmRSS): 3.45 MB=====================================================================================
🔥 [TEST 1/3] QUARTER-MILLION LINES LOG REDACTION TORTURE (250,000 LINES / 25MB+ BUFFER)  ├── Buffer Size: 24.44 MB (250000 lines)  ├── Redaction Latency: 471.05ms (51.9 MB/sec)  ├── Line Throughput: 530,735 lines/sec  ├── Peak Memory (VmRSS): 76.05 MB (Delta: +72.60 MB)  └── Status: ✅ PASSED (100% of 250,000 lines sanitized, zero memory balloon)
🔥 [TEST 2/3] REDOS CATASTROPHIC BACKTRACKING TORTURE (50,000 CHARS PAYLOAD)  ├── Attack Payload Size: 50,082 characters  ├── Execution Latency: 1.165 ms  └── Status: ✅ PASSED (Linear O(N) evaluation, ReDoS-resistant on tested payloads)
🔥 [TEST 3/3] HIGH-CONCURRENCY TORTURE (100 PARALLEL OS THREADS)  ├── Thread Concurrency: 100 concurrent OS threads  ├── Successful Operations: 100/100 (100.0%)  ├── Total Elapsed: 11.31ms  ├── Concurrency Throughput: 17,688 ops/sec  ├── Final VmRSS: 78.99 MB  └── Status: ✅ PASSED (Zero race condition, zero deadlock)
=====================================================================================🏆 TOKENECTOMY OSS STRESS BENCHMARK: 3/3 PASSED (100% GREEN)   Total Suite Duration: 580.83ms   Bounded Final VmRSS: 78.99 MB=====================================================================================test test_oss_heavy_stress_benchmark ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.58s

🛡️ Automated Redaction & Secret Sanitization Benchmark

Evaluated across an internal benchmark test fixture (tests/fixtures/) of 12 polyglot crash traces (Rust, Python, TypeScript, Go, YAML) containing 22 ground-truth credentials and clean negative controls. Evaluated head-to-head against Gitleaks v8.30.1 (default ruleset).

Architectural Note: Gitleaks is designed primarily as a repository commit/diff scanner, not an in-memory runtime trace redactor. Tokenectomy Razor is engineered specifically for runtime stream sanitization and stack trace surgery.

1. Per-Category Precision, Recall & F1-Score

2. Head-to-Head Performance & Architectural Summary

3. Token Reduction & LLM Context Savings (tiktoken cl100k_base)

🔌 Advanced Agent & Gateway Configuration

1. Multi-Provider AI Gateway Options (--proxy)

Tokenectomy's gateway runs locally on 127.0.0.1:8080 with zero manual configuration. In complex development environments or containerized agent topologies, you can customize binding and routing:

# Default Smart Auto-Routing (routes Anthropic, OpenAI, and Ollama requests dynamically):razor --proxy
# Safety Circuit Breaker: Prevent runaway agent loops from burning your hourly budget or 5-hour window:razor --proxy --max-hourly-tokens 200000
# Resilient 429 Auto-Retry: Automatically pause and retry when hitting upstream rate limits (default: on):razor --proxy --max-retries 5
# Explicit upstream override (e.g. Groq, vLLM, or OpenRouter):razor --proxy --upstream-url https://api.groq.com/openai/v1
# Secure remote container binding with mandatory bearer token:razor --proxy --proxy-bind 0.0.0.0:8080 --allow-remote --proxy-token "$MY_GATEWAY_TOKEN"

Real-Time Metrics & Prometheus Export

Tokenectomy exposes live FinOps and token economics data via JSON:

curl http://127.0.0.1:8080/v1/metrics

Returns instant telemetry for rate_limits_mitigated, circuit_breaker_trips, last_latency_ms, current_hourly_tokens, cache_hits, cache_tokens_saved, and estimated_cost_saved_usd.

2. Standalone CLI & Terminal Scrubbing

When debugging or piping terminal test output directly:

# Pipe terminal test failures through the surgical redactor:npm test 2>&1 | razor --scrub
# Sanitize a specific raw log file:razor --scrub --file /var/log/app/error.log > sanitized.log
# Offline local air-gapped mode (zero external network calls):cat failure.log | razor --scrub --local-only

🛠️ Exposed MCP Tools

Tokenectomy Razor complies with Glama Grade A Tool Definition Quality Score (TDQS) with explicit parameter boundaries:

🌐 Supported Polyglot Ecosystems

📦 Installation Options

Method 1: Instant via npx (Zero Toolchain Setup)

npx -y tokenectomy-razor --mcp

Method 2: Cargo (crates.io)

cargo install tokenectomy

Method 3: Precompiled Standalone Binaries

Zero-dependency, standalone release binaries available on GitHub Releases:

• Linux: x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-gnu
• macOS: aarch64-apple-darwin (Apple Silicon M1/M2/M3/M4), x86_64-apple-darwin (Intel)
• Windows: x86_64-pc-windows-msvc.exe

Method 4: Multi-Arch Docker Container (GHCR)

docker pull ghcr.io/tokenectomy-labs/razor:latestdocker run -i ghcr.io/tokenectomy-labs/razor:latest --mcp

⚖️ Edition Comparison

Need Enterprise AST Self-Healing? Explore the Sentinel Tier

🗺️ Roadmap & Milestones

🔒 Security & Invariants

• Local Execution by Default: All stack trace parsing, frame pruning, and secret redaction execute locally on physical hardware.
• Documented Network Egress: In MCP server mode, search_stack_overflow is the sole tool with outbound network egress (HTTPS to api.stackexchange.com). The payload is strictly limited to sanitized, redacted error signature text (no code lines, no local paths, zero credentials). In air-gapped environments, use --local-only to disable network search entirely.
• Deterministic Linear-Time Pattern Matching: All pattern matchers utilize non-backtracking DFA regex engines ($O(N)$ linear time) and Aho-Corasick automaton evaluation.
• Path Traversal Boundary Isolation: File operations are strictly locked within the active workspace root (CWD). Path traversals (../) and unauthorized symlinks are blocked.
• Safe Rust Implementation: Core execution paths enforce safe Rust memory guarantees with bounded stream readers (.take()) preventing resource exhaustion.

For vulnerability disclosures, please review our Security Policy.

⚖️ Legal & Downstream Fork Disclaimer

Tokenectomy Razor is provided strictly for lawful developer productivity, observability, log surgery, and defensive credential redaction. Any downstream forks, clones, redistributions, or private deployments operate completely independently of the original authors. Tokenectomy Labs and its maintainers assume zero liability for unlawful, malicious, or unauthorized actions committed by third parties using this codebase or derivatives thereof. All downstream operators bear 100% individual responsibility for compliance with local and international cybersecurity laws. See DISCLAIMER.md for full legal terms.

❓ Frequently Asked Questions (FAQ)

How does Tokenectomy Razor prevent Claude Code & Cursor from hitting rate limits?

When tests or terminal builds crash, frameworks like Next.js, Express, Jest, and Django dump thousands of internal stack frames (node_modules, site-packages). Sending raw 5,000-line crash logs consumes 15,000 to 45,000 tokens per prompt, draining your 5-hour session limit in minutes. Tokenectomy Razor intercepts logs and strips 95% of non-actionable framework plumbing, reducing a 40,000-character crash log to under 200 essential tokens in <0.2ms.

How do I stop Cursor from sending node_modules error logs to LLMs?

Run Tokenectomy Razor as a local AI Gateway reverse proxy (npx -y tokenectomy-razor --proxy). In Cursor settings, point your OpenAI Base URL to http://127.0.0.1:8080/v1. Any terminal error output pasted or referenced by Composer will be automatically sanitized, scrubbed, and cached on the fly before reaching model servers.

How does Tokenectomy prevent credential leakage in error logs?

All log surgery and secret redaction execute 100% locally on your machine in memory before outbound transmission. Razor uses deterministic linear-time regex and Aho-Corasick automata to detect and redact PostgreSQL/MongoDB connection URIs, JWT bearer tokens, and cloud API keys with [REDACTED] tokens. Zero cloud egress is required for scrubbing.

🤝 Community & Resources

• 🌐 Official Website
• 📖 Documentation
• 🏗️ System Architecture
• 📋 Changelog
• 🤝 Contributing Guidelines
• 🔒 Security Policy
• ⚖️ Disclaimer & Liability