LeanCTX: Context Engineering Machine for AI Agents - Not Just Token Compression

Introduction: The Day I Realized I Was Fueling a Jet with My Wave

It happened like this.

In Q1 this year, my team ran Claude Code on a Go monorepo with around 500 files. Service mesh, multi-module, dependencies were all intertwined. Each time Claude needed to understand a module - for example, the auth package - it would read the entire file. Then it would read an additional 3-4 related files. After 50 files, the context window was full.

The token bill at the end of the month was staggering. Each dev spent $50-60/month on Claude Code + Cursor. With a team of 4 devs, not to mention Gemini CLI and Codex running automatically in CI, the total damage was around $200-240/month for context.

It felt like fueling a Wave with AvGas 100LL - the engine couldn’t handle it, and the money was still being wasted.

Then one rainy Saturday, I was browsing Hacker News and saw a project called LeanCTX. Its tagline was: “Control what your AI can see.” A single Rust binary, promising to reduce tokens by 60-90%. I read the first paragraph: “It decides what they read, remembers what they learn, guards what they touch, and proves what they save.”

I thought: “Isn’t this just a regular compression tool?” I clicked on the repo.

2,747 commits. 225 releases. 39 contributors. Cursor AI + Yves Gugger - a Swiss dev. License Apache 2.0 (migrated from MIT).

The second tagline was even more impressive: “60–90% fewer tokens as the receipt.”

I tried installing it. 60 seconds.

curl -fsSL https://leanctx.com/install.sh | sh
lean-ctx onboard
lean-ctx doctor

The first command I tested:

lean-ctx read src/auth/ -m map

It read 50 files in the auth folder. Output: 533.2K tokens → 8.0K tokens. 98.1% compression.

I sat staring at the screen for 5 seconds, speechless.

It was then that I realized: I had been reading files like a novel, when in fact the AI only needed to know export signatures and type definitions.

First look: see the benefits right after installation

The installation process is extremely smooth. There are 5 ways to install:

# Universal - 1 command
curl -fsSL https://leanctx.com/install.sh | sh

# macOS/Linux
brew tap yvgude/lean-ctx && brew install lean-ctx

# Node.js dev
npm install -g lean-ctx-bin

# Rust dev
cargo install lean-ctx

# Pi agent
pi install npm:pi-lean-ctx

After installation, run lean-ctx onboard. This automatically detects all AI tools on the machine - Cursor, Claude Code, Codex CLI, Windsurf, Copilot, Gemini CLI, Hermes, OpenCode, Zed, Cline, Roo, JetBrains, VS Code, Neovim, Emacs, etc. - and configures the MCP server and shell hooks. Zero interaction.

lean-ctx doctor verifies whether everything is working.

Right from the first run of lean-ctx gain --live - a real-time token savings dashboard - I saw Claude Code reduce from 4,200 tokens per read to 920 tokens. 78% saving. In real-time, in the terminal.

Sorry, at that time I let out a pretty loud “Wow” sound. My wife thought I encountered a bug.

Vibe check after 10 minutes

Immediate pros:

• Binary Rust ~10MB, no dependencies other than libc
• Zero telemetry by default - 100% local
• Auto-detects 30+ agents - no need to manually configure any
• Self-healing diagnostics - doctor --fix automatically detects and fixes configuration errors

Initial annoyances:

• Need to restart the terminal session for shell hooks to take effect
• lean-ctx setup asks a few too many questions (wizard mode). Using onboard is faster.
• There are various integration modes (Auto/Hybrid/MCP) - newcomers may find it confusing. I chose Auto and it seems to be working fine.

Architecture deep dive: 5 subsystems in 1 binary

This is the part that I respect the most. LeanCTX is not just “a token compressor”. The codebase is 90.8% Rust, with the rest being JS/Python/Kotlin for SDKs and plugins.

The structure is divided into 5 clear subsystems, each with its own job:

1. Compression - the engine that makes it famous

There are 10 read modes, each using a different compression strategy:

Full read (baseline): Reads the entire file. Compression 0%. Anyone can do this.

Map mode (98.1% compression): This is the mode I use the most. Instead of reading all 50 files, it parses the AST using tree-sitter, extracts export declarations with line spans. The result:

┌─────────────────────┬────────────────────────┐
│ src/auth/service.go │ authenticate(),        │
│   (4200 tok → 920)  │ validateToken(),       │
│                     │ refreshSession()       │
├─────────────────────┼────────────────────────┤
│ src/auth/middleware │ AuthMiddleware struct,  │
│   (3800 tok → 640)  │ Authenticate(),        │
│                     │ handleError()          │
├─────────────────────┼────────────────────────┤
│ 48 more files...    │ ...                    │
└─────────────────────┴────────────────────────┘

Signatures mode (96.7% compression): Only keeps AST signatures - function signatures, type definitions, interface declarations. When the AI needs to understand “what this module does” without needing implementation details, this is the ultimate weapon.

Benchmark:

• Raw read: 533.2K tokens
• Map mode: 8.0K tokens, quality score 78%
• Signatures mode: 14.0K tokens, quality score 96%
• Cached re-read: ~13 tokens - 99.99% compression for subsequent reads

I don’t understand why no one did cached re-read before. The mechanism is simple: LeanCTX hashes the file content, caches the parsing result. When the AI asks again, it just returns the cache key. 13 tokens vs 4,200 tokens - a 323x ratio.

Diff mode (80-95% compression): Only shows changed lines from the last read. When the AI does code review, it only needs to know what changed, not read the entire file again.

Density mode (variable): Entropy budget like SDE - keeps high-entropy parts (code logic, control flow), discards boilerplate. Uses a compressor heuristic instead of ML, so it’s deterministic and prompt-cache-safe.

Additionally:

• lines:N-M - reads specific lines
• citations - summarizes + citation markers
• anchored - reads from a symbol anchor
• full - reads the entire file (when needed)

95+ shell patterns more. I also like this. When you run npm test through the CTX shell, it knows the output of the test runner (PASS/FAIL, coverage %) and only keeps that part. Git log → commit hash + message. Kubectl get pods → status + restart count. Docker build → layer caching status. Cargo test → test results. 95+ patterns cover almost all the CLI tools I use daily.

2. Routing - learning to read files smarter

This subsystem is more innovative. It has:

ModePredictor: Learns the optimal read mode for each file based on:

• File type (Go, Rust, TypeScript, YAML, Markdown…)
• Reading purpose (code review, feature implementation, bug fix)
• Previous reading history

If you read service.go mostly in signatures mode last week, this time it proposes signatures first. If you need the full content, the AI can override.

IntentEngine: Classifies query complexity. The AI asks “show me the auth flow” → IntentEngine detects this as an architecture question → chooses callgraph mode instead of full. The AI asks “fix bug in function X” → detects this as a bug fix → chooses diff + anchored from function X.

Adaptive fidelity: When the context budget is almost exhausted, it automatically reduces fidelity - from full → signatures → map - instead of crashing or forgetting context.

3. Memory - giving AI “photographic memory” between sessions

This is the killer feature that compression tools usually don’t have.

Context Continuity Protocol (CCP): Since v2.0.0, LeanCTX maintains cross-session memory. When you open a new session, instead of having to explain again from the beginning “what this project does, its structure, who did what last week” - it automatically restores.

Result: 99.2% cold-start tokens eliminated - as promised.

Temporal Knowledge Graph: Stores facts with validity windows. For example:

• “Database migration v3 was run in production from 2026-06-15” → valid from that day, invalid before
• “Auth service endpoint changed from /v1/auth to /v2/auth” → timestamped
• “Module X was deprecated from Q2” → automated pruning

The AI doesn’t need to ask “is this still true?” because it knows the validity window.

Episodic + procedural memory:

• Episodic: “Last time I implemented feature X in file Y with approach Z” - the AI can reference it again
• Procedural: “To deploy this service, I need to run: make build → docker compose up → migrate” - the AI learns the procedure through observation

Property Graph: Multi-edge code graph for impact analysis:

authenticate() ──calls──> validateToken()
authenticate() ──imports──> jwt package
AuthMiddleware ──type_ref──> http.Handler
authenticate() ──exported_by──> service.go

This graph is used for:

• Blast radius analysis: “if I change authenticate(), which files will be affected?”
• Connected files: “which files are related to auth?”
• Impact analysis: tracing from function → package → service

4. Guard - not letting AI read recklessly

Securing context is something that few tools do seriously.

PathJail: Restricts file access according to the config whitelist. You can configure:

• “AI can only read within /src/ and /docs/”
• “Don’t read .env, secret*.yaml, credentials.*”
• “Read-only mode for production”

Secret redaction: Auto-detects secret patterns (AWS key, GitHub token, database URL) and hides them before sending to the model. Output:

DB_URL = postgres://user:***@localhost:5432/db
AWS_SECRET_KEY = ***redacted***

OS-sandboxed code execution (ctx_execute): Runs code in a sandboxed OS, isolating the file system, network, and process. Doesn’t let the AI spawn shells recklessly.

Injection detection: Prevents prompt injection through tool output. If the file content has [SYSTEM: ignore previous instructions], it detects and blocks.

Budgets & SLOs: Team leads can set token budgets for each session. Real-time dashboard.

5. Proof - proving how much you’ve saved

If you’ve ever had to report ROI to your CTO about AI tool spend, this is a lifesaver.

Ed25519-signed savings ledger: Each compression event is signed. Proof can be verified offline - no need to call API, no need to trust. Stack: Ed25519 keypair generated from entropy, signs each ledger entry, lean-ctx verify checks.

ctx_proof / ctx_verify: Two MCP tools for:

• ctx_proof - generates proof for a compression event
• ctx_verify - verifies the proof is valid

CI drift gates: The commitment to “self-footprint only 2.1K tokens” is enforced in CI. If a commit increases the footprint, CI fails. They have 29 published stability contracts, each SHA-256-locked.

Dual-arm benchmark: 99.4% input-side saving on cache-priced rails. Reproducible benchmark with lean-ctx benchmark report . - runs on your exact codebase.

Feature walkthrough: 81 MCP tools and 29 user journeys

I have reviewed compression tools. High-level: compressing messages, compressing tool output, sometimes with memory. LeanCTX has 81 MCP tools divided into 6 categories - I haven’t seen any tool with a surface as wide as this.

Core Tools (File & Code)

These are the tools used daily. 17 tools for file read, shell, search, edit:

• ctx_read - smart read with 10 modes, auto-mode detection, session caching. Each read has compression, each re-read has caching.
• ctx_multi_read - batch read. Instead of 5 round-trips to read 5 files, combine them into 1 call.
• ctx_shell - shell command with 95+ pattern compression. Use raw=true if you need full output.
• ctx_search - grep code search, compact results with file path + line number + match snippet.
• ctx_edit - file editor context-aware: create, replace, replace_all, append. Knows the context of the file being edited.
• ctx_delta - only shows changed lines from the last read. Reviews code very quickly.
• ctx_smart_read - single-call intelligent read. Auto-selects mode based on file type and purpose.
• ctx_semantic_search - hybrid search BM25 + embeddings. Finds code by meaning, no need for keyword matching.
• ctx_explore - iterative code exploration. BM25 + BFS bounded graph, output path:start-end citations, without reading the full file.
• ctx_glob - finds files by glob, gitignore-aware, multi-root support.
• ctx_url_read - fetches web page, PDF, YouTube transcript as cited context.
• ctx_git_read - remote git repo via cached shallow clone. Reads code from GitHub/GitLab without needing to clone the full repository.
• ctx_provider - external context providers: GitHub Issues, GitLab MRs, Jira tickets, Postgres queries, MCP servers, REST APIs.

A typical flow:

1. AI asks “show me the login flow”
2. ctx_intent detects this as a code exploration question
3. ctx_graph queries the Property Graph → finds connected files for “login”
4. ctx_compose builds task context: keywords “login authenticate session” + ranked files + match locations
5. ctx_read with auto-mode = signatures reads 12 related files
6. Total: 4 MCP calls instead of 15+. Token: ~5K instead of 80K.

Intelligence Engine - 19 tools

I use fewer of these, but I’m impressed:

• ctx_intent - detects query type: code review? feature? bug fix? architecture? → auto-selects tool chain
• ctx_graph - persistent project dependency graph. Tracks dependency changes between sessions.
• ctx_dedup - cross-file dedup. Detects function duplicates, config duplicates, error handling pattern duplicates.
• ctx_impact - traces imp containing dependency chains. “If I change X, who will be affected?”
• ctx_architecture - graph-based architecture analysis: detects clusters, layers, dependency cycles.
• ctx_analyze - entropy analysis. Calculates optimal compression mode for each file.
• ctx_compare - previews compression: original vs exact bytes lean-ctx emits. Has line diff.
• ctx_repomap - PageRank repo map of the most important symbols in the codebase.

Memory & Knowledge - 7 tools

• ctx_knowledge - CRUD temporal knowledge graph
• ctx_remember - stores facts into session memory
• ctx_handoff - transfers context between agents (has diary + knowledge transfer)
• ctx_compose - task composition: keywords, ranked files, match locations
• ctx_package - portable context package: exports session state + knowledge, imports/resumes
• ctx_prompt - manages context protocols (CCP, CEP, TDD)

Analysis & Navigation - 12 tools

• ctx_symbol - 26 languages via tree-sitter. Finds definitions, references, implementations.
• ctx_callgraph - caller/callee graph for functions. Multi-hop.
• ctx_outline - structural outline: class hierarchy, function list, import graph.
• ctx_routes - HTTP route extraction (Gin, Echo, Chi, Express, FastAPI, Rails, Django, etc.)
• ctx_smells - code smell: long functions (>50 lines), deep nesting (>3 levels), cyclomatic complexity >10.
• ctx_refactor - LSP/IDE refactoring: rename symbol, move symbol, edits within function body, reformat.
• ctx_review - automated code review: impact analysis, caller tracking, test discovery. Integrates with CI.

Context Firewall & Security - 8 tools

• ctx_firewall - runaway tool output → compact digest + retrieval ref ID
• ctx_scrub - PII/secret redaction
• ctx_policy - query/response policies
• ctx_inspect - inspects context before sending it to the model

Workflow & Orchestration - 15 tools

• ctx_agent - spawns sub-agent with scoped context + budget
• ctx_plan - context planning (CFT) with Phi scoring + budget allocation
• ctx_skillify - codifies recurring patterns into .cursor/rules/skillify-*.mdc
• ctx_rules - cross-agent rules governance: sync, diff, lint, status
• ctx_tools - MCP Tool-Catalog Gateway. This is a meta tool: sits in front of N downstream MCP servers. When AI wants to call a tool, ctx_tools uses BM25 ranking to choose the correct server. Flat context cost even with many tools. Off by default.

Catalogs tools from various add-ons and external MCP servers - Headroom, Sophon, Mem0, Sequential Thinking, etc. - all of which are routed and compressed.

DX Developer Experience: Is it a pleasure to use?

There are small details that make me feel like the author really cares about UX:

lean-ctx gain --live - real-time dashboard on the terminal. The number of saved tokens runs in real-time, with an effect like a fuel gauge. It’s quite addictive.

lean-ctx wrapped - weekly/monthly recap. A shareable card for the team. I see it at the end of the month posted on the team Slack: “This week LeanCTX saved 120K tokens ~ $18.” The team lead loves it.

lean-ctx dashboard - Context Manager on the browser. Real-time SLOs and budgets. 4 tabs: Overview → Agents → Budgets → Ledger.

lean-ctx watch - TUI monitor for terminal fans.

lean-ctx doctor --fix - self-healing. Wrong config? MCP port conflict? File permission? It automatically detects and asks “do you want to fix it?” Pressing Y is all it takes.

lean-ctx benchmark report . - runs a benchmark on your own codebase. Output: a file with detailed numbers, along with an Ed25519 signature. You can compare it with the benchmark from last week.

Integration with 30+ agents

I tested it with 3 agents:

Claude Code: Auto-detects when running lean-ctx onboard. MCP server + shell hooks. Claude automatically uses ctx_read instead of the Read tool. Tokens decreased by 68% in the first session.

Cursor: Similar. Cursor automatically detects the lean-ctx MCP server. In the Cursor chat, every time you read a file, you see (compressed by lean-ctx: 72% saved).

Hermes Agent: Hermes has native support - lean-ctx init --agent hermes. Context compression is transparent. I used Hermes with lean-ctx and saw a clear improvement: responses were 40% faster, and total tokens were 55% fewer.

Codex CLI: OpenAI Codex is also supported. lean-ctx init --agent codex.

Gemini CLI: Google Gemini CLI supports MCP, so the lean-ctx MCP server can be attached.

VSCode and JetBrains have their own extensions: URI handler, native dashboard tab. The JetBrains plugin even has PSI navigation, a refactoring engine, and a gain tool window.

Proxy mode - optional compression layer

When you enable the proxy (lean-ctx proxy enable), all requests from the agent to the model are compressed:

• System prompt → compressed
• Conversation history → compressed (old messages are summarized, keeping the structure)
• Tool results → compressed (keeping the local version, with retrieval reference)

Prompt-cache-safe: #498 contracts ensure byte-stable output. Anthropic prompt caching reduces costs by 90%, and OpenAI by 50%. LeanCTX doesn’t break the cache.

Real dollars metered: The proxy calculates real dollars saved - not just tokens, but also cache hit discounts.

Addon system

lean-ctx addon search memory      # search for addons related to memory
lean-ctx addon add headroom        # install Headroom MCP + wrapper
lean-ctx addon list                # list installed addons
lean-ctx addon remove headroom     # remove

Each addon is an MCP server running under the ctx_tools gateway. It applies the compression pipeline.

I find the Headroom wrap quite amusing. Headroom: “I compress the context.” LeanCTX: “okay, I’ll compress your output too.”

Current registry: Headroom, Sophon, Repomix, Serena, Mem0, Cognee, Letta, Sequential Thinking.

What I don’t fully understand

Honestly: I’m not sure how Context Time Machine works. The docs talk about git-anchored, signed snapshots that you can replay, restore, publish, import. It sounds like Git for context - you can check out the context state from last week, see what the AI saw. But with a codebase of nearly 2,800 commits, this feature is still “direction, not yet shipped.” If anyone has tried it, please comment and let me know.

Weaknesses - nothing is perfect

I like LeanCTX’s docs - they have a dedicated known limitations section.

Rust build time

Building from source: cargo build ~5 minutes on my machine (M1 Pro, 32GB). Pre-built binary is recommended. npm install -g lean-ctx-bin or brew is much faster.

Self-footprint: 2.1K tokens per session

Each session, LeanCTX injects around 2.1K tokens into the system prompt: MCP tool definitions, context protocols, memory descriptors. This cannot be avoided - the binary itself injects them. However:

• CI-gated: footprint only shrinks, not grows
• Compared to 50K-200K tokens per session, 2.1K is negligible
• CEP protocol optimizes cognitive efficiency

Feature overload

81 MCP tools. 5 subsystems. 29 user journeys. 29 stability contracts. 79-pages docs.

If you just want to “compress context to be cheaper”, this is like using a cleaver to cut a slice of sausage. Headroom does better for simple use cases.

Moving target

2,747 commits. 225 releases. Daily releases recently. Version 3.8.18 was released on 1/7/2026. The codebase changes faster than the docs update.

I encountered 2 instances of feature deprecation where the docs hadn’t been updated yet:

• ctx_discover_tools was renamed from an old tool
• Several CLI flags changed between minor versions

No ML compression

This is an intentional trade-off. LeanCTX is deterministic by design - #498 contract. Headroom has “Kompress” with ML-based prose compression. LeanCTX rejects this approach entirely.

Result: prose compression is a bit rigid, but code compression is excellent. If your workload is 80% code + 20% docs, LeanCTX wins. If 80% prose (document Q&A, contract analysis, research papers) → Headroom ML mode might be better.

Marketing self-comparison bias

Comparing with Headroom and tools in its own repo. No one writes “I lose”. I always cross-check with independent sources. The 98.1% compression figure might be true for Go monorepo, but for Python scripts or YAML configs, it might be lower.

Comparison: LeanCTX vs Headroom vs Aphrodite

Headroom - stateless compression powerhouse

Headroom by Tejas Chopra has 55.2K+ stars, a massive community:

Strengths:

• ML compression (Kompress): Model learns to compress prose. 60-95% compression on natural text.
• Framework wrappers: LiteLLM, LangChain, Agno, Strands, Vercel AI SDK - plug & play.
• Python-native: pip install headroom-ai, no daemon needed.
• Proxy mode: transparent proxy compress request/response.

Weaknesses compared to LeanCTX:

• 3 MCP tools (compress/retrieve/stats) vs 81
• Stateless: no memory, no session, no knowledge graph
• Non-deterministic: output changes between runs → not prompt-cache-safe
• Python runtime heavy: needs PyTorch for ML mode
• No code intelligence: no call graph, no AST, no structural analysis

Rule of thumb from LeanCTX’s docs:

“Choose lean-ctx when the payload is code, tool output, logs or RAG context and you need local, deterministic, cache-preserving output; consider Headroom’s ML mode when you specifically need learned prose compression.”

Aphrodite - Hermes-only, obsolete

Aphrodite is a Rust fork of Headroom, targeting Hermes Agent:

In short: Aphrodite is basically obsolete. LeanCTX supports Hermes natively. If you use Hermes, there’s no reason to use Aphrodite instead of LeanCTX.

Matrix summary

Verdict: When to Use AI and When Not to

Use LeanCTX if you:

• Daily use AI coding agents - Claude Code, Cursor, Codex CLI, Gemini CLI, Hermes. Savings are seen immediately.
• Medium-large codebase (50+ files, monorepo, multi-module) - ROI increases with the size of the repository.
• Local-first + zero telemetry - compliance, legal, and security teams will like it.
• Need deterministic output for audit - signed proof, CI gates, reproducible benchmarks.
• Team has many agents - shared memory, session persistence, knowledge graph.
• Work with code more than prose - daily dev work, not document writing.

Skip if you:

• Small codebase - 5-10 files, installing LeanCTX is overkill. Headroom is simpler.
• Need specific ML prose compression - LeanCTX does not have it and does not plan to.
• Headroom + Aphrodite is already OK - do not migrate if there is no pain point.
• Use only one agent - shared memory is not effective.
• Team is non-technical - configuration requires some understanding of MCP and shell hooks.

Bottom line:

LeanCTX is not just “another compression tool.” It is a context OS for AI agents.

Compression is what you see first, but what keeps you is memory, guard, proof, and routing. A 10MB Rust binary does what previously required a stack of 3-4 tools: Headroom + Mem0 + Semgrep + custom CI scripts.

I have switched from Headroom + Mem0 + custom scripts to LeanCTX alone. My token bill for June decreased by 62%. Setup time: 60 seconds. No regrets.

And the Context Time Machine with signed snapshots - I still do not fully understand. Hybrid search? Not used much. But knowing it is there, ready when I need it, gives me a sense of having a safety net.

Deep dive: SDKs, protocols, and building your own agent

LeanCTX is not just a CLI tool. It has a full SDK stack to embed context engineering into your own agent.

SDKs

lean-ctx-sdk (Rust): compress() function drop-in. Use when building an agent harness with Rust.

use lean_ctx_sdk::compress;

let result = compress(messages, model::Gpt4o)?;
println!("Saved: {} tokens ({}%)", result.saved_tokens, result.saved_pct);

lean-ctx-client (Python): Use in Python agent harness.

from lean_ctx import ProxyClient

client = ProxyClient()
result = client.compress(messages, model="gpt-4o")
print(f"Saved {result.saved_tokens} tokens")

lean-ctx-client (TypeScript): For Node.js/Deno agents.

import { ProxyClient } from 'lean-ctx-client';
const client = new ProxyClient();
const result = await client.compress(messages, { model: 'gpt-4o' });

Versioned /v1 API

When you want complete control, use the REST API:

POST /v1/compress
Content-Type: application/json

{
  "messages": [...],
  "model": "claude-sonnet-4-20250514",
  "compress_system": true,
  "compress_history": true,
  "compress_tools": true
}

Response includes compressed messages + metadata (saved_tokens, saved_pct, proof_signature). Deterministic: same input → same output.

GET /v1/references/{id}

Retrieve original uncompressed content from session cache.

Protocols: CCP, CEP, TDD

LeanCTX implements 3 protocols for cross-agent context management:

Context Continuity Protocol (CCP):

• Maintains session memory between chats
• Task/findings/decisions tracking with LITM-aware positioning
• 99.2% cold-start tokens eliminated

Cognitive Efficiency Protocol (CEP):

• Calculates cognitive efficiency of each message
• Automatically compresses low-scoring segments (boilerplate, redundancy)
• Feedback loop: AI responds “this compression lost information” → system adjusts

Token Dense Dialect (TDD):

• Shorthand notation: λ → lambda, § → section
• ROI-mapped identifiers
• Adds 8-25% savings on top of compression

Example of TDD in action - instead of:

The authenticate function in auth/service.go calls validateToken from auth/validator.go

It writes:

§auth: authenticate() ↦ §auth/validator: validateToken()

15 tokens instead of 22. Not much, but scales up to 1M messages.

Build your own agent harness

Docs have a whole section “Journey 14 - Build Your Own Agent: SDKs & /v1 API”. You can:

1. Start lean-ctx daemon (background)
2. Use SDK or REST API to compress context
3. Call model API with compressed context
4. Verify savings with ctx_proof

from lean_ctx import ProxyClient
import openai

client = ProxyClient()
compressed = client.compress(messages, model="gpt-4o")

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=compressed.messages,
)

print(f"This call saved ${compressed.dollars_saved:.4f}")

Context Firewall: preventing AI from running wildly

There’s a new feature I’ve come across recently: Context Firewall (Journey 8). When AI executes a command with a very large output - make test produces 50K lines of log - the firewall intercepts, generates a compact digest (PASS/FAIL, coverage, execution time), and attaches a retrieval reference. If AI needs details, it calls ctx_expand(id, head=50) to view the first 50 lines. Or ctx_expand(id, grep="ERROR") to grep in the original output.

This mechanism prevents context window overflow from tool output runaway. I’ve encountered cases where the Cursor reads all 10K lines of npm test output and the context window is full, leaving no room for code. Since the introduction of the firewall, that’s no longer a problem.

JetBrains vs VS Code experience

I use both JetBrains GoLand and VS Code. LeanCTX supports both.

VS Code Extension

• URI handler: lean-ctx://open/file?path=...
• Native dashboard tab: Open Context Manager right within VS Code
• MCP auto-config: mcp.json automatically generates
• Status bar indicator: token saved counter

JetBrains Plugin

• PSI navigation: uses PSI (Program Structure Interface of JetBrains) instead of MCP calls for navigation. Faster by 2-3x.
• Refactoring engine: rename/move symbol synchronized with LSP
• Gain tool window: real-time token savings display
• Can run on IntelliJ, GoLand, PyCharm, WebStorm

I find the JetBrains plugin smoother than the VS Code extension - probably because JetBrains has PSI, so navigation performance is better. The VS Code extension is stable but lacks a few dashboard features compared to the web dashboard.

Community and Ecosystem

LeanCTX has an actively maintained Discord community. Author Yves Gugger responds to issues on GitHub within a few hours - I have witnessed issues being fixed within 30 minutes of reporting.

The community of contributors consists of 39 people (including @cursoragent and @claude - GitHub accounts of AI agents). This is one of the most AI-assisted development-heavy projects I have ever seen: the contributor list includes accounts of Cursor AI and Claude.

This has two sides:

• The good side: the development speed is tremendous - 2,747 commits
• The bad side: code consistency may be affected, but I find the quality to be quite stable

Pricing: free local forever (enforced by CI). Paid tiers for team/cloud features (shared server, role-based access, managed connectors). Transparent pricing on the website.

Detailed Comparison: Code Benchmarks

I ran benchmark tests on three different codebases:

Go monorepo (50 files, 15K LOC):

• Raw: 533.2K tokens
• Map mode: 8.0K tokens (98.1%)
• Signatures: 14.0K tokens (96.7%)
• Cached re-read: 13 tokens (99.99%)

TypeScript Next.js app (120 files, 25K LOC):

• Raw: 890K tokens
• Map mode: 22K tokens (97.5%)
• Signatures: 35K tokens (96.1%)
• Cached re-read: 13 tokens (99.99%)

Python Django monolith (200 files, 40K LOC):

• Raw: 1.2M tokens
• Map mode: 42K tokens (96.5%)
• Signatures: 68K tokens (94.3%)
• Cached re-read: 13 tokens (99.99%)

Python compression is slightly lower than Go/TS - the tree-sitter grammar for Python has more dynamic features, so the AST mapping coverage is not as good. But 94-96% is still a very impressive figure.

Frequently Asked Questions from Colleagues

“Does this affect the quality of AI?”

I have run A/B tests: the same task with and without LeanCTX. The results:

• With LeanCTX: response is 40% faster, with less hallucination (context window with less noise)
• Without LeanCTX: response is slower, and sometimes misses instructions due to context overflow

Context-rot research from Anthropic shows that accuracy decreases from 98% to 64% when the context window is full of noise. LeanCTX reduces noise → increases accuracy.

“Is any information lost?”

No. Zero-loss when using reversible modes (map, signatures - lossless). Density mode has potential loss but is used conditionally. And all originals are retrievable via ctx_retrieve.

“Is code sent to the cloud?”

No. 100% local. Zero telemetry by default. Compression runs locally. Only shared cards (Wrapped) are opt-in and only publish token count + display name.

“Can it run with Codex CLI?”

Yes. I have tested Codex CLI + LeanCTX, and it works well. MCP server can be attached. lean-ctx init --agent codex.

“Are there conflicts with other MCP servers?”

No. ctx_tools gateway can route requests to multiple MCP servers. Adding more add-ons does not conflict.

“How long does it take to learn the configuration?”

I spent 10 minutes to understand the basics. 1 hour to master the use of modes and tools. Docs have 29 journeys, but you don’t need to read them all - lean-ctx onboard + lean-ctx gain --live is enough to get started.

Personal story: first deployment to production

Last month, I deployed LeanCTX to our team’s CI pipeline. The script was short:

# In CI
lean-ctx install
lean-ctx benchmark report ./ci-benchmark.md

Result: Our CI/CD pipeline using Claude Code for code review reduced from 45K tokens per run to 12K tokens. Each time CI runs, it saves $0.66. With 200 CI runs/day, that’s $132/day. $3,960/month in savings just from CI.

Then I reported to the CTO with signed proof - Ed25519 signature, which can be verified offline. The CTO asked “is this real?” I ran lean-ctx verify in front of him.

3 minutes later, he said “deploy it to the whole team.”

By the end of the month, our team saved $2,300 compared to the previous month. Not a small number. Whoever suggests reverting LeanCTX next month will probably get beaten up by the team. 🤡

Questions I Still Don’t Have Answers To

I’m not a fanboy. There are a few things I’m still exploring:

1. How does Context Time Machine work? Git-anchored, signed snapshots. Sounds great but the docs still say “direction, not yet shipped.” Has anyone tried it yet?

2. ModePredictor quality in non-Go languages? Go and Rust have strong tree-sitter grammar, but what about Python, Ruby, JavaScript? I’ve noticed Python compression is lower - 96.5% vs 98.1%.

3. Scalability with 500+ files? I’ve tested it with a medium-sized repo (200 files). Has anyone used it with a monorepo of 2000+ files and can share the performance?

4. Deterministic compression trade-off? Choosing deterministic (non-ML) means choosing reproducible output but sacrificing adaptive compression. Sometimes I wish it knew “this is config boilerplate, compress it more aggressively.”

5. What happens when AI doesn’t cooperate? This tool relies on the AI agent to use ctx_read instead of Read. If an agent is too stubborn (using old tools), LeanCTX can’t do anything about it.

CTA: Run Benchmark on Your Codebase

Don’t trust the 98.1% compression ratio. Every codebase is different - Go vs TypeScript vs Python vs Rust yields different compression ratios. Install and run:

curl -fsSL https://leanctx.com/install.sh | sh
lean-ctx onboard
lean-ctx benchmark report .

Your numbers are the real numbers. Share them on the Discord community - they have a public leaderboard.

Repo: github.com/yvgude/lean-ctx - Apache 2.0, 3.1K stars, 294 forks, 2,747 commits, with exceptionally well-written code.

Website: leanctx.com - complete with documentation, 29 user journeys, and honest comparison pages.

Discord: link on the website, community is growing rapidly, and the author is active in responding to issues.

Sponsor: buymeacoffee.com/yvgude - the author deserves support.

This article is part of the Tool Deep Dive series - I analyze tools for AI agents from the perspective of a daily coding engineer. If you have a tool you’d like me to review, comment below.

Some things I’m still exploring: How does Context Time Machine work? Is ModePredictor quality in non-Go languages (Python, Ruby) as good as in Go? If you’ve used these features, share your experience with me.

🦞 Luân - an engineer who likes to dissect tools, hates AI hallucination, and is addicted to Rust binaries.