# Copium

> Context optimization layer for LLMs. 65-90% token savings with zero quality loss. Drop-in proxy for Claude, GPT, Gemini, and local LLMs (Ollama/VLLM/llama.cpp). Features KV cache-aware compression, session dedup, error cards, and Pichay-proven context paging.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ikislay-copium`
- **Verified:** Pending review
- **Seller:** [iKislay](https://agentstack.voostack.com/s/ikislay)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [iKislay](https://github.com/iKislay)
- **Source:** https://github.com/iKislay/copium

## Install

```sh
agentstack add mcp-ikislay-copium
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## MCP Compression Proxy (New)

Copium now includes an MCP proxy mode that acts as a transparent compression layer between your AI coding tool and upstream MCP servers.

Key capabilities:

- Tool description compression (70-90 percent reduction)
- Tool schema compression (~57 percent reduction)
- Tool response compression (60-95 percent reduction)
- Session deduplication for repeated tool definitions
- Progressive tool disclosure with on-demand schema expansion

Quick start:

```bash
copium mcp proxy install
copium mcp proxy serve
```

Helpful commands:

- `copium mcp proxy detect`
- `copium mcp proxy status`
- `copium mcp proxy uninstall`

See `docs/mcp-proxy.md` for setup and configuration details.

# Cross-Agent Context Sharing (New)

Copium is now the **context layer for multi-agent systems**. Agents don't share context
across sessions, tools, or each other — until now. SharedContext compresses what moves
between agents, persists it across sessions, and makes it searchable.

Key capabilities:

- **Persistent SharedContext**: SQLite-backed storage that survives proxy restarts.
- **Agent Provenance**: Track which agent created/modified each context entry.
- **Conflict Resolution**: Configurable strategies (last-write-wins, confidence, priority, merge).
- **Semantic Search**: Vector-based search over all shared context entries.
- **Audit Trail**: Full operation log for enterprise compliance.
- **Framework Integrations**: CrewAI, LangGraph, OpenAI Agents SDK, AutoGen, Agno, Strands.
- **Zero-Code Proxy Mode**: Any agent routing through the proxy shares context automatically.

```python
from copium import SharedContext

ctx = SharedContext(persistent=True)

# Agent A stores output (compressed + persisted)
ctx.put("research", big_output, agent="researcher")

# Agent B gets compressed version (~80% smaller)
summary = ctx.get("research")

# Semantic search across all shared context
results = ctx.search("database migration findings", top_k=5)
```

See:

- `guides/shared-context.md`
- `copium/shared_context/` (PersistentStore, VectorIndex, ConflictResolver, AuditLog)
- `copium/integrations/` (crewai, openai_agents, autogen, langchain, agno, strands)

# Pre-Compaction Data Loss Prevention (New)

Copium now prevents the silent data loss caused by auto-compaction in agentic tools.

When Claude Code, Cursor, or Codex fires auto-compaction, critical context is destroyed:
reasoning chains, architectural decisions, file relationships, and user intent. Copium's
new compaction hooks preserve this state and make recovery automatic.

Key capabilities:

- **Input-Priority Compression**: User messages (high entropy) preserved; tool outputs compressed.
- **Entropy-Based Scoring**: Information density scoring for intelligent compression scheduling.
- **Incremental Checkpointing**: Gradual state saves every N tool calls (no cliff).
- **Claude Code Hook Integration**: Native PreCompact/PostCompact hook bridge.
- **CCR Safety Net**: All compression remains reversible via `copium_retrieve`.

See:

- `guides/compaction-prevention.md`
- `copium/hooks/` (InputPriorityHooks, IncrementalCheckpointHooks, claude_code)

# Agent Context Management (New)

Copium now includes a Smart Zone based agent-aware context lifecycle in `copium/agent_context/`.

Key capabilities:

- Smart Zone budget enforcement to keep context in high-quality ranges.
- Phase detection: orientation, exploration, implementation, verification.
- Value-aware and content-type-aware compression scheduling.
- Orientation cache to reduce first-turn tool-call overhead.
- Context health monitoring and recommendations for long sessions.

See:

- `guides/agent-context-management.md`
- `docs/agent-context-management.md`

# Position-Aware Compression (Lost in the Middle)

Initial implementation work has started for position-aware compression to reduce
"lost in the middle" degradation in long contexts.

Implemented in this iteration:
- Rust `position_aware` transform module with zones, scoring, and configuration.
- Python `position_aware` module parity helpers.
- SmartCrusher planner helper for position-aware keep-order optimization.
- Unit tests covering zone classification, weighting, and bookend reordering.

This is an opt-in foundation. Default behavior remains unchanged when
position weighting is disabled.

# Quality Preservation (New)

Copium now includes a comprehensive quality preservation framework in `copium/quality/`.

The community's #1 concern with context compression: "Does it break my agent's answers?"
Our answer: verifiable, benchmarked, auditable proof that quality is preserved.

Key capabilities:

- **Quality Gate**: Post-compression validation with 4 checks (token reduction, critical markers,
  structure, density). Auto-reverts to original if any check fails.
- **Quality Metrics**: ROUGE-L (≥0.85), IPS (≥0.95), CWQ (≥0.85) measurement.
- **A/B Testing**: Statistical framework with Welch's t-test, Cohen's d, power analysis.
- **Quality Dashboard**: Real-time session monitoring via `copium quality status`.
- **Benchmarks**: Synthetic and real-world benchmark suites with CI integration.

```python
from copium.quality import QualityGate, GateConfig, ContentType

gate = QualityGate(GateConfig(min_token_savings_pct=10.0))
result = gate.validate(original, compressed, ContentType.JSON)
# Auto-reverts to original if quality drops below threshold
```

The bottom line: **70-90% compression,  65–94% fewer tokens. Zero quality loss. Drop-in proxy for Claude, GPT, Gemini, Bedrock, and local LLMs.

[](https://pypi.org/project/copium-ai/)
[](https://pypi.org/project/copium-ai/)
[](LICENSE)
[](https://github.com/iKislay/copium/actions)
[](https://copium-docs.vercel.app/docs)

  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

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

# If you use uv
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`.

### RTK (Rust Token Killer) — Included automatically

RTK is bundled with Copium and auto-installed on first `copium wrap` run. No separate install needed.

For RTK-only mode (CLI stdout compression without the proxy):
```bash
copium wrap claude --rtk-only
```

This gives you RTK's exact UX — `rtk git status`, `rtk grep`, etc. — then upgrade to full proxy compression anytime by dropping `--rtk-only`.

To install RTK manually (standalone):
```bash
# Via Homebrew (macOS/Linux)
brew install rtk

# Via curl (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/main/install.sh | bash

# Via cargo
cargo install --git https://github.com/rtk-ai/rtk
```

Then activate for your agent:
```bash
# Claude Code
rtk init --claude-code

# Verify savings
rtk gain
```

### Start the proxy

**Recommended — background daemon (survives shell exit):**

```bash
copium start               # starts on http://localhost:8787, detaches from terminal
copium status              # check health, port, today's savings
copium status --prompt     # minimal output for shell prompts (⚡ 38%)
copium stop                # stop gracefully (prints session summary with duration + all-time totals)
copium restart             # restart to pick up config changes
copium ping                # fast health check — exit 0 running, exit 1 stopped
```

**One-shot foreground mode (blocks the terminal):**

```bash
copium proxy               # or: copium run
```

Point your agent at the proxy:

```bash
# 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

```bash
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:

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

### Cursor

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

Or via environment:

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

### OpenCode

OpenCode uses the OpenAI-compatible API format:

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

Or set it permanently in your OpenCode config:

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

### Aider

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

### Codex (OpenAI)

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

### GitHub Copilot

```bash
copium wrap copilot
```

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

### Mistral / Vibe

```bash
copium wrap vibe
```

### VS Code Extensions

#### Cline

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

#### Continue

```bash
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:

```python
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

```bash
pip install "copium-ai[mcp]"
```

Then add to your MCP client config:

```json
{
  "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)   |
    |  -------------------------------------------------  |
    |  ToolPrefilter  → ContentRouter → SmartCrusher    |
    |  Session Dedup  | SelfCompressor | Kompress       |
    |  Cache Aligner  | Error Compressor | 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 |
|---|---|---|
| **ToolPrefilter** | Oversized tool outputs (500-match grep → 50 lines) | 60–95% |
| **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% |
| **SelfCompressor** | LLM self-compression markers (_context_updates) | 40–80% |
| **Error Compressor** | Verbose stack traces → structured error cards | 50–80% |
| **ANSI Remover** | Terminal colors, spinners, progress bars | 10–30% |
| **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.

---

## Progressive Tool Disclosure

Register 30+ MCP tools without burning 60K tokens per request. Copium loads only the tools the LLM needs, when it needs them.

```python
from copium.mcp_proxy.progressive_disclosure import (
    ProgressiveDisclosureConfig,
    ProgressiveDisclosureInterceptor,
)

# Configure progressive disclosure
config = ProgressiveDisclosureConfig(
    enabled=True,
    eager_load_max=10,       # Max tools loaded eagerly
    search_backend="bm25",   # Fast, dependency-free search
    min_tools_for_disclosure=8,  # Threshold to activate
)

# Use in your proxy pipeline
interceptor = ProgressiveDisclosureInterceptor(config)
modified_request = interceptor.intercept_request(request_body)
# 61 tools → 10 eager + copium_find_tool + copium_call_tool
# Token savings: 70-98%
```

**How it works:**
1. Client sends request with all tools (unchanged workflow)
2. Copium classifies tools as eager (high-usage) or deferred
3. LLM receives eager tools + `copium_find_tool` + `copium_call_tool`
4. LLM discovers deferred tools on-demand via BM25 semantic search
5. Schemas are cached for instant repeated lookups

| Tool Count | Token Savings | Eager Tools |
|-----------|--------------|-------------|
| 10 tools | ~40% | 6-8 loaded |
| 30 tools | ~75% | 8-10 loaded |
| 60 tools | ~95% | 10 loaded |

---

## Session management

Copium is also a **universal session manager** for AI coding agents. Compress, search, and share session archives across Claude Code, Cursor, Aider, and OpenCode.

```bash
# Compact a Claude Code session (40-97% smaller)
copium session compact ~/.claude/projects/.../session.jsonl

# Search across all your sessions
copium session search "authentication bug" --agent claude_code

# Export from Claude Code, import into Cursor
copium session export claude-session.jsonl --format shared
copium session import shared.jsonl --agent cursor

# Batch compact all sessions
copium session compact-all ~/.claude

…

## Source & license

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

- **Author:** [iKislay](https://github.com/iKislay)
- **Source:** [iKislay/copium](https://github.com/iKislay/copium)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ikislay-copium
- Seller: https://agentstack.voostack.com/s/ikislay
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.