How It Works

The Context Engineering Layer
for AI Coding.

lean-ctx is a compression system with three independent layers. A context server replaces your AI's file reads with AST-aware compressed versions. A shell hook intercepts 95+ CLI command patterns. And three communication protocols teach the AI to respond more efficiently. You install it once - everything else is automatic.

The data flow

Where does lean-ctx sit?

lean-ctx intercepts at two levels: the context layer (file reads, code search, shell commands) and the shell layer (raw CLI output). Both compress data before it reaches the LLM. The AI sees the same information in a fraction of the tokens.

data flow - before vs. after 
Without lean-ctx:

You  →  AI Tool  →  reads file  (full content)  →  LLM processes everything

With lean-ctx:

You  →  AI Tool  →  lean-ctx compresses  →  signal only  →  LLM: 60–99% less noise
                           ├─ PathJail sandbox + size caps
                           ├─ AST-aware compression
                           ├─ Memory Runtime (knowledge + forgetting)
                           ├─ Session cache (re-read ≈ 13 tok)
                           └─ 10 read modes per file type

You

Code normally. Change nothing about your workflow.

AI Tool

Cursor, Claude Code, Copilot, Windsurf, …

lean-ctx

Compresses everything via Context Server & Shell Hook.

LLM

Sees only signal. 60–90% fewer tokens, same information.

Two commands. That's it.

What do YOU actually do?

Almost nothing. lean-ctx works invisibly after a one-time setup. You keep coding exactly like before.

01

Install

Single Rust binary. No dependencies, no cloud, no account.

curl -fsSL leanctx.com/install.sh | sh
02

Setup

Auto-detects your shell and AI tools. Configures everything in seconds.

lean-ctx setup
03

There is no step 3

Code normally. Your AI uses compressed tools automatically.

Tokens saved: automatically

You vs. The Machine

What YOU do (once) What happens AUTOMATICALLY
lean-ctx setup AI uses ctx_read instead of Read - up to 99% fewer tokens (cached re-reads)
AI uses ctx_shell instead of Shell - 60–90% fewer tokens
AI uses ctx_search instead of Grep - 50–80% fewer tokens
Shell hook compresses CLI output transparently
Session cache remembers files across reads (~13 tokens for re-reads)
lean-ctx gain (optional) See your lifetime savings dashboard

Full setup guide → Getting Started  ·  All CLI commands → CLI Reference

Reciprocal Rank Fusion (RRF) Cache Eviction

When the session cache is full, lean-ctx uses Reciprocal Rank Fusion to decide which entries to evict. Each signal (recency, frequency, size) is ranked independently, then fused into a single score - no arbitrary weight tuning required.

Formula: RRF(d) = Σ 1/(K + rank_i(d)) where K=60. This handles signal incomparability (seconds vs counts vs tokens) without needing tuned weights, unlike traditional weighted combinations.

Want to understand the architecture?

Explore the Context OS: the six-step pipeline, integration modes, agent matrix, Context Field Theory, and nine architectural pillars that make lean-ctx work.

Deep dive into Context OS

Security Layer

lean-ctx enforces a defense-in-depth security model to prevent LLM prompt injection from accessing files outside the project:

  • PathJail - All file operations are sandboxed to the project root. Symlink traversal, ../ escapes, and absolute paths outside the jail are blocked at the resolve_path chokepoint.
  • Bounded Shell Capture - Shell output is capped at 200KB with clear truncation markers. Prevents memory exhaustion from runaway commands.
  • TOCTOU Prevention - File edits use same file handle for read-verify-write, eliminating time-of-check-to-time-of-use race conditions.
  • Build Integrity - Compile-time integrity seed and hash verification detect tampered binaries. Checked automatically by lean-ctx doctor.
Get started

Ready to start saving?

One binary. Zero cloud dependencies. Apache-2.0 licensed. Install in 60 seconds and start saving tokens immediately.

Get Started Check Compatibility