scube-labs 0.40.0

Quickstart · Install · Proof · Agents · Docs · Experiments · llms.txt

_{AI agents / LLMs: start with llms.txt; measured results and decision history live in experiments/.}

Scube Labs compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens. Compression runs on your machine; no prompt or file content is sent anywhere to be compressed.

About this project. Scube Labs is derived from an Apache-2.0 licensed upstream project (see NOTICE): package scube-labs, import scube_labs, CLI scube-labs, environment variables SCUBE_*. On top of the compression pipeline it adds the cache governor below, optional cache-aware savings accounting (--aggressive-cost-calc), and an opt-in telemetry beacon. Every technique we tried — kept or dropped — is documented with data in experiments/.

Cache governor

Prompt-cache cost controls for Anthropic traffic, each measured against Anthropic-reported usage (deterministic replays of real Claude Code sessions, live A/B runs and simulations over real transcripts). Flags or env vars override every default.

Tool-search deferral (on by default) also keeps the cache intact when MCP tools connect mid-session: −66.9% input cost over a replayed Claude Code session start, with no tool-use failures in quality checks. Proxy overhead is ~12 ms p50 per 150 KiB request.

scube-labs proxy                                  # cache mode: compaction reuse + diagnostics
scube-labs proxy --no-cache-diagnostics           # turn diagnostics off
SCUBE_CACHE_KEEPALIVE=1 scube-labs proxy          # opt in to keep-alive
scube-labs proxy --mode token --compaction-tool-reuse   # opt in from token mode

_{10,144 → 1,260 tokens. The same FATAL found.}

What it does

• Library — compress(messages) in Python or TypeScript, inline in any app.
• Proxy — scube-labs proxy --port 8787, zero code changes, any language.
• Agent wrap — scube-labs wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|openclaw|vibe|omp|zcode in one command; undo with scube-labs unwrap <tool>.
• MCP server — scube_labs_compress, scube_labs_retrieve, scube_labs_stats for any MCP client.
• Cross-agent memory — one shared store across Claude, Codex, Gemini and Grok, with automatic dedup.
• scube-labs learn — mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored), CLAUDE.md, AGENTS.md, GEMINI.md or GROK.md.
• Output token reduction — trims what the model writes back, not only what you send. See below.
• Reversible (CCR) — originals are cached locally and retrieved on demand.

How it works

 Your agent / app
   (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
        │   prompts · tool outputs · logs · RAG results · files
        ▼
    ┌────────────────────────────────────────────────────┐
    │  Scube Labs (runs locally — your data stays here)  │
    │  ────────────────────────────────────────────────  │
    │  CacheAligner  →  ContentRouter  →  CCR            │
    │                    ├─ SmartCrusher   (JSON)        │
    │                    ├─ CodeCompressor (AST)         │
    │                    └─ Kompress-v2-base (text, HF)  │
    │                                                    │
    │  Cross-agent memory  ·  scube-labs learn  ·  MCP   │
    └────────────────────────────────────────────────────┘
        │   compressed prompt  +  retrieval tool
        ▼
 LLM provider  (Anthropic · OpenAI · Bedrock · …)

• ContentRouter detects the content type and selects a compressor for it.
• SmartCrusher / CodeCompressor / Kompress-v2-base handle JSON, source code and prose respectively.
• CacheAligner flags volatile content that would bust a provider KV-cache prefix. It never rewrites prompts.
• CCR stores originals locally so the model can call scube_labs_retrieve when it needs the full text.

→ Architecture · CCR · Kompress-v2-base model card

Get started (60 seconds)

# 1 — Install
uv tool install --python 3.13 "scube-labs[all]"  # CLI in a self-contained env
pip install "scube-labs[all]"                    # Python — ships the `scube-labs` CLI
npm install scube-labs                           # TypeScript SDK only — no CLI

# 2 — Pick a mode
scube-labs deploy                         # turnkey local deployment + agent config
scube-labs wrap claude                    # wrap a coding agent
scube-labs proxy --port 8787              # drop-in proxy, zero code changes
# or: from scube_labs import compress     # inline library

# 3 — Check it and watch the savings
scube-labs doctor                         # health check — confirms routing works
scube-labs perf
scube-labs dashboard                      # live savings (proxy must be running)

Inline, in Python:

from scube_labs import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

Launch a wrapped agent session each time, so the setup runs. scube-labs wrap starts a local proxy, installs Serena for semantic code navigation, and launches the agent configured to route through Scube Labs. Serena is registered at user scope (for Claude Code, in ~/.claude.json), so it stays available in your other projects until you run scube-labs unwrap. Skip it with --code-memory none.

The scube-labs CLI ships only in the PyPI package. The npm scube-labs package is the TypeScript SDK — a library you import (import { compress } from 'scube-labs') — and provides no scube-labs command.

Proof

Four scenarios built from real MCP server output formats, measured with the provider tokenizer and the shipped compress(). Seeded and offline, so you get the same numbers we did:

uv run python benchmarks/index_proof_table.py --seed 20260902

Savings scale with how repetitive the payload is. Repeated JSON arrays and log lines clear 90% in benchmarks/bench_latency.py; prose and already-dense output compress very little. Run scube-labs savings against your own traffic for the number that applies to you.

Compression costs well under a millisecond — 0.21 ms p50 on a 10K-token JSON search result, 1.4 ms at 100K tokens — so it does not show up in agent latency.

Accuracy. python -m scube_labs.evals suite --tier 1:

At N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA shows no detectable difference rather than an improvement. Methodology →

Output token reduction

Everything above shrinks the prompt you send. You also pay for every token the model writes back, and on Opus-class models output costs 5× input. Much of that output is ceremony: "Great, let me…" preambles, code re-printed straight back at you, and deep reasoning spent on routine steps like reading a file.

Scube Labs trims it from the proxy, with no change to your code:

• Verbosity steering appends a short "be terse, don't restate context" note to the end of the system prompt, so your prompt cache still hits.
• Effort routing dials thinking effort down when a turn is only the model resuming after a tool result — a file read, a passing test. New questions and errors keep full effort.

Both apply to Anthropic /v1/messages and to OpenAI-compatible /v1/chat/completions and /v1/responses. Effort routing uses reasoning_effort on OpenAI and thinking.budget_tokens / output_config.effort on Anthropic, with the same clamp-only invariant and the same output_shaper:* labels on both paths.

export SCUBE_OUTPUT_SHAPER=1     # off by default
scube-labs proxy --port 8787

Already running a proxy? These switches are read live on every request, so a proxy that scube-labs wrap reused rather than started would not see a value you export afterwards — its environment was snapshotted at launch. scube-labs wrap hot-syncs your current settings to the running proxy over a loopback POST /admin/runtime-env, so they take effect with no restart and no dropped requests. On a shared proxy these overrides are global; the last explicit setting wins.

Terseness you didn't have to configure. People rarely state how terse they want answers — they show it, by interrupting long replies or moving on before they could have read them. scube-labs learn --verbosity reads past sessions and picks the level:

scube-labs learn --verbosity            # dry run — preview what it found
scube-labs learn --verbosity --apply    # save it; the proxy picks it up

Measuring it. Output savings are counterfactual — we never see what the model would have written — so Scube Labs reports an estimate with a confidence range and labels it as one:

scube-labs output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]

For a measured number instead, hold out 10% of conversations as an unshaped control: export SCUBE_OUTPUT_HOLDOUT=0.1. The dashboard's Output Tokens Saved card then reads measured rather than estimated, with the band.

→ Output token reduction

Agent compatibility

Any OpenAI-compatible client works through scube-labs proxy. MCP-native clients: scube-labs mcp install. Undo durable wrapping with scube-labs unwrap <tool> (claude, copilot, codex, grok, kimi, omp, opencode, openclaw, zcode). Registry authors should use the canonical server.json rather than reconstructing the scube-labs mcp serve contract from prose.

scube-labs copilot-auth login
scube-labs wrap copilot --subscription -- --model gpt-4o

export GITHUB_COPILOT_ENTERPRISE_DOMAIN=ghe.example.com
export GITHUB_COPILOT_ENTERPRISE_URL=https://ghe.example.com

scube-labs copilot-auth login
scube-labs wrap vscode

pip install "scube-labs[proxy]"
scube-labs wrap vscode-claude

When to use · when to skip

Good fit if you run coding agents daily and want savings without touching your code, work across several agents and want one shared memory, or need compression that is reversible — originals stay retrievable through CCR for the configured TTL.

Skip it if you only use one provider's native compaction and don't need cross-agent memory, or work in a sandbox where local processes can't run.

Scube Labs pays off on long agent sessions with heavy tool output. Short conversational exchanges, prose, and already-dense payloads see little or no reduction, and blocks under min_input_words come back byte-identical. Limitations has the full list.

Install

uv tool install --python 3.13 "scube-labs[all]"  # CLI, isolated app env
pip install "scube-labs[all]"                    # Python, everything — includes the CLI
npm install scube-labs                           # TypeScript SDK (library only)
docker pull ghcr.io/rajkotraja/scube-labs:latest

Granular extras: [proxy], [mcp], [ml] (Kompress-v2-base), [code], [memory], [vector] (optional HNSW backend — needs a C++ toolchain, not in [all]), [relevance], [image], [agno], [langchain], [evals], [pytorch-mps] (Apple-GPU memory-embedder offload — set SCUBE_EMBEDDER_RUNTIME=pytorch_mps). Requires Python 3.10+.

[all] covers the core stack but not the framework adapters. Install those separately: pip install "scube-labs[langchain]", and likewise [agno], [strands], [anyllm], [bedrock].

Pick Python 3.13 if you want the dollar figure. The dashboard's Proxy $ Saved tile prices compression with LiteLLM, which cannot be installed on Python 3.14+. Token savings still track on 3.14, but the dollar figure stays $0.00. To switch: pipx reinstall scube-labs --python python3.13, then restart the proxy.

→ Installation guide — Docker tags, persistent service, PowerShell, devcontainers.

brew install python@3.13  # if 3.13 is not already available
uv tool install --python 3.13 "scube-labs[all]"
uv tool update-shell      # if ~/.local/bin is not on PATH
scube-labs --version

[mcp_servers.scube-labs]
command = "/Users/you/.local/bin/scube-labs"
args = ["mcp", "serve"]

pipx install --python python3.13 "scube-labs[all]"

scube-labs update          # detects pip / pipx / uv tool and upgrades in place
scube-labs update --check  # report the latest release without upgrading
scube-labs update --pre    # include pre-releases

# macOS / Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable
# Windows
winget install Rustlang.Rustup && rustup default stable

brew install onnxruntime
ORT_STRATEGY=system \
ORT_LIB_LOCATION="$(brew --prefix onnxruntime)/lib" \
ORT_PREFER_DYNAMIC_LINK=1 \
  pip install "scube-labs[all]"

# ORT is dlopen'd at runtime too:
export ORT_DYLIB_PATH="$(brew --prefix onnxruntime)/lib/libonnxruntime.dylib"

[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
Basic Constraints of CA cert not marked critical

SCUBE_TLS_STRICT=0 scube-labs proxy --port 8787

scube-labs learn

scube-labs learn mines failed sessions and writes corrections to CLAUDE.local.md (default, gitignored; use --target CLAUDE.md for the shared team file), AGENTS.md or GEMINI.md. → Failure learning

Telemetry

An anonymous beacon is on by default. It reports how compression behaved: ratios, counters, provider and model IDs, OS and architecture. It never sends prompts, completions, code or file paths. It exists so we can see when a release regresses a compression ratio across real workloads rather than only our own test corpus.

Turn it off with SCUBE_BEACON=off, the DO_NOT_TRACK=1 convention, or --offline. The full field list is in the proxy docs.

Scube Labs for teams

Scube Labs OSS is built for individual developers: run scube-labs proxy or scube-labs wrap on your laptop and start cutting tokens in minutes, free and local-first.

Running it across an engineering org is a different job — a shared always-on deployment, centralised config and version rollout, org-wide savings dashboards, SSO and access control, air-gapped and VPC installs, and someone to call. We help companies with that, self-hosted with support or fully managed.

If your team is spending real money on LLM tokens — Claude Code, Codex, Cursor, or agents running in CI — open an issue with your stack and rough monthly LLM spend.

Everything in this repo stays open source under Apache 2.0. The managed offering is for teams that would rather have it deployed, supported and scaled for them.

Documentation

Compared to

Scube Labs runs locally, covers every content type, works with every major framework, and is reversible.

Scube Labs is the proxy, and it compresses everything flowing through it whatever sits upstream. Our recommended companion is Serena for semantic code navigation, installed by default when you wrap an agent, plus Ponytail if you want leaner model output. Everything else is your call — attach a code-memory MCP, Graphify, Caveman, or any other MCP server, and Scube Labs compresses downstream of all of it.

Contributing

git clone https://github.com/rajkotraja/scube-labs && cd scube-labs
uv sync --extra dev && uv run pytest

Devcontainers in .devcontainer/ (default, plus memory-stack with Qdrant and Neo4j). See CONTRIBUTING.md.

Community

• Issues — questions, feedback, bug reports.
• Kompress-v2-base on HuggingFace — the model behind text compression.

License

Apache 2.0 — see LICENSE.