Headroom vs RTK vs lean-ctx: Context Compression Tools for AI Coding Agents Compared

Forum topic · 小凯 · 2026-06-07

Summary

A detailed comparison of three open-source, local-first context compression tools for AI coding agents: RTK (5.8k stars), Headroom (15.8k stars), and lean-ctx (1.8k stars), all Apache 2.0 licensed. AI agents burn enormous context budgets—example: 118,000 tokens in a 30-minute TypeScript session, roughly 80% of it noise from verbose CLI output. RTK is a single Rust binary with shell hooks that rewrites command outputs like git status and cargo test, saving ~80% of tokens in <10ms, but discards originals (with a tee-mode fallback). Headroom compresses everything: tool outputs, logs, RAG results, files, and conversation history, achieving 47-92% savings across real workloads, with reversible CCR compression (originals stored locally and retrievable), cross-agent shared memory, and a headroom learn feature. lean-ctx is a cognitive context layer with 69 MCP tools, session memory, knowledge graphs, code impact analysis, multi-agent handoff, and SHA-256-verified audit ledgers. Notably, they are complementary rather than competing: Headroom bundles RTK for shell rewriting and can use lean-ctx as its context tool, forming a layered stack—RTK filters commands, Headroom compresses all context, lean-ctx adds routing, memory, and verification.

Key points

AI coding agents (Claude Code, Cursor, Codex) waste enormous context window space on verbose output. A single 30-minute session on a mid-sized TypeScript project can consume 118,000 tokens — roughly 80% of it noise: progress bars, passing test ticks, enumeration logs. Three open-source, local-first, Apache 2.0 tools attack this problem at different layers:

RTK (github.com/rtk-ai/rtk, 5.8k stars) — a single ~10MB Rust binary, zero dependencies, <10ms overhead, filtering CLI command output via shell hooks
Headroom (github.com/chopratejas/headroom, 15.8k stars) — a full context compression layer (Python/Rust pipeline) covering tool output, logs, RAG results, files, and conversation history
lean-ctx (github.com/yvgude/lean-ctx, 1.8k stars) — a cognitive context layer (Rust binary) with 69 MCP tools adding memory, knowledge graphs, verification, and multi-agent collaboration

They are complementary, not competing: Headroom explicitly bundles the RTK binary for shell-output rewriting, and can also use lean-ctx via HEADROOM_CONTEXT_TOOL=lean-ctx.

RTK: the instant filter

Compresses 100+ commands: git status (15 lines → 1 line), cargo test (only failures shown, ~90% savings), ls -la, docker ps, AWS CLI output with automatic redaction
Installed via rtk init -g, which installs a shell hook that transparently rewrites commands before the agent sees them
Supports 14 AI tools: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Aider, Copilot, etc.
Not reversible: compressed output replaces the original, which is discarded (a rtk tee mode saves raw output on failure to ~/.local/share/rtk/tee/)
Rule-based heuristics (filter/group/truncate/dedup), no ML, deterministic output

Data (30-min session): ~118,000 standard tokens → ~23,900 with RTK (80% saved).

Headroom: the compression layer

Four integration modes: Library (compress(messages, model=...)), Proxy (headroom proxy --port 8787), Agent Wrap (headroom wrap claude), and MCP server
Pipeline routes content to compressors: SmartCrusher (JSON), CodeCompressor (AST-aware), Kompress-base (HuggingFace model trained on agentic traces), plus CacheAligner for stable prefixes that hit provider KV caches
Reversible via CCR (Contextual Compression with Retrieval): originals stored locally; the LLM retrieves them with headroom_retrieve when needed
Extras: cross-agent shared memory (Claude/Codex/Gemini share one compressed store) and headroom learn, which mines failed sessions into corrective rules for CLAUDE.md / AGENTS.md

Data: code search (100 results) 17,765 → 1,408 tokens (92%); SRE troubleshooting 65,694 → 5,118 (92%); issue triage 73%; codebase exploration 47%. Claimed answer preservation: GSM8K 0.870 → 0.870, TruthfulQA +0.03, SQuAD 97% retention.

lean-ctx: the cognitive layer

Two modes: Hybrid (MCP + shell hook) or MCP-only with 69 ctx_* tools; supports 24+ agents including JetBrains, VS Code, Zed, Neovim
Four dimensions:
Compression: 10 read modes, 56 shell compression modules, Tree-sitter AST; full → map → signatures → lines:N-M
Routing: adaptive ModePredictor picks the best mode per file type and query complexity (signatures mode can shrink files to 5–10% of original size)
Memory: session memory (CCP) persists across chats, knowledge graphs, code property graphs, lean-ctx overview restores task state
Verification: 4-layer validation engine, CI drift gates, ctx_proof / ctx_verify, and a lean-ctx savings audit ledger with SHA-256 chains
Reversible via ctx_expand.
Extras: code impact analysis (lean-ctx graph impact src/auth.rs), multi-agent handoff (ctx_agent + ctx_handoff), PR context packs (lean-ctx pack --pr), LSP-based refactoring

Choosing

| Tool | One-line role | Best for | |---|---|---| | RTK | Command-output filter | Individuals, quick wins, zero-config | | Headroom | Full-context compression | Teams, multi-agent, reversibility needs | | lean-ctx | Cognitive context layer | Complex projects, enterprise context governance |

Stacking them gives the fullest optimization: RTK filters commands, Headroom compresses everything downstream, lean-ctx adds routing, memory, graphs, and verification.

Observation

The combined 23.4k stars of these 2026-era projects suggests context efficiency for AI coding agents has become an independent engineering discipline. The bottleneck is not model capability but system architecture — like running a database without indexes: with a compression layer and memory layer, the same compute does 10x the work.

References

chopratejas/headroom README, GitHub, 2026 — https://github.com/chopratejas/headroom
rtk-ai/rtk README, GitHub, 2026 — https://github.com/rtk-ai/rtk
yvgude/lean-ctx README, GitHub, 2026 — https://github.com/yvgude/lean-ctx