Spaces:
Build error
Build error
Commit History
-
chore: bump version to 0.5.1
628157f -
fix: capture Zone 1 + Zone 2 savings in token_headroom stats
In token_headroom mode, original_tokens was being overwritten with the pipeline's input view (post-Zone-1-swap), causing tokens_saved to only reflect Zone 2 compression. Zone 1 savings from cached content swaps were invisible in stats, cost tracking, and the session summary. Now keeps original_tokens as the real original (from Claude Code's uncompressed messages) so tokens_saved = Zone 1 + Zone 2.47a9422 -
chore: bump version to 0.5.0
8d902fd -
Merge feat/token-headroom-mode: dual-mode optimization + clean stats
Token headroom mode (HEADROOM_MODE=token_headroom) compresses older messages to extend session length, trading prefix cache cost savings for token reduction. Content-addressed CompressionCache avoids re-compression across turns. Works for both Anthropic and OpenAI. Also: claude-opus-4-6 model entry, clean session summary in /stats and MCP headroom_stats tool.0b7ecac -
feat: add clean session summary to /stats and MCP headroom_stats
The /stats endpoint now includes a "summary" section at the top with: - Avg/best compression % on requests that actually compressed - Breakdown of why uncompressed requests were skipped - Cost impact: without vs with Headroom, total saved - Actionable tip when token_headroom mode would help The MCP headroom_stats tool returns clean formatted text instead of dumping raw JSON when the proxy is reachable. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>c91220b -
fix: prevent stat inflation in compute_frozen_count, fix token estimate
- compute_frozen_count now checks _cache directly instead of calling get_compressed, which was inflating hit/miss stats on every turn - update_from_result uses len//4 for rough token estimate instead of raw character count Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>9b5e783 -
test: add integration tests for token_headroom mode
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>b59d6a5 -
feat: add compression_cache stats to /stats endpoint
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>f3043c1 -
feat: add token_headroom branch to OpenAI handler
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>6838f75 -
feat: add token_headroom branch to Anthropic handler
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>26e8b69 -
feat: configure pipeline based on HEADROOM_MODE at startup
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>6a5ec2d -
feat: add HEADROOM_MODE config to ProxyConfig
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>e46862d -
feat: export CompressionCache from cache package
eac7379 -
feat: add frozen count, apply_cached, update_from_result to CompressionCache
Add three methods and supporting helpers for token headroom mode: - compute_frozen_count: counts consecutive stable messages from start - apply_cached: swaps cached compressions into tool results (immutable) - update_from_result: learns new compressions from original/compressed pairs Supports both Anthropic and OpenAI tool result formats. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>60741b5 -
feat: add CompressionCache with LRU eviction for token headroom mode
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>29928b8 -
fix: add claude-opus-4-6 (1M context) to ANTHROPIC_CONTEXT_LIMITS
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>830f939 -
Add implementation plan for token headroom mode
11 tasks across 4 chunks: CompressionCache core, ProxyConfig/pipeline setup, handler integration (Anthropic + OpenAI), and integration/E2E tests. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>1f0bf05 -
Update token headroom mode spec with review fixes
Address spec review findings: fix protect_recent_fraction plumbing (set at startup, not per-call kwarg), clarify Zone 3 scope (excluded-tool messages only), fix frozen count to treat user/assistant as stable, increase cache to 10K entries, add observability section, define update_from_result contract, handle force_compress_threshold interaction, add mode-switch and latency edge cases. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>89b0310 -
Add design spec for token headroom mode
Introduces dual-mode optimization (cost_savings vs token_headroom) to address low compression rates in long Claude Code sessions caused by prefix freeze consuming all messages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>4cf523a
-
Add SharedContext for multi-agent, rewrite README, fix proxy cleanup
- SharedContext: compressed inter-agent context sharing via put()/get() over existing CCR compression pipeline. Zero new dependencies. - README rewrite: lead with "any agent" positioning, not just coding agents. Add headroom wrap, SharedContext, MCP tools to Quick Start. Reorder integration table: universal first, coding shortcuts last. Update compression pipeline references (LLMLingua → Kompress). - Fix proxy cleanup in headroom wrap: don't kill shared proxy if other clients are still using it (was orphaning terminals 2-N). - New docs: docs/shared-context.md61e7398 -
Updated README and mcp docs
33bbf31 -
Enhanced MCP server with compress/stats tools, fix proxy torch crash
- Fix proxy crash when torch not installed: make kompress_compressor.py imports lazy so `is_kompress_available()` works without [ml] extra - Rewrite MCP server from 1 tool (retrieve-only) to 3 tools: headroom_compress (on-demand compression, no proxy needed), headroom_retrieve (local store first, proxy fallback), headroom_stats (session stats + sub-agent aggregation + proxy cache) - Add shared stats file (~/.headroom/session_stats.jsonl) so sub-agent compression stats are visible from the main session - Add mcp to [proxy] extras so proxy users get MCP tools automatically - Remove dead TextCompressor from exports and pipeline (was never called) - Update mcp install messaging to clarify proxy vs MCP roles - Fix fcntl Windows compat, asyncio deprecation, httpx timeout race Bump version to 0.4.6.facf3b5
-
Fixing tests
f166566 -
Fix proxy crash when torch not installed (kompress lazy imports)
The proxy startup crashed with `ModuleNotFoundError: No module named 'torch'` when installed with just `[proxy]` extras because kompress_compressor.py had unconditional top-level torch imports. Moved torch/transformers imports to be lazy so the module is safely importable without the [ml] extra. Added tests for import safety. Bumped version to 0.4.580f8f0d
-
Bump version to 0.4.4
a7975c5 -
Add wrap commands for Codex/Cursor/Aider with rtk instructions, fix savings metrics
- headroom wrap codex: injects rtk instructions into AGENTS.md - headroom wrap cursor: injects into .cursorrules, prints config steps - headroom wrap aider: injects into CONVENTIONS.md, sets both env vars - All with --no-rtk flag to skip rtk setup Unified savings metrics across three layers: - cli_filtering: tokens avoided by rtk before reaching context - compression: tokens removed by proxy (SmartCrusher, etc.) - prefix_cache: provider cache discount with honest attribution Fix flaky test_process_stats_collected when psutil not installed.aacfc8b
-
Bump version to 0.4.3
f13981b -
Commit message:
Fix OpenAI streaming with backends and /v1 double-path bug Add stream_openai_message() to LiteLLM and any-llm backends so /v1/chat/completions with stream:true returns SSE events instead of a JSON blob. Clients (Kilo Code, Cursor, etc.) were hanging because the proxy ignored the stream flag when routing through a backend. Also strip trailing /v1 from OPENAI_TARGET_API_URL to prevent double-path URLs like /v1/v1/models.d90c6b8 -
Slim core dependencies: 2.5GB → 195MB install size
Move heavy deps to optional extras: sentence-transformers, torch, numpy, pillow, datasets, accelerate out of core. Remove unused deps entirely (semantic-router, protobuf, sentencepiece). New extras: [ml] for Kompress, [image] for image compression, [langchain] for LangChain integration. Guard memory/image imports so core install works without numpy/torch. Core (tiktoken, pydantic, litellm, click, rich) gives full compression: SmartCrusher, ContentRouter, CCR, TOIN, CLI.050d435 -
fix(wrap): route through proxy, prevent pipe deadlock, bump to 0.4.2
- Fix ANTHROPIC_API_URL → ANTHROPIC_BASE_URL (SDK uses BASE_URL) - Write proxy logs to ~/.headroom/logs/proxy.log instead of PIPE (macOS 64KB pipe buffer fills up, blocking the proxy process) - Add --auto-patch to rtk init to avoid interactive prompt timeout - Bump version to 0.4.2 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>a96b1bb -
Fixing headroom wrap claude
aa971c5 -
Fix mypy no-any-return errors in kompress_compressor.py
832f85d -
Format prefix_cache_benchmark.py for ruff 0.15 compatibility
a3c6964 -
Fix pricing lookup for retired Claude models
LiteLLM removed claude-3-5-sonnet-20241022 from its cost database. Add alias fallback map so retired model names resolve to current equivalents for pricing lookups.89d649c -
Fix proxy backend bugs: env vars, tool forwarding, and provider support
- CLI now reads OPENAI_TARGET_API_URL, GEMINI_TARGET_API_URL, and HEADROOM_ANYLLM_PROVIDER environment variables - Add --openai-api-url and --gemini-api-url CLI flags - Remove --backend choices restriction so litellm-* backends work - Forward tools/tool_choice through LiteLLM and any-llm backends - Parse tool call arguments from JSON string to dict (Anthropic format) - Forward top_p, stop_sequences, tools in streaming paths - Update Vertex AI model map with Claude 3 through 4.6 (from official docs) - Bump version to 0.4.15a87378
-
Introducing headroom wrap
- headroom wrap claude is the simplest way to start up claude - It will also install rtk-ai locally - rtk-ai is a cli wrapper that can save ~90% tokens for CLI calls made by Claude Code641cfec
-
Kompress: use argmax for token selection, remove hardcoded 0.5 threshold
The model is a binary classifier — let it decide. When no target_ratio is set (default proxy path), use argmax on token head logits directly instead of score > 0.5 cutoff. Span head boosts borderline tokens (0.3-0.5 probability) in important spans. Result: compression adapts per content — 9% kept for verbose filler, 100% kept for dense commands/code. Previously uniform 29% everywhere.58a7549 -
Add Kompress: ModernBERT token compressor replacing LLMLingua-2
Adds kompress_compressor.py — a self-contained ModernBERT-based token compressor that auto-downloads from chopratejas/kompress-base on HuggingFace. Trained on 330K structured tool outputs (JSON, diffs, logs, code, SQL, agentic traces), achieving 82% entity preservation vs LLMLingua-2's 36%. Changes: - New: kompress_compressor.py — dual-head ModernBERT (token + span CNN) with HuggingFace auto-download, no extra pip install needed - ContentRouter: Kompress is primary ML compressor, LLMLingua-2 is fallback - fallback_strategy changed from PASSTHROUGH to KOMPRESS — unknown/mixed content now gets compressed instead of ignored - No hardcoded compression ratios — model decides per-token importance, optional target_ratio only when user explicitly sets it via API - Version bump: 0.3.8 → 0.4.0001364f
-
Updating the README to reflect the right positioning for Headroom
- Added Discord channel as well - README is now simpler66ac1c8
-
feat: provider-aware prefix cache tracking and combined savings dashboard
Add per-provider prefix cache metrics (Anthropic/OpenAI/Google/Bedrock) with correct economics (read discounts, write premiums, bust detection). Model-aware bust detection excludes cold starts when switching models. Dashboard hero metric shows combined savings (compression + cache) with per-provider breakdown table, efficiency bar, and hit rate tracking. - Add _CACHE_ECONOMICS dict and _build_prefix_cache_stats() helper - Track cache_by_provider with per-model cold start awareness - Add _merge_cost_stats() to combine compression + cache savings - Dashboard: "Prefix Cache Impact" section with provider breakdown - Dashboard: hero "Total Savings" shows compress + cache breakdown - Fix ruff (unused var, quoted annotations) and mypy type errors - Refactor code_compressor to data-driven language config Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>22987ea
-
fix: dashboard metrics, TTFB tracking, eager LLMLingua loading, and multi-provider consistency
Dashboard was showing wildly incorrect metrics (99.5% savings, 3ms overhead) due to using Anthropic API's non-cached input_tokens instead of optimized_tokens, and dividing overhead by total request count instead of optimized-only count. Key fixes: - Use optimized_tokens (what we sent) for dashboard aggregation, not API's input_tokens which excludes cached portion - Track overhead_count separately from latency_count for correct averages - Add TTFB (time to first byte) measurement, replace full stream latency in UI - Eager-load LLMLingua model at proxy startup (eliminates 5.9s first-request delay) - Simplify CostTracker to token-based accounting with counterfactual cost display - Add two-tier compression cache to ContentRouter (skip set + result cache) - Fix compression pinning to detect both CCR and ReadLifecycle markers - Clamp tokens_saved to max(0, ...) across all provider paths - Add per-transform timing instrumentation to pipeline - Guard against over-aggressive code compression…0e85550 -
docs: add headroom learn demo GIF to README
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>7e6087f
-
Fixing the build AND the perf logs
6a51c39 -
style: ruff format parser.py, content_router.py, smart_crusher.py
Pre-existing formatting issues caught by CI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>257873b -
fix(learn): pass explicit model in tests to avoid API key requirement
SessionAnalyzer() without a model calls _detect_default_model() which raises when no API keys are set (e.g., in CI). Pass model="test-model" in the three tests that mock _call_llm.a6eefcc -
feat: add `headroom perf` CLI and rewrite `headroom learn` to use LLM analysis
Proxy performance logging (`headroom perf`): - Add always-on RotatingFileHandler to ~/.headroom/logs/proxy.log (10MB x 5 backups) - Replace scattered log lines with structured PERF lines containing model, msgs, tok_before/after/saved, cache_read/write/hit_pct, opt_ms, and transforms - Emit PERF lines from all three response paths (streaming Anthropic, non-streaming Anthropic, Bedrock streaming) - Add `headroom perf` CLI that parses proxy logs and reports token savings, cache hit rates, prefix stability, transform effectiveness, routing breakdown, TOIN status, and actionable recommendations - Support --hours and --raw flags for time filtering and raw record output Learn module rewrite (LLM-based analysis): - Replace all regex/heuristic analyzers with a single LLM call via LiteLLM - New SessionAnalyzer builds compact digests and sends to any of 100+ models - Auto-detect best model from API keys (Anthropic → OpenAI → Gemini) - Add --model flag for explicit model selection - Enric…62d80bc -
fix: harden edge cases, expand tool exclusions, and fix mypy errors
- Fix division-by-zero in OpenAI cache, BM25 scorer, BLEU metrics, and smart_crusher - Add null safety for SQLite memory store JSON fields - Add thread safety lock for CCR retrieval counter - Add timeout/error handling for CCR stream collection - Safer error logging and JSON serialization fallback in proxy server - Return explicit zero stats on compression failure instead of None defaults - Guard against missing "messages" key in ASGI and LiteLLM integrations - Add aclose() for proper httpx client cleanup in ASGI middleware - Expand DEFAULT_EXCLUDE_TOOLS to include Grep, Write, Edit - Revert protect_recent_reads_fraction to 0.0 (protect all excluded-tool outputs) - Fix whitespace waste detection to use tokenizer for both original and normalized - Fix top-waste-requests sorting by tokens_saved instead of tokens_before - Fix TOCTOU race in semantic cache _touch() method - Fix mypy errors: type annotations for ASGI receive/send and proxy error loggingc8388c1
-
Merge pull request #40 from smartwatermelon/claude/fix-mcp-startup-and-install-20260306
fix(mcp): use claude mcp add for install/uninstall, fix startup importa4bb833 -
fix(mcp): fix uninstall symmetry, move subprocess import, add cli-path tests
Claude Code Bot +1: Claude Sonnet 4.6Address code review feedback on the initial MCP fix: - mcp_uninstall: now also calls `claude mcp remove -s user` when the claude CLI is available, mirroring mcp_install. Removes from mcp.json fallback config as well if present. This fixes the broken uninstall->reinstall roundtrip on machines using Claude Code CLI >=2.x. - cli/mcp.py: move `import subprocess` to module level (was deferred inside mcp_install function body, inconsistent with other stdlib imports and harder to mock). - tests: add TestMCPInstallWithClaudeCLI and TestMCPUninstallWithClaudeCLI covering the previously-untested `claude mcp add` code path, including force-overwrite ordering, -e flag for env vars, and fallback on failure. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>514dae4 -
fix(mcp): use claude mcp add for install and fix startup import
Claude Code Bot +1: Claude Sonnet 4.6Two fixes to get the headroom MCP server working with Claude Code CLI: 1. mcp_server.py: define CCR_TOOL_NAME inline instead of importing from tool_injection, which triggered headroom/__init__.py -> LiteLLM -> HTTP requests to GitHub, adding 4-5 seconds to startup time. 2. cli/mcp.py: prefer `claude mcp add -s user` when the claude CLI is available (Claude Code CLI ≥2.x stores servers in ~/.claude/.claude.json, not ~/.claude/mcp.json). Falls back to writing mcp.json for older versions and the claude.ai desktop app. 3. tests/test_cli/test_mcp.py: update mock_claude_config_path fixture to also stub out the claude CLI so install tests exercise the mcp.json fallback path, matching the fixture's intent. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>4d381a9