LeanCTX Context Intelligence
A local context layer that controls, compresses, remembers, and measures what coding agents send to models.
- Source repo
- yvgude/lean-ctx
- Stars
- ★ 3.9k
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Rust
- FA score
- 75/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code · OpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- Developers who use Cursor, Claude Code, or Codex every day and frequently run git, test, and build commands can use hybrid mode to reduce repeated reads and noisy terminal output.
- Not a fit if
- Users in tiny repos who rarely call the shell from their AI tool
- Workflows that always need raw, unfiltered logs; --raw lowers the payoff
- Teams unwilling to change local agent config and install shell, MCP, hook, and daemon components
- Source review
- 75/100 · Good
What does this agent do, and when should you use it?
LeanCTX is a local-first context engineering layer for AI coding agents, delivered as a single Rust binary with an MCP server, shell hooks, an optional request proxy, session memory, a code graph, and a browser dashboard. It compresses repository reads, common development-command output, and—when the proxy is enabled—the requests sent to model providers, while retaining pruned material in content-addressed storage for recovery. Ten read modes and Tree-sitter support for 27 languages provide structural views, while a multi-edge property graph supports search, impact analysis, and related-file discovery. The product also records tokens, cost, accepted outcomes, and CPAO through Shadow Mode, an auditable savings ledger, context proofs, and reporting commands. It supports more than 30 coding agents and exposes Python, TypeScript/Node, and Rust SDK or client options; code, memory, and telemetry remain local by default unless the user enables an external capability.
On the read path, a coding agent reaches LeanCTX through ctx_* MCP tools or shell commands. lean-ctx read can return full, map, signatures, diff, lines:N-M, density:X, and other views, while shell hooks condense output from git, npm, cargo, docker, kubectl, terraform, and other recognized commands. Tree-sitter analysis, ModePredictor, and IntentEngine extract structure, select read depth, and classify task complexity; omitted bytes are stored under deterministic handles and can be recovered with ctx_expand, ctx_retrieve, or /v1/references/{id}. Session memory, a temporal knowledge graph, and a multi-edge property graph retain tasks, facts, decisions, and code relationships for cross-chat recall, hybrid search, and lean-ctx graph impact. On the optional wire path, lean-ctx proxy enable places a local proxy between the agent and OpenAI, Anthropic, or Gemini and compresses system prompts, history, and tool results. lean-ctx gain, savings, value-report, shadow, and the Context Manager dashboard produce token, dollar-cost, CPAO, quality, and baseline-comparison reports; ctx_proof and ctx_verify add four-layer verification and CI drift gates. Multi-agent work is supported through ctx_agent, ctx_handoff, shared state, portable .ctxpkg bundles, signed snapshots, and an addon gateway for upstream MCP servers.
- Developers who use Cursor, Claude Code, or Codex every day and frequently run git, test, and build commands can use hybrid mode to reduce repeated reads and noisy terminal output.
- Teams maintaining medium-to-large repositories or monorepos can use AST signatures, hybrid search, the property graph, and
graph impactto inspect APIs and estimate change blast radius. - Engineers carrying a refactor or investigation across multiple chats can persist tasks, facts, and decisions in local session memory and the knowledge graph.
- Organizations switching among OpenAI, Anthropic, and Gemini can retain a portable local cache and memory layer while enabling the request proxy only where appropriate.
- Engineering leads who need evidence of AI return on cost can inspect CPAO, the verified savings ledger, Shadow Mode comparisons, benchmarks, and live dashboards.
- Teams coordinating planner, developer, and reviewer agents can use
ctx_agent,ctx_handoff, diaries, shared state, and context-transfer bundles for deterministic handoffs.
How do you install or deploy this agent?
Choose one documented installation route:
curl -fsSL https://leanctx.com/install.sh | sh
brew tap yvgude/lean-ctx && brew install lean-ctx
npm install -g lean-ctx-bin
cargo install lean-ctx
pi install npm:pi-lean-ctxThen configure a supported agent with one command, for example:
lean-ctx wrap cursor
lean-ctx wrap claude
lean-ctx wrap codex
lean-ctx wrap vscodewrap installs shell hooks, registers the MCP server, configures agent hooks, starts the daemon, and verifies the connection. lean-ctx onboard can connect all detected tools without prompts, while lean-ctx setup provides an interactive wizard. For a Windows source build, clone the repository and run ./install.ps1 in PowerShell; add -BuildOnly to avoid installation. No credential is documented for the basic local layer. Enabling model proxying, cloud sync, public-web ingestion, or external providers requires access to the corresponding network service.
How do you use this agent?
After wrapping the agent, run lean-ctx doctor to verify the integration. Initial working commands include:
lean-ctx read src/server.rs -m map
lean-ctx -c "git status"
lean-ctx overview
lean-ctx graph impact src/auth.rs
lean-ctx gain --live
lean-ctx dashboardRun lean-ctx proxy enable if every request sent to the model should pass through the local compression proxy. For baseline savings analysis, add [shadow] and enabled = true to ~/.config/lean-ctx/config.toml, use LeanCTX for a while, then run lean-ctx savings and lean-ctx shadow --latest. Application integrations can start lean-ctx serve and call /v1/tools/call or use lean-ctx-client. For message-array compression only, install lean-ctx-sdk and call Python's compress(messages, model="claude-sonnet-4") or TypeScript's compress(messages, { model: "gpt-4o" }).
What are this agent's strengths and limitations?
- One local Rust binary combines MCP reads, shell-output compression, an optional request proxy, memory, graph intelligence, and cost observability instead of requiring a separate product for each layer.
- Compression has explicit recovery paths: pruned content is moved into content-addressed storage and can be retrieved through tools, in-band handles, or an HTTP reference endpoint.
- More than 30 coding agents are documented, alongside standard MCP, an HTTP
/v1API, Python and TypeScript compression SDKs, and Python, TypeScript, and Rust clients. - Cost and quality measurement is unusually concrete: real-time token and dollar reporting, CPAO, Shadow Mode, an auditable event ledger, reproducible benchmark commands, and CI quality gates are all described.
- Telemetry is off by default, memory and caches are local and portable, and
.ctxpkgpackages plus signed snapshots reduce dependence on one model provider.
- The payoff depends on how much of the context window LeanCTX can reach, whether sessions are long-lived, and how the provider prices prompt caching; the documented matrix says unfavorable combinations may only break even.
- Users of tiny repositories, workflows with little shell activity, or processes that always require raw logs are explicitly described as poor fits;
--rawexists but reduces the benefit. - Full integration changes local agent configuration and installs shell, MCP, hook, and daemon components, which teams must assess against their existing development environment.
- Request proxying, cloud sync, public-web reads, addon installation, and model calls introduce network or third-party boundaries beyond the otherwise local-first workflow.
- Several team-scale capabilities remain roadmap items, including hosted
ctxpkg.comhistory, the broader unified context graph, and fuller OpenTelemetry or Prometheus export.
How does this agent compare with similar options?
The project positions LeanCTX as a layer spanning both the agent read path and the model request path, and names RTK, Context+, and MemGPT in its comparison documentation. It can also host tools such as Headroom, Sophon, Repomix, Serena, Mem0, Cognee, Letta, and Sequential Thinking as addons, then compress, archive, index, and mark their output as untrusted. Those products may therefore overlap with individual LeanCTX capabilities or operate behind its gateway; the supplied material does not provide enough comparative evidence to claim item-by-item superiority.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| LeanCTX Context Intelligence This agent | 75 · Good | CLIFree + model costs | ★ 3.9k | today | Rust | Codex · Claude Code · OpenAI API · Claude API |
| Entroly | 68 · Some gaps | CLIFree + model costs | ★ 479 | 1d ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| Happier | 82 · Good | Desktop appFree + model costs | ★ 2k | today | TypeScript | Codex · Claude Code |
| Tokless | 57 · Major gaps | CLIFree | ★ 293 | today | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence shows default project path jailing, secret-path denial, workspace-trust gating, role permissions, and local audit events. Telemetry is opt-in, the proxy is disabled by default and loopback-bound, and update checks, model downloads, and proxy flows are disclosed; sensitive-data handling and data-flow transparency are therefore thorough. Shell, cloud commands, and high-risk tools can be denied, but an authorized ctx_execute has full user-level shell reach, onboarding may operate without prompts, and project configuration, proxies, and addons enlarge the attack surface, so least privilege, confirmation, and external-effects handling do not receive full marks. Unwrap, immediate disablement, content recovery, and snapshot restoration are described, but there is no uniform transactional rollback for configuration changes, command side effects, or addon installation, so rollback is 2. Dependency auditing, cargo deny, checksums, and pinning are described and partly supported by workflow evidence, but no lockfile, audit output, or current vulnerability inventory is supplied, and HuggingFace models lack cryptographic pinning; dependency security is 2. The repository owner, license copyright holder, and security contact are clear, but enterprise publisher identity is unverified and broader organizational provenance is not established, so attribution is 2.
The README, security policy, and tests jointly support the local client, HTTP tool manifests, adapter conversion, error parsing, and helpful ImportErrors for optional dependencies. Live tests also define a manifest-drift gate, but require an environment URL and optional frameworks, so dependency availability and failure messages score 2. Self-consistency scores 1: the README says 79 MCP tools while the object description says 76, and the security document's claim of 29 dependencies and limited network use sits uneasily beside extensive server, proxy, model-download, and ecosystem functionality. “Local-only” also requires numerous later qualifications. The static material does not establish that all broad claims are synchronized at this revision.
The material gives concrete journeys for onboarding, daily coding, memory, code comprehension, multi-repository work, lifecycle operations, and regulated deployments, spanning many agents, models, and SDKs; audience and scenarios are thorough. Capability boundaries are unusually explicit about PathJail, roles, the differing constraints of ctx_shell and ctx_execute, the proxy's MITM role, and the absence of kernel sandboxing, earning 3. Activation offers agents-only mode, wrap commands, explicit proxy enablement, and workspace trust, but zero-prompt onboarding, transparent shell hooks, and automatically merged configuration can make some triggers less conspicuous, so trigger precision is 2. Multiple platforms and installation channels are covered, with Windows residual risks and container mitigations disclosed, but production TLS, external models, optional frameworks, and package-manager requirements create environment prerequisites, so environment fit is 2.
The README has strong navigation, capability sections, quick starts, scenarios, SDK examples, troubleshooting, and reference pointers, supporting full marks for architecture, installation notes, and examples. SECURITY thoroughly records residual risks, mitigations, and regulated-environment configurations, so known limitations earns 3. The complete Apache-2.0 text, copyright notice, and README label agree, earning 3 for license. Naming is generally stable and the client tests expose a contract version, but “AI Value Gate/Lean Context,” the 76/79 tool-count drift, and changing version examples show terminology and inventory drift, so naming stability is 2. A changelog is linked and version changes plus a last-updated date are noted, but the changelog itself and a compatibility policy are absent from the supplied evidence, so versioning is 2. A security email, private-advisory route, response target, and copyright holder are identified, but publisher identity remains unknown and no formal support entity or redundancy is shown, so maintenance responsibility is 2.
Commands, SDK examples, diagnostics, dashboards, recovery handles, and structured HTTP errors make outputs directly actionable, so output usability earns 3. Compression, caching, recoverability, graph search, memory, and cost ledgers offer plausible value beyond ordinary agent tooling, but the supplied code evidence covers only Python clients and adapters rather than the core 79-tool implementation, so marginal value is 2. The source states 50–80% savings, approximately 13-token rereads, a benchmark workflow, and CPAO/Shadow Mode, but supplies no revision-specific benchmark report or raw results and does not quantify setup, governance, or compression-error costs; cost-benefit is therefore 2.
Many claims point to repository security material, reproducible demo tapes, reference documentation, CI, and benchmark commands, while tests concretely cover HTTP forwarding, error parsing, adapters, and manifest equality. This supports scores of 2 for traceability and cross-source corroboration. The supplied evidence lacks core implementation files, benchmark artifacts, lockfiles, and CI results, so broad features and percentage claims cannot be closed-loop verified statically. Fact/inference separation scores 1 because marketing statements such as “definitively a false positive,” “never discards,” “quality held,” and “zero config” are categorical and are not consistently distinguished nearby from measured results, design intentions, or roadmap projections.
- ctx_execute is not constrained by the ctx_shell allowlist; any agent allowed to call it has full shell reach under the invoking user's privileges. Disable it by role and use an OS-level sandbox in high-risk settings.
- The optional LLM proxy reads request bodies and plaintext Authorization headers. Keep it disabled unless needed and bind it only to loopback.
- HuggingFace embedding-model downloads are not cryptographically hash-pinned; regulated deployments should pre-provision models from a verified internal mirror.
- Windows retains a PathJail check-to-use race and relies on the user profile's NTFS ACLs. Use container or VM isolation on shared or adversarial hosts.
- Do not base adoption solely on the README's 50–80% savings, approximately 13-token rereads, or 79-tool claim; the supplied material contains no corresponding benchmark artifact, core implementation, or executed result.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
A bugfix release: tool calls that an agent gets almost right are now served instead of refused, edits survive indentation slips, and the Claude Code plugin wakes the agent only once per finished background job. Agent Tools protocol and data formats are unchanged. Fixed - Searching a broad directory searches the project instead of failing. ctx_search, ctx_glob and ctx_tree called on ~, / or another directory that contains the session's project now walk the project and say so in the first line of the result. Before, they answered "refusing to scan" and agents repeated the sam …View on GitHub ↗ -
Release notes excerpt
PathJail opens the home directory by default, the gateway keeps downstream MCP sessions alive between calls, Windows updates and CUDA 13 GPU embeddings work, and Claude Code gets a gateway cockpit. Agent Tools protocol and data formats are unchanged. Changed - PathJail opens your whole home directory by default. The default path_jail_scope = home now admits everything below ~ for reading and writing; before, it admitted only paths inside a project, read-only outside the session's project. Protected locations stay closed: every top-level dot entry (~/.ssh, ~/.aws, ~/.config, …View on GitHub ↗ -
Release notes excerpt
Updater and security hotfix for 3.11.1. Agent Tools protocol, configuration and data formats are unchanged. Upgrade notes - Updating from 3.11.0 or 3.11.1 needs one manual step. Their built-in updater stops after downloading and verifying a release with Failed to complete durable update transaction: prepared transaction is missing its integrity digest, and scheduled automatic updates fail the same way. Nothing is changed or damaged: the installed binary keeps running. Install this release once through the channel you installed with — curl -fsSL https://leanctx.com/install.sh | sh …View on GitHub ↗
FAQ
Does local use cost money or send telemetry by default?
Can compression permanently hide code or logs?
ctx_expand, ctx_retrieve, in-band markers, and the HTTP reference endpoint. Teams should still validate that compressed views meet their diagnostic and audit requirements.Is it tied to one model provider or editor?
How can I bypass compression during a failure investigation?
lean-ctx -c --raw "git status" for one uncompressed command, lean-ctx-off to disable it in the current shell, and lean-ctx doctor --json to produce shareable diagnostics.Can it be removed cleanly?
lean-ctx uninstall --dry-run to preview changes, then lean-ctx uninstall to remove processes, hooks, editor configuration, rules, autostart entries, data, and the binary. Package-manager installations also require the matching brew, cargo, npm, or Pi uninstall command.