TokenShrink

Cut your LLM token usage by 30–60% on every message. Zero API calls. Zero cost. Works everywhere.

Before: "I was wondering if you could please help me understand how transformer
         neural networks work and why they have been so effective in the field
         of natural language processing, if you don't mind."
         → 47 tokens

After:  "Help me understand how transformer neural networks work and why they're
         so effective in NLP."
         → 18 tokens

Saved:  29 tokens  (62%)  — instant, local, $0.00

---

Why this matters

Claude Opus 4 costs $15 per million input tokens. If you send 500 words per message, 100 times a day, that's ~12,500 tokens → $0.19/day → $68/year. TokenShrink cuts that in half, automatically, with no quality loss.

For teams and heavy users, the savings compound fast:

• 10 developers × 100 messages/day = $680/year saved at zero cost
• API automation at scale = savings in the thousands per month

---

Install

Terminal / CLI (all platforms)

npm install -g tokenshrink

Or one-command full install (Claude Desktop + CLI + shell aliases):

curl -fsSL https://raw.githubusercontent.com/lhr-present/tokenshrink/master/install.sh | bash

Claude Desktop (MCP — auto-compresses every message silently)

# After install.sh, restart Claude Desktop, then:
# Click + → select "auto_compress" once per conversation
# Every message >30 words compresses automatically. Invisible to the user.

Claude Code CLI

claude mcp add --scope user tokenshrink -- node ~/.tokenshrink/mcp/server.js

---

Usage

# Compress and see stats
tokenshrink "I was wondering if you could help me understand transformers"

# Quiet mode — compressed text only (pipe-friendly)
tokenshrink -q "I was wondering if you could help me understand transformers"

# Pipe into clipboard
echo "verbose prompt here" | tokenshrink -q | pbcopy    # Mac
echo "verbose prompt here" | tokenshrink -q | xclip -sel clip  # Linux

# Compression modes
tokenshrink --mode balanced  "..."   # 30-50% — natural language (default)
tokenshrink --mode extreme   "..."   # 50-70% — telegram style
tokenshrink --mode technical "..."   # ~25%   — preserves all code/variable names

# JSON stats
tokenshrink --stats "your prompt"

Shell aliases (added automatically by install.sh):

alias ts='tokenshrink'
alias tsc='tokenshrink -q | xclip -sel clip && echo "✓ compressed → clipboard"'

---

What it removes

TokenShrink applies 100+ pre-compiled rules at under 2ms per message:

Category	Example → Compressed
Filler openers	"I was wondering if you could..." → removed
Politeness hedges	"please", "if you don't mind" → removed
Verbose phrases	"in order to" → "to", "due to the fact that" → "because"
Nominalizations	"make a decision" → "decide", "make an attempt" → "try"
Passive bloat	"has been completed" → "has completed"
Academic filler	"it is important to note that" → "note:"
Turkish support	"lütfen", "acaba", polite openers → removed

Code blocks, URLs, and quoted strings are never touched.

---

Platforms

Platform	Method	Status
Terminal	tokenshrink CLI	✓ Available now
Claude Desktop	MCP auto_compress	✓ Available now
Claude Code CLI	MCP server	✓ Available now
claude.ai	Chrome/Firefox extension	🔜 Coming soon
VS Code	Extension	🔜 Coming soon
ChatGPT / Gemini	Browser extension	🔜 Coming soon

---

MCP tools (Claude Desktop / Claude Code)

After install, these tools are available in Claude:

Tool	Description
compress	Compress text + return stats
compress_and_use	Compress and return only the compressed text
compression_stats	Session token savings summary
set_config	Set Groq API key for higher-quality compression

Optional Groq upgrade — get 14,400 free LLM-quality compressions/day:

Get free key at console.groq.com → tell Claude: "set my groq key to gsk_..."

---

Architecture

Input text
    │
    ▼
[Mask protected regions]  ← code blocks, URLs, quoted strings
    │
    ▼
[100+ regex rules]         ← filler, hedges, verbose phrases, nominalizations
    │                         Turkish rules if Turkish detected
    ▼
[Cleanup + normalize]      ← whitespace, capitalization, dedup
    │
    ▼
[Unmask protected regions]
    │
    ▼
Compressed output          ← zero API calls, <2ms, runs locally

---

Contributing

Pull requests welcome. To add rules, edit src/core/localCompressor.js. Rules must be pre-compiled regex (no dynamic regex in hot path) and must not match inside code blocks or URLs.

---

Support the project

If TokenShrink saves you money, consider:

• ⭐ Star this repo
• Sponsor on GitHub
• Share with your team
• Send crypto (every bit helps keep this free)

Crypto donations:

Network	Address
Solana (SOL)	H45tgS8vBmDzwNLAjRv9XQUESbU6GzwW8zx7eXxU5ysf
Ethereum (ETH)	0xC9bDb4a80d2e0c5b8205230bF0B37e66E71f5cE0

TokenShrink Pro (coming soon) — VS Code extension + team dashboard + unlimited Groq LLM compression. Join the waitlist: open an issue with title [Pro waitlist].

---