LeanCTX: a local Rust binary that gates what your coding agent reads

The problem LeanCTX targets: agents that re-read the same file every turn

An AI coding agent burns most of its context window on material it has already seen. The README puts a number on it: a repeated file read costs roughly 2000 tokens each time, and a raw `git status` costs about 800. Those numbers are the project's own, not an independent measurement, but the mechanism they describe is familiar to anyone who has watched an agent re-open the same module three turns in a row.

The audience is narrow and specific. LeanCTX is for people running long, multi-turn coding sessions against a repository large enough that file reads dominate the prompt. It is not a model, not an editor, and not a chat client. It is a layer that sits alongside whichever agent you already use, and the README lists Cursor, Claude Code, Copilot, Windsurf, Codex and Gemini among the supported clients, with a claim of 30+ agents in total. If your sessions are short one-shot prompts, there is nothing here to amortise and the layer is pure overhead.

How the context gate works: read modes, AST parsing and a content-addressed store

The mechanism has four moving parts. First, task triage: LeanCTX classifies what the agent is trying to do and picks a depth of disclosure rather than dumping whole files. Second, read modes. The README documents ten, including `full`, `map`, `signatures`, `diff`, `lines:N-M` and `density:X`. The `signatures` mode is the interesting one: it carries line spans and points at `lines:N-M` so the agent can expand a specific body on demand. Outline first, bodies later. `density:0.4` is a different idea, keeping the highest-entropy lines until roughly 40 percent of the original token count remains, and the README describes the result as deterministic.

Third, structural parsing. Tree-sitter AST support covers 27 languages, so compression operates on syntax rather than on text patterns. Fourth, shell output. The README claims 95+ shell-output patterns covering git, npm, cargo, docker, kubectl and terraform, with 270 passthrough rules for output that should not be touched.

The part worth scrutinising is reversibility. The README states that compression never discards content: pruned or truncated payloads move into a content-addressed store with a deterministic handle, and the model can pull the original bytes back through `ctx_expand`, `ctx_retrieve`, an in-band marker, or `GET /v1/references/{id}`. That is five recovery paths, and it is the difference between a lossy summariser and a cache. Whether it holds up in practice depends on whether the agent actually issues the expansion call when it needs the full file, which is an agent-behaviour question, not a LeanCTX question.

Installing LeanCTX and running the first setup against your agent

The repository ships `install.sh` and `install.ps1` at the top level, and the README's install section is anchored as "Get started in 30 seconds". The Makefile shows the path the maintainers use for a release build, installing into `~/.local`:

cd rust && cargo install --path . --force --locked --root "$HOME/.local"
lean-ctx --version

The `--locked` flag matters here because it pins dependency resolution to the committed lockfile. After installation the binary lands in `$HOME/.local/bin`, so that directory needs to be on your `PATH` for the version check to resolve.

The README says setup is one command with no config changes required:

lean-ctx setup

What you should see is LeanCTX detecting your installed agent and wiring itself in. The repository layout supports that expectation: there are checked-in configuration directories for several clients, including `.claude-plugin/`, `.codex/`, `.cursor/`, `.kiro/`, `.windsurfrules`, `.clinerules` and `.vscode/`. That is a concrete signal about which integrations are first-class rather than aspirational.

For a first real use, point it at the repository you actually work in and watch the dashboard the README describes. The claim to check is the cached re-read: roughly 13 tokens for a file already seen, against about 2000 for a fresh read. If that gap does not appear on your own files, the compression is not engaging and the rest of the layer will not pay for itself.

If you prefer building from source for development, the Makefile has a `dev` target:

make dev

The Makefile comment explains why it removes the existing binary before copying: overwriting a Mach-O in place invalidates the ad-hoc code signature on Apple Silicon, and the copied binary then dies with SIGKILL (exit 137) on every exec. The target re-signs ad hoc where `codesign` exists. That is a real platform detail, and it is the kind of thing that costs an afternoon if you hit it without the comment.

Where LeanCTX is the wrong tool

The compression ratios are the project's own, and the README itself scopes them: 50 to 80 percent fewer tokens "where compression applies", with the headline table saying 60 to 90 percent in the repository description. Those two ranges do not match each other, and neither has been independently verified. Treat both as marketing envelopes until you have measured your own repository.

The 270 passthrough rules are the honest part of the design, because they admit that some shell output must not be compressed. But that also means the benefit is uneven. A repository dominated by large binary assets, generated code, or languages outside the 27 with tree-sitter support will see far less than the headline number. The README does not publish a per-language breakdown, only that a benchmark exists to measure compression by language and mode.

There is a second boundary. LeanCTX is local-first and runs as a binary alongside your agent, which means your agent's file reads and shell commands now pass through an additional process. If your threat model requires a formally audited boundary between the agent and the filesystem, this is a new component in that path, not a reduction of it. The repository does carry a `SECURITY.md` and a `security/` directory, but the README does not describe a third-party audit.

Finally, if your prompts are short and your repository is small, the triage and caching machinery has nothing to work on. The overhead is a binary in the loop and a setup step, against savings that will not materialise.

LeanCTX against a plain context-compression proxy

The most direct comparison in the README is with Headroom, and it links a page titled `docs/comparisons/vs-headroom.md` whose anchor is about reversibility. That anchor is the whole argument. A conventional compression proxy rewrites the request and sends less; the original is gone from the prompt, and if the model needed a line that got pruned, it has to ask for the file again. LeanCTX's claim is that pruned payloads land in a content-addressed store with a deterministic handle, so the model can retrieve the exact original bytes through `ctx_expand`, `ctx_retrieve`, an in-band marker, or `GET /v1/references/{id}`.

That is a meaningful architectural difference, not a feature-list difference. It changes compression from a lossy transform into a cache with eviction, and it is what makes aggressive `density:0.4` compression defensible. The cost is state: a content-addressed store has to be managed, and the recovery path only helps if the agent takes it.

The second axis of difference is memory. The README contrasts LeanCTX with vendor-hosted context features that keep your memory in a black box, and describes LeanCTX as model-agnostic with context portable via `.ctxpkg`. If you switch between OpenAI, Anthropic and Gemini, that portability is the practical distinction. If you are committed to a single vendor and its hosted memory already works for you, the portability argument is worth less than the compression argument.

Maintenance, licence and what an upgrade actually costs

The last push to the default branch was on 2026-08-26, and the most recent release, v3.9.20, carries the same timestamp. The two prior releases landed on 2026-08-18 and 2026-08-08. That is a steady release cadence over the visible window, and the repository is not archived. The version numbering, at 3.9.x, suggests a project that has been through a lot of iteration.

The upgrade cost is concentrated in two places. The compression rules are versioned behaviour: 95+ shell-output patterns and 270 passthrough rules mean that a release can change what your agent sees for a given command, and a passthrough rule that flips to compressed can alter agent behaviour without any change on your side. The repository keeps a `CHANGELOG.md` and a `DEPRECATIONS.toml`, which is where to look before bumping. The second cost is the integration surface: with configuration directories checked in for Claude Code, Codex, Cursor, Kiro, Cline and Windsurf, an upstream client changing its plugin or rules format is a LeanCTX release, not yours.

On licensing, the repository is Apache-2.0, with a `NOTICE` file and a separate `CLA.md` for contributions. Apache-2.0 includes an express patent grant and requires that you preserve the `NOTICE` file when redistributing. If you vendor the binary or embed it in a product, read `NOTICE` and `LICENSE` yourself; this is a description of what is in the repository, not legal advice.

Editorial conclusion

Adopt LeanCTX if you run long agent sessions against a large repository and your token bill is the constraint, and you are willing to route agent file reads and shell commands through a proxy binary. Do not adopt it if you need a formally audited security boundary, or if your workflow is short one-off prompts where compression has nothing to amortise against. Before committing, verify three things yourself: that `lean-ctx setup` detects your agent, that a cached re-read actually returns the ~13 tokens the README claims, and that the content-addressed store's `ctx_expand` path returns original bytes for the file types you care about.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes