On the command line this looks unremarkable:

The documentation shows the same file in different modes, and the difference is more telling than any percentage. A 66-line file in map mode:

The @L3-55 markers are not decoration. Having seen the map, the model knows where to go back for a function body and can request exactly that range. And auto is not guessing blindly: the project keeps statistics on past decisions and learns which mode works best on which file.

Reading the same file twice

The second idea is simpler than the first. Over a long session an agent keeps returning to the same places - package.json, a config, a central service, a module entry point. Every time, that is the full text again.

LeanCTX keeps a session cache. If the file has not changed, a repeat read returns not the content but a compact reference to context already known. The project quotes the cost of such a reference at roughly thirteen tokens, against thousands for the full file.

That number is the project's own figure, not a guarantee from any provider. But the direction is right: over a session lasting hours, repeat reads account for a noticeable share of the spend, and that is precisely the case where compression is beside the point - you simply should not send the same thing twice.

A tree instead of text

The map and signatures modes do not work through line-by-line heuristics but by parsing a syntax tree with tree-sitter. That is why "keep only the API" means the actual API rather than the first N lines.

And here is the first documentation discrepancy, of which this project has many. The current README claims support for twenty-seven languages, while the agent skill bundled into the repository and the benchmark file both say twenty-six. Not a critical error, but a telling one: in places the prose trails the code.

Shell output compression comes bundled

Worth its own note is that the job of a dedicated terminal filter is handled here in passing. LeanCTX has its own shell interception and, per the README, more than ninety-five output compression patterns for git, npm, cargo, docker, kubectl, terraform and the rest, plus two hundred and seventy passthrough rules.

Which leads to a practical consequence worth thinking about before installing: if you already run RTK, do not keep two interceptors on the same output. It will not double the savings, but it will double the number of places where you have to work out why the output does not look the way you expected.

There are emergency exits for when compression gets in the way: lean-ctx-off disables interception in the current shell, --raw covers a single call, and the shell_activation = "agents-only" setting confines interception to agent sessions, leaving your own terminal untouched.

Two paths: the read and the wire

The README describes two independent routes, and they should not be conflated, because the meaning of every percentage depends on which one is active.

The first works as soon as you connect: read modes, cache, search, command output compression, memory. The second is a separate local proxy, enabled by hand, which compresses the request itself - system prompt, conversation history, tool results.

The proxy is the most powerful and the most invasive part of the project. A single proxy enable writes *_BASE_URL exports into your shell configuration file, edits ~/.claude/settings.json and the Codex config, and installs an autostart service on macOS or a user systemd unit on Linux. The documentation warns about this itself: if a base URL "defaults to the wrong provider" after enabling, those exported variables are where to look.

In other words, before the proxy this is a utility working alongside your repository. After it, an infrastructure intermediary in front of your model provider. That decision deserves to be made separately and deliberately, not as part of "install and forget".

Shadow mode: the agent is left no choice

There is one setting that explains why the project's savings figures run higher than you might expect - and explains part of its risk profile at the same time.

The problem is obvious: if the agent has its own reading and searching tools, it can keep using them and every read mode stays unused. LeanCTX solves this bluntly - shadow mode denies the native tools at the permission level, forcing the agent through ctx_*. Since version 3.9.9 this is the default, and 3.9.10 added a one-time migration for earlier installs. The changelog also gives the reasoning: per community feedback, over sixty percent of the savings came from ctx_read alone when the mode was on.

The flip side turned up exactly where you would expect it. Release 3.9.18 lists under security: commands redirected in shadow mode now honour the environment's permission rules - previously the redirect path bypassed them. Which means a setting like "rm *": "ask" could, for a while, fail to fire on commands that went through the redirect.

Fixed, and good. But it is precisely the class of problem that appears in any layer inserted between an agent and its tools. The more transparent the interception, the more it matters that safety rules survive it intact.

How many tools are there - three different answers

This is my favourite finding in the project, and it illustrates its state well.

How many MCP tools does LeanCTX have? Depends where you ask.

And the 3.9.18 changelog literally contains the line "tool count updated from 82 to 83 across all documentation" - while the README and the reference still say 79. In itself this is trivia and breaks nothing. But it is an exact snapshot of the project's pace: releases ship almost continuously, and the prose does not keep up with the code.

The practical takeaway for a reader: with this project, verify any specific number against the current release rather than the first repository file you open.

Its own toolset costs tokens too

Eight dozen MCP tools are not only capability. Every tool's schema occupies space in the context before the agent has done anything at all.

The project knows this and ships profiles.

The minimal profile carries five tools: read, shell, search, glob and directory tree. The reference states the principle outright: fewer tools mean less per-call and schema overhead. The project optimises even the cost of its own presence in the model's window, which is an honest sign that surface size is recognised here as a problem.

Memory across chats, and search instead of walking the repo

Two subsystems that formally have nothing to do with compression, and everything to do with savings.

The first is memory. Tasks, findings and decisions can be persisted across sessions so the next chat does not start by reading a dozen files again.

The second is search. Instead of walking the repository in sequence, the project builds a BM25 index and a code graph with relations such as imports, calls and type references, then hands the model a small selection of files - and reads that selection in a suitable mode.

The logic in both cases is the same, and it runs through the whole project: do not compress the surplus, do not produce it.

On top of that sits a window management layer - you can pin an important file, exclude a vendor directory, see what is occupying the window, and evict what has gone stale.

This is the point where the term "context engineering" stops being marketing: the subject is no longer an archiver for prompts but a policy for what is entitled to occupy a limited window.

What the project's own benchmarks show

There is a benchmark file in the repository, and it needs careful reading - starting with the header.

The measurements were generated by version 3.8.18 on 2 July 2026, which makes them older than the current release. Fifty files from the project's own repository were measured, 533 thousand tokens in total, counted with the o200k_base tokenizer, latency by wall clock, quality by the project's own preservation score.

The table is more interesting than it looks, but not for the reason it usually gets quoted. It shows that the modes solve different problems rather than competing on a percentage. signatures shrinks a file nearly thirtyfold because it deliberately keeps only the external interface - that is not "compression without loss of meaning", it is a different representation for a different job. Meanwhile entropy and aggressive gave almost nothing on this set of files, and the project does not hide that result.

The discipline of the competitor comparison deserves a separate mention. The same file carries a table against Repomix, aider and others, and it says plainly: the LeanCTX numbers were measured, the competitors' numbers come from their published documentation. Plus a disclaimer that a different test repository will produce different results, and a command to reproduce it on your own code:

The file also contains a thirty-minute session simulation showing 88.1% savings. That is the project's simulation on its own repository, not anybody's invoice.

How to read "60-90%"

Here is where it gets interesting, because different parts of the project quote different numbers.

The repository description on GitHub promises "60-90% fewer tokens". The README, in its list of benefits, is more careful - "50-80% fewer tokens on reads and shell output". The agent skill says "up to 99%". These describe different things: the last refers to one file representation, the first to an end-to-end effect.

But the most valuable thing in the README is not the figure, it is the paragraph next to it. The project honestly lists the three levers the result depends on: reach (does LeanCTX own the window through the proxy, or only the tool layer), context lifetime (one long-lived session versus a fresh process per phase), and provider pricing (a cacheable prefix versus a full re-bill every turn). Then comes a sentence you rarely see in a README: where the levers line up, a clear win; where they do not, it nets out to break-even.

That last line matters too. If a compressed representation made the model take an extra turn to fetch the details, part of the saving goes straight back.

Installation and setup

There are five installation routes, all equally valid:

Then one command per agent:

wrap installs shell hooks, registers the MCP server, sets up the agent hooks, starts the daemon and verifies the connection. Undo it with lean-ctx unwrap. For those who want control there is lean-ctx onboard to connect every detected tool and lean-ctx setup with the full set of questions.

The compatibility matrix in the README lists thirty-three agents across two modes. Hybrid means MCP plus shell interception, and it goes to anything with shell access: Cursor, Claude Code, Codex CLI, Gemini CLI, Windsurf, GitHub Copilot, OpenCode, Hermes, Cline, Roo Code, Antigravity, Amazon Q and others. Pure MCP is for clients without reliable command interception: Aider, Mistral Vibe, Continue, JetBrains, VS Code, Zed, Neovim, Emacs, Sublime Text. And a separate note: any MCP-compatible client can connect without first-class support, just manually.

Measurement: gain, savings, ghost, discover

As with RTK, your own statistics beat the marketing figure, but here the toolkit is noticeably wider.

savings deserves singling out. The README describes it as a per-event ledger with tokenizer transparency, bounce-netting and a tamper-evident SHA-256 chain, local-only and on by default. That is no longer "show me a nice percentage" but an attempt to make savings a verifiable quantity - rare discipline for this class of tool.

And ghost and discover close a question that is easy to miss: not how well the compression works, but what share of the work went past it. A filter with an excellent ratio is worthless if the agent bypasses it half the time.

Security: very close to your files

LeanCTX reads the filesystem, runs shell commands, stores state, edits agent configuration files, starts an MCP server and, on request, a proxy. That calls for a more serious posture than a prompt plugin deserves, and to the project's credit it has written a twenty-kilobyte document on the subject.

The threat model lists: accidental exfiltration of secrets to the model through reads, search, compressed command output and archives; boundary escapes via absolute paths, symlinks and artifact path tricks; token burn from scanning enormous files; denial of service through user-supplied regular expressions; cross-workspace access in team deployments.

The defences are described just as concretely: path jailing around the project root plus an explicit list of allowed roots, blocking reads of secret-like paths such as .env and SSH keys by default, working-directory checks for shell commands, deterministic redaction in output and in persisted archives, hard caps on read and output size, limits on regular expression length and complexity, tenant isolation on the team server.

A separate table enumerates all network activity and how to switch it off: the daily update check, the optional anonymous telemetry, the embedding model download, the local dashboard and the daemon socket. Every row with a "how to disable" column is the right format for a local tool.

And one last discrepancy, typical for this project. The frequently-asked-questions file still claims "Zero telemetry", while the current security policy describes telemetry as opt-in and off by default: when explicitly enabled, a daily heartbeat sends the version, OS, architecture, a random installation identifier and anonymised compression characteristics - no code, no filenames, no personal data.

The correct phrasing as of August 2026: telemetry exists, is off by default, and is turned on by hand. "Zero telemetry" is a stale line, not a description of behaviour.

What was double-checked

How LeanCTX differs from its neighbours

Curiously, the LeanCTX README states the overlap itself: of its own proxy it says this is the same layer as a standalone request-compression proxy such as Headroom, and you do not need one on top. An ambitious claim, but at least an honest one - the project does not pretend to coexist peacefully with everything.

The practical conclusion from the table is simple. If only the terminal is noisy, RTK is narrower and easier to debug. If what you want is a request compression layer, Headroom does not drag a platform along with it. If the work runs for hours in a large repository and the agent keeps re-reading the same things - that is when LeanCTX starts paying for its complexity. Installing all of them at once for a maximum percentage is a bad idea: two proxies or two shell interceptors will not double the savings, but they will certainly complicate the debugging.

Where to start

An order that lets you understand the benefit without turning token optimisation into a separate infrastructure project:

1. Install it and connect one agent with wrap.
2. Leave the proxy off for now - work on the read cache and command output compression.
3. Optimise nothing in particular for a few days.
4. Look at lean-ctx gain --deep, lean-ctx ghost, lean-ctx discover, lean-ctx doctor.
5. Work out where your spend actually comes from: repeat reads, the terminal, or conversation history.
6. Only then decide whether you need the proxy, the memory, and the power profile.

The order is not arbitrary. Each additional layer adds both benefit and debugging surface, and the only way to know which one you need is your own numbers.

Conclusion

The problem of saving tokens has several different answers. RTK says: do not send the model your terminal noise. Headroom: compress the context before sending it. pxpipe: some text is cheaper to deliver through vision. LeanCTX: first decide which context deserves to enter the window at all.

The most valuable thing about LeanCTX is not the peak compression percentage. Stronger is the chain: find the right files by search, read them structurally, cache them, return a delta the second time, collapse command output, replace anything oversized with a reference, carry the task across chats. Savings arise at every step, before you ever have to fight an overflowing window.

The conclusion, reduced to one thought: there is no magic compressor. Work out where the surplus tokens in your workflow come from - the terminal, repeat file reads, enormous tool results, or conversation history - and take the narrowest tool that solves that particular problem. A tool that solves all four charges you in complexity, and paying that is only worth it when you genuinely have all four problems.

Sources

The material was verified on 13 August 2026 against the current yvgude/lean-ctx repository and the documentation inside it. The version and metadata were checked against the package manifest and the GitHub API; discrepancies between the README, the bundled skill, the benchmark file, the changelog and the repository description were not smoothed over but collected in a separate table. Supplemented on 15 August 2026 against a fresh clone: the three tool counts, the language-count mismatch, the shadow-mode version history and the figures for 95+ patterns and 270 passthrough rules were re-checked and held; and it is now stated that the ten read modes are the README's number, while the code carries more.

• GitHub - yvgude/lean-ctx
• Releases - v3.9.18
• README - modes, integrations, the honest fine print on levers
• CHANGELOG - shadow mode, tool count, fixes
• SECURITY.md - threat model, network surface, telemetry
• BENCHMARKS.md - methodology and per-mode measurements
• Daily use - read modes and output compression
• Advanced and integrations - the proxy
• Context engineering and observability
• Analytics - gain, savings, ghost, discover
• MCP tool reference
• The bundled agent skill
• FAQ - an example of the stale telemetry line