Token Saver

token-saver

> MCP plugin that alerts you when AI token usage is wasteful. Works with Claude Code, Cursor, Windsurf, Zed, Continue.dev — any MCP-compatible client, any model. Fires warnings, errors, and alerts on large outputs, verbose logs, and repetitive history. Auto-suppresses noise to keep your context lean.

[](https://github.com/flightlesstux/token-saver/actions/workflows/ci.yml) [](https://www.npmjs.com/package/token-saver-mcp) [](LICENSE) [](https://nodejs.org)

---

Overview

In agentic coding sessions, AI model responses often contain massive log outputs, repeated tool results, or near-duplicate history entries — all of which are re-sent on every turn, burning tokens. token-saver monitors every output and tells you when something is wasteful, so you can suppress it before it poisons your context window.

Works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Zed, Continue.dev, and any other tool that speaks the Model Context Protocol. No dependency on any specific AI provider or API — token-saver analyzes plain text and is model-agnostic by design.

Core value proposition: Most token waste in long AI sessions comes from outputs nobody actually reads — stack traces, verbose logs, repeated file contents. token-saver catches these early and tells you exactly why and how much you're wasting.

---

How it works

Your AI model output (Claude, GPT, Gemini, or any other)
        │
        ▼
  check_output          ← estimates tokens, detects log/noise patterns
        │
        ▼
  alert level           ← info / warning / error / alert
        │
        ▼
  shouldSuppress        ← true if output matches suppression criteria
        │
        ▼
  get_session_stats     ← cumulative waste report for the session

---

Installation

Three ways — pick what suits you:

Option A — npx (no install, always latest)

No global install needed. Add directly to your MCP client config:

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

Option B — npm global

npm install -g token-saver-mcp

Then add to your MCP client config:

{
  "mcpServers": {
    "token-saver-mcp": {
      "command": "token-saver-mcp"
    }
  }
}

Option C — install directly from GitHub

npm install -g github:flightlesstux/token-saver

Same config as Option B. Works without a build step — compiled output is included in the repo.

---

Tools

| Tool | Description | |------|-------------| | set_mode | Switch mode: off (default, silent) · monitor (analyze only) · active (full suppression). Start here. | | check_output | Analyze a text output. Returns alert level, token count, suppression flag, and detected patterns. | | analyze_history | Scan a messages array for near-duplicates and ignored log outputs. Returns suggested truncation and savings estimate. | | get_session_stats | Cumulative session statistics: tokens analyzed, suppressed, saved, and alert counts. | | reset_session_stats | Reset session statistics to zero. | | set_thresholds | Override warning/error/alert token thresholds and suppression flags for the current session. |

---

Example usage

1. Enable the plugin (off by default)

{ "name": "set_mode", "arguments": { "mode": "active" } }

{ "mode": "active" }

2. Check a suspicious output

{ "name": "check_output", "arguments": { "text": "[INFO] server started\n[DEBUG] connection ok\n[TRACE] request received\n..." } }

{
  "alertLevel": "warning",
  "tokens": 87,
  "outputType": "log",
  "shouldSuppress": true,
  "reason": "Output matches log/noise patterns and will be suppressed",
  "detectedPatterns": [
    { "pattern": "\\[INFO\\]", "matchCount": 5, "description": "Log pattern matched 5 times" },
    { "pattern": "\\[DEBUG\\]", "matchCount": 5, "description": "Log pattern matched 5 times" }
  ]
}

3. Scan conversation history for waste

{ "name": "analyze_history", "arguments": { "messages": [ ...your messages array... ] } }

{
  "totalMessages": 6,
  "totalTokens": 114,
  "repetitiveMessages": [
    { "index": 2, "role": "user", "tokens": 19, "reason": "Near-duplicate of message 0" },
    { "index": 4, "role": "user", "tokens": 19, "reason": "Near-duplicate of message 0" }
  ],
  "suggestedTruncation": 2,
  "estimatedTokenSavings": 38,
  "alertLevel": "alert"
}

4. Session summary

{ "name": "get_session_stats", "arguments": {} }

{
  "turns": 5,
  "totalTokensAnalyzed": 1416,
  "totalTokensSuppressed": 201,
  "warningsFired": 2,
  "errorsFired": 0,
  "alertsFired": 1,
  "tokensSaved": 201
}

---

Proof test output

Run python3 test_live.py to verify the full mode/suppression/history flow locally:

============================================================
TOKEN-SAVER PROOF TEST
============================================================

[1] Default mode (off) — all analysis skipped
  [check_output] mode=off skipped=true
  [PASS] mode=off correctly skips analysis

[2] Switch to monitor mode
  [PASS] mode switched to monitor

[3] Short normal output → info
  [check_output] level=info tokens=3 suppress=False
    reason: Output is within normal bounds
  [PASS] info level, no suppression

[4] Large output (>1000 tokens) → warning or higher
  [check_output] level=warning tokens=1125 suppress=False
    reason: Output exceeds warning threshold (1125 tokens >= 1000)
  [PASS] warning level fired at 1125 tokens

[5] Log output in monitor mode → detected, not suppressed
  [check_output] level=info tokens=87 suppress=False
    patterns: 3 matched
  [PASS] patterns detected, suppression=false (monitor mode)

[6] Switch to active mode
  [PASS] mode switched to active

[7] Log output in active mode → suppressed
  [check_output] level=warning tokens=87 suppress=True
    reason: Output matches log/noise patterns and will be suppressed
  [PASS] suppressed 87 log tokens

[8] Repetitive history → alert
  totalMessages=6 totalTokens=114
  repetitive=5 savings=95 level=alert
  [PASS] 95 tokens saveable from repetitive history

[9] Session stats
  turns=5 analyzed=1416 suppressed=201 warnings=2 alerts=1
  [PASS] 201 tokens suppressed this session

============================================================
PROOF SUMMARY
============================================================
  Tokens suppressed this session : 201
  Turns analyzed                 : 5
  Warnings fired                 : 2
  Alerts fired                   : 1

  Overall: ALL CHECKS PASSED
============================================================

---

Alert levels

| Level | Trigger | |-------|---------| | info | Output is within normal bounds (= 24

• Any MCP-compatible AI client

---

FAQ

Does it work with non-Claude models and clients? Yes. token-saver has zero dependency on any AI provider or API. It analyzes plain text — Claude, GPT-4, Gemini, Mistral, Llama, whatever. Works with any MCP-compatible client: Claude Code, Cursor, Windsurf, Zed, Continue.dev.

Why is the default mode "off"? Intentional. Install it, verify it's there, then turn it on when you're ready. set_mode("monitor") to observe first, set_mode("active") for full suppression. Your MCP client (Claude) calls this for you when you ask — you don't touch JSON directly.

What's the difference between monitor and active mode? monitor — analyzes and reports waste, never suppresses. active — full mode, sets shouldSuppress: true on matching outputs so your client can skip feeding noise back into context.

Does it actually block or delete anything? No. It sets shouldSuppress: true on noisy outputs and explains why — but never intercepts or modifies any API call. Your client decides what to do with the signal.

How does token counting work? Fast heuristic: ~4 characters per token (English/code average). Not the exact tokenizer — that would add latency. Accurate enough to catch waste at scale.

What's the difference between warning, error, and alert? info — normal output. warning — over 1,000 tokens or log patterns detected. error — over 5,000 tokens. alert — over 10,000 tokens or repetitive ignored history detected.

Can I add custom log patterns? Yes. Add a logPatterns array to .token-saver.json with regex strings. Merged with built-in patterns.

Does it send data anywhere? No. Everything runs locally in memory. No telemetry. Stats evaporate when the MCP server stops. See [PRIVACY.md](PRIVACY.md).

Is it free? MIT license. Free forever. No SaaS, no subscription.

---

Contributing

Contributions are welcome — new detection heuristics, better suppression logic, benchmark improvements, and docs.

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. All commits must follow Conventional Commits. The CI pipeline enforces typechecking, linting, testing, and coverage on every PR.

---

License

[MIT](LICENSE) — flightlesstux.github.io/token-saver

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: flightlesstux
• Source: flightlesstux/token-saver
• License: MIT
• Homepage: https://token-saver.ai/

Install and usage instructions live in the source repository linked above.