lean-ctx — Summary

lean-ctx (Lean Cortex) is a single Rust binary with 62 MCP tools that compresses AI agent context at three layers: file reading (10 compression modes, tree-sitter AST for 18 languages, cached re-reads at ~13 tokens), shell output (60+ pattern modules for git/npm/cargo/docker/kubectl), and session memory (CCP — context-carry protocol across chats). Its own benchmark shows 83.6% session savings without CCP and 84.7% with CCP; map mode achieves 96% compression on Rust files. README claims "up to 99%" and "60-99% compression on shell output."

It ships lean-ctx setup (one-command install of shell hook + editor wiring + rules + skills), a browser-based Context Manager dashboard, a lean-ctx gain --live real-time savings counter, a SKILL.md that mandates replacing native Read/Grep/Bash with ctx_read/ctx_shell/ctx_search, multi-agent tools (ctx_agent, ctx_handoff), LSP refactoring (ctx_refactor), and cryptographic context proofs (ctx_proof, ctx_verify).

Compared to seeds, lean-ctx is closest to ccmemory (MCP memory layer) but is broader: it compresses every tool interaction (not just session memory), ships 62 tools (vs ccmemory's ~10), targets 23+ AI clients (not just Claude Code), and adds real-time observability. The SKILL.md's "CRITICAL: NEVER use native Read, Grep, or Shell directly" is the most aggressive tool-replacement mandate in this batch.

lean-ctx — Overview

Origin

Yves Gugger (yvgude). Apache-2.0 and MIT dual license. Rust. Version 3.3.6. Available on crates.io, npm (lean-ctx-bin), Homebrew, AUR, and Pi.dev. Active (last commit 2026-05-26). 20 contributors.

Philosophy

From README:

"LeanCTX stands for Lean Cortex: a lightweight cognitive layer that helps AI agents perceive, compress, remember, route, and reuse context across workflows."

"It governs every token between your code and the AI — so you make better decisions, not just cheaper ones."

From LEAN-CTX.md (injected as agent rules):

"CRITICAL: ALWAYS use lean-ctx tools instead of native equivalents. This is NOT optional." "NEVER use native Read, Grep, or Shell directly."

Three Layers

1. Compression — file reads + shell output compressed by mode and pattern
2. Memory — CCP (context-carry protocol) persists tasks/facts/decisions across chat sessions
3. Governance & Observability — real-time dashboard, budgets, SLOs, context proofs

Benchmark Proof

From BENCHMARKS.md (self-measured via lean-ctx benchmark report .):

Session simulation (30-min coding): 83.6% savings without CCP, 84.7% with CCP.

Verbatim from README: "Repeated file reads: ~2000 tokens each → Cached re-reads: ~13 tokens", "Raw git status: ~800 tokens → Compressed: ~120 tokens"

lean-ctx — Architecture

Distribution

• Universal install: curl -fsSL https://leanctx.com/install.sh | sh
• Homebrew: brew tap yvgude/lean-ctx && brew install lean-ctx
• npm: npm install -g lean-ctx-bin
• Cargo: cargo install lean-ctx
• Pi: pi install npm:pi-lean-ctx

Directory Structure

rust/                    # Rust source (binary)
skills/lean-ctx/         # SKILL.md + install scripts
  └── SKILL.md           # Agent behavioral mandate
.claude-plugin/
  └── manifest.json      # Plugin manifest v3.3.6
.claude/
  ├── lean-ctx/          # Claude-specific rules
  └── rules/             # Additional rule files
bin/                     # Helper scripts
benchmark/               # Benchmark tooling
cookbook/                # Usage recipes

CLI Binary

lean-ctx — own Rust runtime, not a wrapper.

Key subcommands:

• lean-ctx setup — install shell hooks + editor wiring
• lean-ctx -c <cmd> — run command with compression
• lean-ctx read <file> -m <mode> — compressed file read
• lean-ctx gain --live — real-time token savings
• lean-ctx gain --wrapped — weekly/monthly savings summary
• lean-ctx serve — HTTP MCP endpoint
• lean-ctx pack [--pr] — context package builder
• lean-ctx doctor — diagnostic tool
• lean-ctx benchmark report <path> — compression benchmark

State Files

• ~/.config/lean-ctx/config.toml — global config
• .lean-ctx.toml — per-project overrides (auto-merged)
• .lean-ctx-id — unique project ID (for Docker/multi-workspace)
• CCP storage: unknown path (local session memory)

Required Runtime

None (statically linked Rust binary).

Target AI Tools

Cursor, Claude Code, GitHub Copilot, Windsurf, Codex, Gemini, and 23+ other agents. Two integration modes:

• Hybrid: MCP + shell hooks (agents with shell access)
• MCP only: protocol-only agents (JetBrains, VS Code, Zed)

lean-ctx — Components

MCP Tools (62)

Categories from README:

Core Read/Search (10 modes) ctx_read(path, mode) — 10 modes: auto, full, map, signatures, diff, aggressive, entropy, task, reference, lines:N-M

Shell/Command Tools ctx_shell(command) — pattern compression for 60+ shell tools ctx_search(pattern, path) — token-efficient grep ctx_tree(path, depth) — compact directory maps ctx_edit(path, old, new) — search-and-replace without Read

Memory (CCP) ctx_compress — compress current context when large ctx_overview(task) — session overview at start

Search & Intelligence Hybrid BM25 + embeddings + graph proximity (RRF-ranked)

LSP Refactoring ctx_refactor — language-server powered rename, go-to-def, find-references

Multi-Agent ctx_agent — start/manage agent run ctx_handoff — transfer context to another agent

Cryptographic Proofs ctx_proof — create context proof ctx_verify — verify context integrity

Observability ctx_expand — FTS5 cross-archive search Context Manager dashboard tools

Other notable ctx_overview, archive search, PR context packs, .ctxpkg package builder

SKILL.md (1)

skills/lean-ctx/SKILL.md — the behavioral mandate installed as a Claude Code skill:

• "CRITICAL: ALWAYS use lean-ctx tools instead of native equivalents."
• Tool mapping table (MUST USE vs NEVER USE)
• Mode selection guide

Plugin

.claude-plugin/manifest.json — Claude Code plugin v3.3.6

Scripts

skills/lean-ctx/scripts/install.sh — auto-install script referenced in SKILL.md

Hooks

None defined in .claude-plugin/; integration via lean-ctx setup which registers shell hooks.

lean-ctx — Uniqueness

Differs From Seeds

Closest seed: ccmemory (MCP memory layer for coding agents). Key deltas: (1) lean-ctx is a full-session context runtime, not just a session memory store — it compresses every file read and shell command in real time, while ccmemory only captures decisions/corrections at session end. (2) lean-ctx ships 62 MCP tools (vs ccmemory's ~10) covering read modes, shell compression, memory, search, multi-agent, LSP refactoring, and cryptographic proofs. (3) lean-ctx targets 23+ AI clients (high portability); ccmemory targets only Claude Code (low portability). (4) lean-ctx ships a browser-based real-time dashboard; ccmemory has no UI. (5) lean-ctx's LEAN-CTX.md mandate ("CRITICAL: NEVER use native Read, Grep, or Shell") is the most aggressive tool-replacement directive in this batch. Against entroly (the other compression framework): lean-ctx compresses tool outputs at the provider level (wraps file reads + shell); entroly compresses at the LLM API proxy level (intercepts API calls). They differ architecturally but share the token-reduction goal.

Positioning

"The cognitive context layer that governs every token between code and AI — compression + memory + governance + observability, all in one zero-dependency Rust binary."

Unique Features in Batch

1. Reproducible benchmarks: lean-ctx benchmark report . generates committed benchmark data with language-by-language savings and quality scores
2. Cryptographic context proofs: ctx_proof/ctx_verify for audit trails — unique in this batch
3. Browser dashboard: real-time token tracking and cost visibility — unique in this batch
4. 10 read modes: granularity from lines:N-M to signatures to aggressive — unique level of per-file control
5. Shell pattern compression: 60+ named patterns for specific CLI tools — not present in any other framework in this batch

Observable Failure Modes

1. LEAN-CTX.md mandate rigidity — "NEVER use native Read" can cause issues when ctx_read fails for a binary file or unsupported format; the SKILL.md fallback instruction ("fall back only if unavailable") may not be clear enough.
2. 62-tool context overhead — injecting 62 tool descriptions into Claude's context window uses ~5K tokens before any work; lean-ctx's own instruction to use itself consumes the savings it provides at scale.
3. Quality metric ambiguity — BENCHMARKS.md shows aggressive mode: "4.1% savings / 100% quality" — contradicts the README's "aggressive = maximum compression" claim.
4. CCP internals opaque — the exact storage format for CCP is not documented publicly; upgrading lean-ctx may break CCP continuity.
5. Property Graph not externally queryable — the knowledge graph powers search ranking but doesn't expose raw graph queries to agents.