╭──────────────────────────────────────────╮ ╭──────────────────────────────────────────╮ │ >>>>>>>>>>>>>>> ctx_read >>>>>>>>>>>> │ │ >>>>>>>>>>>>>>> ctx_read >>>>>>>>>>>> │ ┌─────────────┐ │ >>>>>>>>>>>>>>> compress >>>>>>>>>>>> │ ┌──────────┐ ┌─────────────┐ │ >>>>>>>>>>>>>>> compress >>>>>>>>>>>> │ ┌──────────┐ │ 100K tokens │ =========>│ >>> AST >>> cache >>> signal >>> │ =========> │ ~5K tok │ │ 100K tokens │ =========>│ >>> AST >>> cache >>> signal >>> │ =========> │ ~5K tok │ └─────────────┘ │ >>>>>>>>>>>>>>> filter >>>>>>>>>>>> │ └──────────┘ └─────────────┘ │ >>>>>>>>>>>>>>> filter >>>>>>>>>>>> │ └──────────┘ │ >>>>>>>>>>>>>>> dedupe >>>>>>>>>>>> │ │ >>>>>>>>>>>>>>> dedupe >>>>>>>>>>>> │ ╔══════════════╗ ╰──────────────────────────────────────────╯ ╔══════════╗ ╔══════════════╗ ╰──────────────────────────────────────────╯ ╔══════════╗ ║ raw input ║ ─ ─ ─ ─ ─ ─ ─ ─ LeanCTX ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║ output ║ ║ raw input ║ ─ ─ ─ ─ ─ ─ ─ ─ LeanCTX ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║ output ║ ╚══════════════╝ ╚══════════╝ ╚══════════════╝ ╚══════════╝ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │░░│ │░░│ │░░│ │░░│ │▓▓│ │▓▓│ │▓▓│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │▓▓│ │▓▓│ │▓▓│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ ───> │▓▓│ │▓▓│ │▓▓│ ───> │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ ───> │▓▓│ │▓▓│ │▓▓│ ───> │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ file file file file read cache send tok tok tok tok tok tok file file file file read cache send tok tok tok tok tok tok ╭──────────────────────────────────────────╮ ╭──────────────────────────────────────────╮ │ >>>>>>>>>>>>>>> ctx_read >>>>>>>>>>>> │ │ >>>>>>>>>>>>>>> ctx_read >>>>>>>>>>>> │ ┌─────────────┐ │ >>>>>>>>>>>>>>> compress >>>>>>>>>>>> │ ┌──────────┐ ┌─────────────┐ │ >>>>>>>>>>>>>>> compress >>>>>>>>>>>> │ ┌──────────┐ │ 100K tokens │ =========>│ >>> AST >>> cache >>> signal >>> │ =========> │ ~5K tok │ │ 100K tokens │ =========>│ >>> AST >>> cache >>> signal >>> │ =========> │ ~5K tok │ └─────────────┘ │ >>>>>>>>>>>>>>> filter >>>>>>>>>>>> │ └──────────┘ └─────────────┘ │ >>>>>>>>>>>>>>> filter >>>>>>>>>>>> │ └──────────┘ │ >>>>>>>>>>>>>>> dedupe >>>>>>>>>>>> │ │ >>>>>>>>>>>>>>> dedupe >>>>>>>>>>>> │ ╔══════════════╗ ╰──────────────────────────────────────────╯ ╔══════════╗ ╔══════════════╗ ╰──────────────────────────────────────────╯ ╔══════════╗ ║ raw input ║ ─ ─ ─ ─ ─ ─ ─ ─ LeanCTX ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║ output ║ ║ raw input ║ ─ ─ ─ ─ ─ ─ ─ ─ LeanCTX ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║ output ║ ╚══════════════╝ ╚══════════╝ ╚══════════════╝ ╚══════════╝ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │░░│ │░░│ │░░│ │░░│ │▓▓│ │▓▓│ │▓▓│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │▓▓│ │▓▓│ │▓▓│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ ───> │▓▓│ │▓▓│ │▓▓│ ───> │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ ───> │▓▓│ │▓▓│ │▓▓│ ───> │░░│ │░░│ │░░│ │░░│ │░░│ │░░│ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ └──┘ file file file file read cache send tok tok tok tok tok tok file file file file read cache send tok tok tok tok tok tok

How It Works

How LeanCTX controls what
your AI sees.

LeanCTX is the Cognitive Context Layer between your AI and your code: one small Rust binary that runs the same loop on every read, command and search. It perceives structure across 18 languages, compresses the noise, remembers across sessions, routes the right context to each model, and governs every tool call. You install it once. Everything else is automatic.

The data flow

Where does LeanCTX sit?

LeanCTX 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–90% 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

Deep dive: Shell Patterns (95+ patterns) · Read Modes (10 compression modes) · Caching

You

Code normally. Change nothing about your workflow.

AI Tool

Cursor, Claude Code, Copilot, Windsurf, …

LeanCTX

Decides, compresses and remembers via Context Server & Shell Hook.

LLM

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

Architecture

One binary. Five capabilities.

Every capability runs inside a single Rust binary. Here is how a request flows through LeanCTX: from your AI tool, through the cognitive pipeline, to the model.

Your AI Tool Cursor · Claude Code · Copilot · Windsurf

MCP · CLI · HTTP

lean-ctx Cognitive Context Layer · Single binary · 76 tools

Understand

10 read modes
Context visibility
Token counting
Intent detection

Compress

Tree-sitter AST (18 langs)
95+ shell patterns
CDC reorder (Rabin-Karp)
64 KB budget, 500 ms deadline

Remember

Session cache (zstd, in-memory)
13-token re-reads
Knowledge graph (SQLite)
Cross-session memory

Verify

PathJail sandbox
OS-level isolation
Shell allowlist (deny-by-default)
Full audit trail

Connect

GitHub · GitLab · Jira · Linear
Postgres · REST · MCP Bridge
Hybrid search (BM25 + semantic)
Config-based providers (TOML)

10read modes

13tokens per re-read

18languages (AST)

optimized context

LLM Less noise · Higher signal · Better results

The five subsystems

Five things LeanCTX does to every token.

Between your AI and your code, one local binary runs the same five-step loop on every read, command, and search: perceive, compress, remember, route, and govern, so your AI sees the signal, keeps its memory, and stays inside the guardrails.

Perceive

See what matters before you act.

Map an unfamiliar repo, surface the files and symbols that matter, and read structure instead of whole files, across 18 languages with tree-sitter.

ctx_overview → repo mapped in one call

Compress

Every token carries signal.

Ten read modes, 95+ shell-output patterns and content-addressed caching shrink reads 60–90% and re-reads to ~13 tokens. The noise never reaches the model.

ctx_read → 4,200 → 920 tokens (78% saved)

Remember

Continuity across sessions.

Findings, decisions and touched files persist and auto-restore into every new session, so your agent never re-explains context or re-reads what it already knows.

ctx_session → restored · 0 re-reads

Route

The right context to the right model.

Detect intent, pick the read mode and token budget, and load only the tools a task needs, so each model sees exactly the context it should, and nothing more.

ctx_intent → right mode + budget per task

Govern

Safe, measured, enforced.

PathJail, a shell allowlist, secret detection, role policies and token budgets keep every tool call in bounds, and analytics prove exactly what was saved.

ctx_verify → paths ok · secrets blocked

Two commands. That's it.

What do YOU actually do?

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

Install

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

curl -fsSL https://leanctx.com/install.sh | sh

Setup

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

lean-ctx setup

Done. It's automatic

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

Even forgetting is a decision.

When the session cache is full, LeanCTX automatically decides what to keep and what to evict. It ranks entries by recency, frequency, and size: then fuses these signals into a single score. No tuning required.

How caching works

Want to understand the architecture?

Explore the Cognitive Context Layer: the six-step pipeline, integration modes, agent matrix, Context Field Theory, and nine architectural pillars that make LeanCTX work.

Deep dive into the Architecture

Security

Guards what they touch.

LeanCTX 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.

[##]

Shell Allowlist + AST Parsing - When configured, every segment of compound commands (pipes, chains) is validated against the allowlist. Dangerous patterns (eval, backticks, $()) are blocked unconditionally. Output capped at 200KB.

[]

Safe file access - File reads can't be tricked into following symlinks out of your project, and the local proxy only ever talks to your own machine.

[ok]

Build Integrity - Compile-time integrity seed and hash verification detect tampered binaries. Checked automatically by lean-ctx doctor.

Security & Trust Details →

FAQ

How it works, answered.

What is LeanCTX?

LeanCTX (short for Lean Context) is the open-source context intelligence layer for AI agents. One local Rust binary sits between your AI tool (Cursor, Claude Code, GitHub Copilot, and more) and the LLM. It decides what agents read, remembers what they learn, guards what they touch, and proves what they save — with savings of 60–90% per read as the receipt.

Does compression hurt code quality?

No. LeanCTX uses tree-sitter AST parsing to understand code structure, then strips only what the LLM doesn't need: redundant whitespace, boilerplate imports, and decorative comments. On average, 98% of AST structure, 97% of identifiers, and 96% of meaningful code lines are preserved. You can verify this with lean-ctx benchmark run.

How do I install LeanCTX?

Install via cargo install lean-ctx or curl -fsSL https://leanctx.com/install.sh | sh. Then run lean-ctx init for the shell hook and lean-ctx setup to connect with your AI tools. Zero configuration required.

Which AI tools does LeanCTX support?

LeanCTX works with every major AI coding tool: Cursor, GitHub Copilot, Claude Code, Windsurf, Cline, OpenAI Codex, Gemini CLI, Antigravity, Pi, Crush, Zed, Continue, and OpenCode. All tools benefit from both the context server and shell hook compression.

Get started

Sixty seconds to smarter agents.

One binary. Zero cloud dependencies. Apache-2.0. Your next session reads leaner, and the ledger keeps the receipt.

Get Started Check Compatibility

How LeanCTX controls whatyour AI sees.

Where does LeanCTX sit?

You

AI Tool

LeanCTX

LLM

One binary. Five capabilities.

Five things LeanCTX does to every token.

Perceive

Compress

Remember

Route

Govern

What do YOU actually do?

Install

Setup

Done. It's automatic

Even forgetting is a decision.

Want to understand the architecture?

Guards what they touch.

How it works, answered.

Sixty seconds to smarter agents.

How LeanCTX controls what
your AI sees.