copium-ai 0.26.2

The Context Optimization Layer for LLM Applications - Cut costs by 65-90%

Copium

The context compression layer for LLM applications

65–94% fewer tokens. Zero quality loss. Drop-in proxy for Claude, GPT, Gemini, Bedrock, and local LLMs.

Docs · Install · Proof · Alternatives · Agent Guides · GitHub

---

What is this?

You know how your AI coding assistant (Claude Code, Cursor, Copilot, etc.) sometimes slows down mid-session, starts forgetting things it read earlier, or just becomes weirdly bad at tasks it was great at ten minutes ago? That's the context window filling up. Every file your agent reads, every command it runs, every tool output it processes — it all piles into a prompt that the AI has to re-read from scratch on every single message. You're paying for all of it, every time.

Copium sits between your agent and the AI provider and compresses everything before it goes out. It's a local proxy — your data never leaves your machine. Same answers. Fraction of the tokens.

The gains are real: 1.4 billion tokens saved across 50K+ sessions in production.

---

Get started (60 seconds)

Install

# Recommended — installs globally in an isolated environment
pipx install copium-ai          # or: pipx install "copium-ai[proxy]"

# If you use uv
uv tool install copium-ai       # or: uv tool install "copium-ai[proxy]"

# Project-local install (less recommended for CLI use)
pip install "copium-ai[proxy]"

Why pipx? It installs CLI tools into isolated environments so copium is available globally without polluting any project's dependencies. If you don't have pipx: pip install pipx && pipx ensurepath.

Start the proxy

Recommended — background daemon (survives shell exit):

copium start               # starts on http://localhost:8787, detaches from terminal
copium status              # check health, port, today's savings
copium stop                # stop gracefully (prints session summary)
copium restart             # restart to pick up config changes

One-shot foreground mode (blocks the terminal):

copium proxy               # or: copium run

Point your agent at the proxy:

# Claude Code
export ANTHROPIC_BASE_URL=http://localhost:8787

# Cursor / Aider / OpenCode / any OpenAI-compatible client
export OPENAI_API_BASE=http://localhost:8787/v1

# Watch the savings live
copium status
# or: copium tui  (live terminal dashboard)
# or: open http://localhost:8787/dashboard in your browser

That's it. No config files. No code changes. Copium automatically compresses every request.

---

Connect your AI agent

Claude Code

copium wrap claude

That single command starts the proxy and configures Claude Code to route through it. When you're done, copium unwrap claude restores everything.

Alternatively, set it manually:

copium run &
export ANTHROPIC_BASE_URL=http://localhost:8082
claude  # or claude-code, or claude --dangerously-skip-permissions

Cursor

copium run &
# In Cursor settings → OpenAI API Base URL:
# http://localhost:8082/v1

Or via environment:

export OPENAI_API_BASE=http://localhost:8082/v1
cursor .

OpenCode

OpenCode uses the OpenAI-compatible API format:

copium run &
export OPENAI_BASE_URL=http://localhost:8082/v1
opencode

Or set it permanently in your OpenCode config:

{
  "openai": {
    "baseURL": "http://localhost:8082/v1"
  }
}

Aider

copium wrap aider
# or manually:
aider --openai-api-base http://localhost:8082/v1

Codex (OpenAI)

copium wrap codex
# Automatically patches ~/.codex/config.toml
# Undo with: copium unwrap codex

GitHub Copilot

copium wrap copilot

This routes Copilot through Copium while keeping your existing auth. Supports both BYOK and subscription modes.

Mistral / Vibe

copium wrap vibe

VS Code Extensions

Cline

copium wrap cline
# Then configure in VS Code:
#   Settings > Cline > API Provider > Anthropic
#   Base URL: http://localhost:8082

Continue

copium wrap continue
# Auto-injects into .continue/config.json

Antigravity (Google)

Note: As of June 2026, Google transitioned Gemini CLI to Antigravity CLI. The new Antigravity 2.0 Desktop App and CLI use Google Sign-In OAuth authentication and route through Vertex AI — they do not expose proxy/base URL settings. Copium cannot currently intercept Antigravity traffic.

Workarounds:

• Use the old Gemini CLI (if available) which routes through Cloud Code Assist
• For enterprise users: configure Vertex AI with Copium proxy separately
• Wait for Google to add proxy configuration support

Any HTTP client / custom app

If your tool lets you set a base URL or API endpoint:

http://localhost:8082         → Anthropic-compatible
http://localhost:8082/v1      → OpenAI-compatible
http://localhost:8082/bedrock → AWS Bedrock
http://localhost:8082/vertex  → Vertex AI (Google Cloud)

As a Python library

If you don't want the proxy at all and just want to compress messages inline:

import json
from copium import compress

# Works with any messages list you'd send to an LLM
data = json.load(open("data.json"))   # e.g. 500-item JSON array
result = compress([{"role": "user", "content": json.dumps(data)}])

print(f"Saved {result.compression_ratio:.1%} tokens")
# → Saved 64.8% tokens

As an MCP server

pip install "copium-ai[mcp]"

Then add to your MCP client config:

{
  "mcpServers": {
    "copium": {
      "command": "copium",
      "args": ["mcp"]
    }
  }
}

Exposes three tools: copium_compress, copium_retrieve, copium_stats.

---

How it works

You don't need to understand this to use Copium. But if you're curious:

 Your agent / app
   (Claude Code, Cursor, Aider, OpenCode, your own code...)
        |   prompts, tool outputs, logs, RAG results, files
        v
    +----------------------------------------------------+
    |  Copium   (runs locally — your data stays here)   |
    |  -------------------------------------------------  |
    |  ContentRouter → SmartCrusher  | Kompress          |
    |                  Session Dedup | Error Compressor  |
    |                  Cache Aligner | TOON Encoder      |
    |                  Diff Response | Output Compressor |
    +----------------------------------------------------+
        |   compressed prompt (same meaning, fewer tokens)
        v
 LLM provider  (Anthropic, OpenAI, Gemini, Ollama, Bedrock...)

Each component targets a specific kind of waste:

Component	What it removes	Typical savings
ContentRouter	Routes each chunk to the best compressor	20–60%
SmartCrusher	Compresses JSON arrays, repeated tool outputs	40–95%
Session Dedup	Re-sent file content across conversation turns	30–70%
Error Compressor	Verbose stack traces → structured error cards	50–80%
TOON Encoder	JSON arrays → pipe-delimited tables	15–40%
Cache Aligner	Stabilizes prefixes for provider KV cache hits	10–20%
Diff Response	Sends diffs for repeated tool calls	Up to 95%
Output Compressor	Trims verbose assistant responses	15–40%

The pipeline runs in ~52ms median overhead. Your agent doesn't notice it's there.

---

Proof

Compression on real content types

Content Type	Before (tokens)	After (tokens)	Savings
JSON arrays (100 items)	3,163	297	90.6%
Build logs (200 lines)	2,412	148	93.9%
Shell output (200 lines)	3,238	469	85.5%
JSON arrays (500 items)	9,526	1,614	83.1%
Repeated tool outputs	10,000	1,500	85%
Git diffs	3,000	300	90%

Quality preserved — LLM accuracy benchmarks

The most important thing: does the AI still give correct answers?

Benchmark	Baseline (no compression)	With Copium	Delta
HTML Extraction (F1)	0.958	0.919	−0.039
HTML Recall	—	0.982	98.2% content preserved
JSON Needle Finding	4/4	4/4	100% accuracy at 87.6% compression
GSM8K (Math)	0.870	0.870	+/−0.000
TruthfulQA (Factual)	0.530	0.560	+0.030 (improved)

Run these yourself:

pip install "copium-ai[evals]" && pytest tests/test_evals/ -v -s

Production telemetry (250+ instances, 50K+ sessions)

Metric	Value
Total tokens saved	1.4 billion
Median proxy overhead	52ms
Median compression (all requests)	4.8%
Heavy tool-use sessions	40–80%

Most requests are short conversational turns — the median 4.8% compression is accurate for those. Where Copium pays for itself is in long agentic sessions with accumulated tool outputs, logs, and search results: that's where you see 40–94%.

---

When does it help?

You'll see real gains if you:

• Run AI coding agents daily (Claude Code, Cursor, Codex, etc.)
• Use local LLMs and need to stay within context limits
• Work with verbose tool outputs — build logs, JSON, search results, git diffs
• Want to extend context window life on quantized models (Q4_0, Q8_0)
• Use Copilot or other subscription services and want more out of each turn

It won't help much if you:

• Only send short conversational prompts (median savings: 4.8%)
• Already use a provider's native compaction and don't need more
• Work in a sandboxed environment where local processes can't run

---

Compared to alternatives

Copium runs locally, covers every content type, works with every major framework, and supports both cloud and local LLMs.

	Scope	Deploy	Local LLMs	Reversible	Observability
Copium	All context — tools, RAG, logs, files, history	Proxy, library, MCP	✅	✅ (CCR)	Full metrics
Kompact	Prompt text & schemas	Python library	❌	❌	❌
Claw Compactor	Prompt text & structure	Python library	❌	❌	❌
Headroom	All context	Proxy, library, middleware, MCP	❌	✅ (CCR)	❌
ContextZip	Session history / JSONL	Python CLI	✅	✅ (Static)	❌
RTK	CLI command outputs only	CLI wrapper	✅	❌	❌
lean-ctx	CLI commands, MCP tools	CLI wrapper, MCP	✅	❌	❌
Compresr, Token Co.	Text sent to their API	Hosted API call	❌	❌	❌
OpenAI Compaction	Conversation history	Provider-native	❌	❌	❌

vs Kompact

Kompact is a Python library focused strictly on compressing prompt text and JSON schemas. Copium is a full architecture handling streaming tool outputs, multi-turn session deduplication, and provider caching.

	Copium	Kompact
Architecture	Proxy, MCP, Library	Library only
Tool Outputs	SmartCrusher (statistical)	Regex/Text truncation
Session Dedup	✅ Cross-turn retrieval	❌
Performance	Core logic in Rust	Pure Python
Safety	Reversible (CCR)	Lossy

vs Claw Compactor

Claw Compactor is a high-quality 14-stage pipeline for compressing prompts, but it's restricted to library deployment and irreversible compression. Copium incorporates similar quality-gated pipelines but wraps them in a zero-code proxy with reversible fail-safes.

	Copium	Claw Compactor
Zero-Code Usage	✅ Drop-in Proxy	❌ Library only
Reversibility	✅ Compress-Cache-Retrieve	❌ Irreversible
Quality Gates	✅ Auto-reverts on inflation	❌ Manual
Provider Support	Universal (Anthropic, Bedrock, etc)	Manual injection

vs Headroom

Both Copium and Headroom compress AI agent context. Key differences:

	Copium	Headroom
Local LLM support	✅ (Ollama, VLLM, llama.cpp)	❌
KV cache precision detection	✅ (auto-detect Q4_0/Q8_0/FP16)	❌
Context paging	✅ (virtual memory for LLM context)	❌
Telemetry	Off by default (opt-in)	On by default (opt-out)
CCR integrity checks	✅ (SHA-256 verification)	❌
Windows support	✅ Pre-built wheels (CI tested)	Manual install only

vs ContextZip

ContextZip operates on static conversation archives (e.g., .jsonl files) to compress past sessions. Copium operates on live agent traffic in real time.

	Copium	ContextZip
Target	Live HTTP traffic (Proxy)	Static session files (.jsonl)
Mechanism	Real-time compression / routing	Post-hoc deduplication
Use Case	While the agent is actively running	Archiving or resuming past chats

vs RTK

RTK saves 60-90% on CLI stdout only (rtk git status). Copium saves 40-90% on all context — tool outputs, file reads, search results, conversation history, RAG chunks — and includes RTK for free via copium wrap.

Key differences:

	RTK	Copium
Scope	CLI stdout only	Everything (tools, files, search, history)
Setup	rtk git status per command	copium wrap claude (one command)
Reversibility	None	CCR — LLM can retrieve originals
Observability	None	Full metrics dashboard
Strangeness tax	High (abbreviated output confuses LLMs)	Low (quality gate preserves critical markers)

Migration: pip install "copium-ai[proxy]" && copium wrap claude — drops in as a superset of RTK. Use --rtk-only to start with RTK-only compression, then unlock proxy features when ready.

vs Provider-native compaction

Provider compaction (OpenAI, Anthropic) only compresses conversation history. Copium compresses everything — tool outputs, logs, RAG results, files — and routes each content type to the best compressor before it ever reaches the provider.

---

Local LLM support

If you run Ollama, VLLM, or llama.cpp, Copium has a specific feature you won't find elsewhere: KV cache precision detection.

When a quantized model's KV cache is too full, accuracy collapses — not gradually, but off a cliff:

Q4_0 KV Cache at 32K context = 2% accuracy (vs 37.9% for FP16)

Copium detects your model's quantization type and starts compressing aggressively before you hit that cliff.

copium doctor   # detects your local LLM setup and makes recommendations

It also supports cold/hot context paging — effectively virtual memory for your LLM's context window, cutting context by up to 93% for long sessions.

---

Configuration

Create copium.json in your project root to customize behavior:

{
  "mode": "optimize",
  "cache_aligner": { "enabled": true },
  "session_dedup": {
    "enabled": true,
    "similarity_threshold": 0.85
  },
  "error_compressor": {
    "enabled": true,
    "max_stack_frames": 3,
    "preserve_security_warnings": true
  }
}

Disable specific transforms per request:

curl -H "X-Copium-Disable: toon,code_compressor" \
     http://localhost:8082/v1/chat/completions

Environment variables:

export COPIUM_PORT=8082
export COPIUM_HOST=0.0.0.0
export COPIUM_LOG_LEVEL=debug
export COPIUM_CCR_TTL_SECONDS=1800   # how long compressed data is cached

Compression presets

copium proxy --preset minimal      # Structural transforms only; safest
copium proxy --preset standard     # Full stack; recommended (default)
copium proxy --preset aggressive   # Maximum savings; more aggressive
copium proxy --preset local-llm    # Optimized for Ollama/VLLM/llama.cpp
copium proxy --preset lossless     # Zero quality loss transforms only

# Inspect any preset without starting the proxy:
copium preset aggressive

View your savings

copium status                  # proxy health, uptime, today's savings
copium status --verbose        # also show all-time stats
copium status --json           # machine-readable JSON
copium stats                   # detailed savings breakdown
copium stats --period session  # current session only
copium stats --json            # machine-readable output

Check agent status

copium agents                  # list all detected agents and wrap status
copium agents --installed      # show only installed agents
copium agents --json           # machine-readable output

View logs

copium logs                    # show last 100 lines of proxy logs
copium logs -n 50              # show last 50 lines
copium logs -f                 # follow logs in real time (Ctrl+C to stop)
copium logs --level ERROR      # filter by log level

Version and diagnostics

copium version                 # show version, Python, platform, install method
copium version --json          # machine-readable output
copium doctor                  # diagnose installation and configuration

---

Always-on Background Service

The biggest daily friction with a proxy tool is keeping it running. Copium solves this two ways:

Daemon mode (recommended for daily use)

copium start                  # start proxy, detach from terminal — survives shell exit
copium stop                   # stop gracefully (shows session summary first)
copium restart                # restart (picks up config changes)
copium status                 # check running/stopped, uptime, savings today
copium status --json          # machine-readable output (for scripts / shell prompts)

copium start auto-creates a deployment profile on first run. The PID file lives at ~/.copium/deploy/default/runner.pid; logs at ~/.copium/deploy/default/runner.log.

Flags:

copium start --port 9090          # custom port
copium start --preset aggressive  # aggressive compression
copium start --memory             # enable persistent memory
copium start --no-wait            # don't wait for ready signal (fire-and-forget)

Auto-start on login (system service)

For teams or power users who want the proxy running before they even open a terminal:

copium service install        # install as systemd user unit (Linux) or launchd agent (macOS)
copium service status         # show service health
copium service logs           # tail service logs (uses journalctl on Linux)
copium service logs -f        # follow logs continuously
copium service remove         # uninstall the service (keeps your data)

After copium service install, the proxy starts automatically at login and restarts on failure. You never have to think about it again.

Shell completion

Enable tab completion for faster command lookup:

# Bash
copium completions bash >> ~/.bash_completion

# Zsh
copium completions zsh >> ~/.zshrc

# Fish
copium completions fish > ~/.config/fish/completions/copium.fish

# PowerShell
copium completions powershell | Out-String | Invoke-Expression

After installing, reload your shell or run source ~/.zshrc (zsh) / source ~/.bash_completion (bash).

Platform details:

Platform	Mechanism	Config location
Linux	systemd user unit	~/.config/systemd/user/copium.service
macOS	launchd LaunchAgent	~/Library/LaunchAgents/com.copium.default.plist
Windows	Windows Service / Task Scheduler	via sc.exe or schtasks

Architecture (for the curious)

The full request pipeline:

Request → Cache Aligner → Differential Response → Session Dedup
        → KV Cache Detection → Content Router → Error Compressor
        → Paging → Output Compressor → TOON Encoder → Provider

ContentRouter decides which compressor to use for each piece of content. It detects the content type (JSON array, log output, code, HTML, search results, git diff) and routes it to the appropriate transform. The routing decision is logged for transparency.

SmartCrusher uses statistical analysis — variance-based change point detection, Kneedle algorithm for optimal K, BM25 + embedding relevance scoring — to compress tool output arrays while keeping the items the LLM actually needs. It never generates text; the output contains only items from the original array.

CCR (Compress-Cache-Retrieve) makes compression reversible. When SmartCrusher compresses a 1,000-item array down to 20 items, the original 1,000 items are stored locally (SHA-256 verified). The LLM receives a retrieval marker. If it needs more data, it calls copium_retrieve(hash, query) and gets the relevant subset. Worst case: the LLM retrieves what it needs. Best case: it never needs to.

Session Dedup tracks content hashes (exact SHA-256 + MinHash for near-duplicates) across the entire conversation. If a file read from turn 3 shows up again in turn 15, only a reference marker goes to the LLM. The proxy overhead for this lookup is sub-millisecond.

TOON Encoder converts JSON arrays into pipe-delimited tables — the same semantic content, dramatically fewer tokens. [{"name": "alice", "age": 30}, {"name": "bob", "age": 25}] becomes name | age\nalice | 30\nbob | 25. The LLM reads both perfectly; the table uses 60–80% fewer tokens.

Cache Aligner stabilizes prompt prefixes so provider KV caches actually hit. Anthropic and OpenAI offer prefix caching (massive cost reduction), but a single changed character busts the cache. Cache Aligner moves dynamic content (dates, session IDs, request hashes) to the end of system messages so the stable prefix stays stable.

---

Integrations

Your setup	How to use
Any Python app	compress(messages)
Anthropic / OpenAI SDK	CopiumClient(original_client=...)
Vercel AI SDK	Copium middleware
LiteLLM	Callback integration
LangChain	CopiumChatModel(your_llm)
Agno	CopiumAgnoModel(your_model)
MCP clients	pip install "copium-ai[mcp]"
Any HTTP client	copium run (proxy mode)
Claude Code	copium wrap claude
Codex	copium wrap codex
Cursor	Set API base URL in settings
OpenCode	export OPENAI_BASE_URL=http://localhost:8082/v1
Aider	copium wrap aider
GitHub Copilot	copium wrap copilot
Mistral Vibe	copium wrap vibe
Cline (VS Code)	copium wrap cline
Continue (VS Code/JetBrains)	copium wrap continue
Antigravity	⚠️ Not supported (no proxy settings)
AWS Bedrock	http://localhost:8082/bedrock
Google Vertex AI	http://localhost:8082/vertex
Ollama	copium run --backend ollama

---

Documentation

Start here	Go deeper
Quickstart	Architecture
Proxy	How compression works
MCP tools	Benchmarks
Configuration	Limitations
Migration guide	Presets

---

Contributing

git clone https://github.com/iKislay/copium.git && cd copium
uv sync && uv run pytest

See CONTRIBUTING.md.

---

License

Apache 2.0 — see LICENSE.

---

Acknowledgments

• Pichay (arXiv:2603.09023) — Virtual memory paging for LLM context
• The r/LocalLLaMA community — For identifying and stress-testing the precision cliff problem