Skip to content
Back to search

lean-ctx

LeanCTX — Context Intelligence for AI systems.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/yvgude/lean-ctx with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/yvgude/lean-ctx'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/yvgude--lean-ctx/badge.svg)](/listings/yvgude--lean-ctx)

HTML

<a href="/listings/yvgude--lean-ctx"><img src="/api/listings/yvgude--lean-ctx/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Enable shadow mode for savings comparison
lean-ctx config set shadow.enabled true

# After using LeanCTX for a while:
lean-ctx savings
lean-ctx shadow --latest

<details> <summary><strong>Full feature list (complete MCP tool set)</strong></summary>

- **Web & Research** (`ctx_url_read`): pull a public web page, PDF, or YouTube transcript into context as compressed, citation-backed text — `facts`/`quotes` return claims with a confidence score + source URL, relevance-ranked research-compression distils to a token budget, SSRF-guarded (http/https only) - **Graph-Powered Intelligence**: hybrid search (BM25 + embeddings + graph proximity via RRF), incremental git-diff updates - **LSP Refactoring** (`ctx_refactor`): language-server-powered rename, references, go-to-definition via rust-analyzer, typescript-language-server, pylsp, gopls - **Multi-Agent** (`ctx_agent`, `ctx_handoff`): agent handoff with context transfer bundles, diary system, synchronized shared state - **Archive Full-Text Search** (`ctx_expand search_all`): FTS5-powered cross-archive search over all previously archived tool outputs - **PR Context Packs**: `lean-ctx pack --pr` builds a PR-ready context pack (changed files, related tests, impact, artifacts) - **Context Packages**: `lean-ctx pack create` bundles Knowledge + Graph + Session into portable `.ctxpkg` files with SHA-256 integrity - **Context Time Machine**: `lean-ctx snapshot create|list|show|verify|restore|publish|import` — git-anchored, ed25519-signed snapshots of the layer state (lineage, ledger Φ, ROI, session) on an append-only timeline; replay them in the dashboard, `restore` to resume a session (and `--git` to check out the commit), or `publish`/`import` a signed snapshot to share it ([concept →](docs/concepts/context-time-machine.md)) - **Observability**: `lean-ctx gain --live` for live context metrics, `lean-ctx wrapped` for weekly/monthly summaries (`gain --svg`/`--share` for a shareable card or self-hostable page), and `lean-ctx dashboard` for the browser Context Manager - **Savings ledger**: `lean-ctx savings` is an auditable, per-event ledger of local token counts (tokenizer transparency, bounce-netting, tamper-evident SHA-256 chain) — local-only, on by default; provider-measured savings need the proxy with counterfactual metering - **HTTP mode**: `lean-ctx serve` for Streamable HTTP MCP + `/v1/tools/call` (used by the Cookbook and external clients)

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 770 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <pre>
  3. ██╗ ███████╗ █████╗ ███╗ ██╗ ██████╗████████╗██╗ ██╗
  4. ██║ ██╔════╝██╔══██╗████╗ ██║ ██╔════╝╚══██╔══╝╚██╗██╔╝
  5. ██║ █████╗ ███████║██╔██╗ ██║ ██║ ██║ ╚███╔╝
  6. ██║ ██╔══╝ ██╔══██║██║╚██╗██║ ██║ ██║ ██╔██╗
  7. ███████╗███████╗██║ ██║██║ ╚████║ ╚██████╗ ██║ ██╔╝ ██╗
  8. ╚══════╝╚══════╝╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝
  9. </pre>
  10. ## LeanCTX
  11. **Context Gateway for AI Systems.**
  12. ### **Control what your AI can see.**
  13. LeanCTX sits between AI tools and the information they read. It selects
  14. task-relevant context, applies supported access and content controls before
  15. delivery, and records the context operations and delivery evidence it can observe.
  16. Your application, agent loop and model stay yours.
  17. The open-source **LeanCTX | OSS** runs locally through CLI, MCP, hooks and proxy paths.
  18. The **LeanCTX SDK** embeds supported Engine capabilities in your application.
  19. ---
  20. <p>
  21. <a href="https://github.com/yvgude/lean-ctx/stargazers"><img src="https://img.shields.io/github/stars/yvgude/lean-ctx?style=social" alt="GitHub Stars"></a>&nbsp;&nbsp;
  22. <a href="https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml"><img src="https://github.com/yvgude/lean-ctx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  23. <a href="https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml"><img src="https://github.com/yvgude/lean-ctx/actions/workflows/security-check.yml/badge.svg" alt="Security"></a>
  24. <a href="https://crates.io/crates/lean-ctx"><img src="https://img.shields.io/crates/v/lean-ctx?color=%23e6522c" alt="crates.io"></a>
  25. <a href="https://crates.io/crates/lean-ctx"><img src="https://img.shields.io/crates/d/lean-ctx?color=%23e6522c" alt="Downloads"></a>
  26. <a href="https://www.npmjs.com/package/lean-ctx-bin"><img src="https://img.shields.io/npm/v/lean-ctx-bin?label=npm&color=%23cb3837" alt="npm"></a>
  27. <a href="https://aur.archlinux.org/packages/lean-ctx"><img src="https://img.shields.io/aur/version/lean-ctx?color=%231793d1" alt="AUR"></a>
  28. <a href="LICENSE.md"><img src="https://img.shields.io/badge/License-Mixed-blue.svg" alt="Mixed license"></a>
  29. <a href="https://discord.gg/6qUJ3QmDyP"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
  30. <a href="https://x.com/leanctx"><img src="https://img.shields.io/badge/𝕏-Follow-000000?logo=x&logoColor=white" alt="X/Twitter"></a>
  31. <a href="#privacy--security"><img src="https://img.shields.io/badge/Telemetry-Configurable-blue?logo=shield&logoColor=white" alt="Configurable telemetry"></a>
  32. </p>
  33. <p>
  34. <a href="https://leanctx.com">Website</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://leanctx.com/docs/getting-started">Docs</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#get-started-30-seconds">Install</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#real-world-scenarios">Scenarios</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#demo">Demo</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#benchmarks">Benchmarks</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="cookbook/README.md">Cookbook</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="SECURITY.md">Security</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="CHANGELOG.md">Changelog</a>
  35. </p>
  36. </div>
  37. ---
  38. ## Where it sits
  39. ```text
  40. Files · repositories · tool results · configured providers
  41. │
  42. ▼
  43. LeanCTX Context Gateway
  44. Select · Control · Learn · Prove
  45. │
  46. ▼
  47. Your AI application / agent
  48. │
  49. ▼
  50. Your model
  51. ```
  52. - **Select:** give AI the context the task needs, with search, structural views,
  53. compression and reuse.
  54. - **Control:** apply configured path permissions, content filters and context
  55. budgets to supported calls.
  56. - **Learn:** retain local task records and connect code and knowledge across
  57. sessions, within the configured access and retention rules.
  58. - **Prove:** inspect source references, policy decisions and usage evidence.
  59. A context-only integration records its prepared result; the host owns the
  60. subsequent model call.
  61. For coding workflows, start with **Claude Code, Cursor or Codex**.
  62. [The installation matrix](docs/integrations/installation-matrix.md) distinguishes
  63. first-class paths from other compatibility references.
  64. | Your work | Start here |
  65. |---|---|
  66. | Improve the context path of existing AI tools | [Community setup](#get-started-30-seconds) |
  67. | Apply shared context controls across an organization | [Enterprise](https://leanctx.com/enterprise/) — licensed controls and deployment scope |
  68. | Build context control into your application | [LeanCTX SDK](https://github.com/Thinkery-AG/leanctx-sdk) — stable interfaces and separate SDK/OEM terms |
  69. [What is LeanCTX?](docs/what-is-leanctx.md) ·
  70. [Where LeanCTX fits](docs/where-leanctx-fits.md) ·
  71. [Architecture](ARCHITECTURE.md)
  72. <p align="center"><strong>See it in action:</strong></p>
  73. <table>
  74. <tr>
  75. <td align="center" width="33%">
  76. <img src="assets/leanctx-demo.gif" width="320" alt="Map-mode file read + compressed git output demo">
  77. <br/>
  78. <strong>Read + Shell</strong>
  79. <br/>
  80. Map-mode reads + compressed CLI output
  81. </td>
  82. <td align="center" width="33%">
  83. <img src="assets/leanctx-gain.gif" width="320" alt="lean-ctx gain terminal summary demo">
  84. <br/>
  85. <strong>Gain (terminal)</strong>
  86. <br/>
  87. Token usage + estimated cost differences
  88. </td>
  89. <td align="center" width="33%">
  90. <img src="assets/leanctx-benchmark.gif" width="320" alt="lean-ctx benchmark report demo">
  91. <br/>
  92. <strong>Benchmark measurement</strong>
  93. <br/>
  94. Measure compression by language + mode
  95. </td>
  96. </tr>
  97. </table>
  98. <p align="center"><sub>All GIFs are generated from reproducible VHS tapes in <code>demo/</code>.</sub></p>
  99. ## Why developers use LeanCTX
  100. - **Focused input** — use less of the context window for repeated reads and noisy output.
  101. - **Configured controls** — bound file access and filter supported results before delivery.
  102. - **Continuity** — retain local task, finding and decision records across sessions.
  103. - **Existing tools** — configure a supported integration with `lean-ctx setup`.
  104. - **Inspectable usage** — separate token estimates, provider observations and calculated costs.
  105. - **Model choice** — keep your own model calls and application workflow.
  106. ---
  107. <p align="center">
  108. <strong>Find LeanCTX useful?</strong> <a href="https://github.com/yvgude/lean-ctx">Give it a star</a> — it helps others find the Context Gateway for AI systems.
  109. </p>
  110. ---
  111. ## Inside LeanCTX | OSS
  112. The Engine puts Select, Control, Learn and Prove into the context paths of your
  113. existing AI tools. Your host keeps control of the task, agent loop and model.
  114. ### 1. Select — the context each task needs
  115. Search and structural views help an agent find relevant information before
  116. reading entire files. Supported read and shell paths can return focused views
  117. of files and command output, with references for recovering detail.
  118. - **File reads**: 16 read modes (`full`, `map`, `signatures`, `diff`, `lines:N-M`, `density:X`, …) — eligible cached re-reads return a compact reference instead of repeating content
  119. - **Target density** (`density:0.4`): SDE-style budget compression — keeps the highest-entropy lines until ~40% of the original tokens remain, deterministic
  120. - **JIT disclosure**: `signatures` carries line spans and points at `lines:N-M` for targeted expansion — outline first, bodies on demand
  121. - **Shell output**: 85+ shell-output patterns compress git, npm, cargo, docker, kubectl, terraform and more (250+ passthrough rules)
  122. - **Tree-sitter AST**: structural understanding for 27 languages — not just text compression
  123. - **Source recovery (CCR)**: supported compact views retain source or archive references for expansion through `ctx_expand` or the reference API. Recovery depends on permissions, retention and the source remaining available. [Read modes and detail →](docs/reference/02-daily-use.md#1-reading-files)
  124. ### 2. Control — configured rules on supported paths
  125. - **PathJail and roles:** constrain tool filesystem access to the configured scope.
  126. - **Content filters:** configured detectors can warn, redact or block on supported
  127. paths. Detection coverage and enforcement depend on the integration and settings.
  128. - **Context budgets:** bound selected input and supported tool output.
  129. - **Host-owned model choice:** the host chooses the model and performs any model
  130. calls outside the Engine's observed path.
  131. Review [the security policy](SECURITY.md) for defaults, supported controls and
  132. coverage limits. A filesystem boundary is not an operating-system sandbox.
  133. ### 3. Learn — connect work across sessions
  134. Keep useful task records and discover relationships between code and local
  135. knowledge. Learning here means context continuity; it does not train your model.
  136. - **Session memory (CCP)**: persist task/facts/decisions across chats — structured recovery queries survive compaction
  137. - **Knowledge graph**: temporal facts with validity windows, relations and lifecycle
  138. - **Property Graph**: multi-edge code graph (imports, calls, exports, type_ref) powers impact analysis and search ranking
  139. - **Permission-bound reuse:** access and retention rules still apply when stored
  140. context is retrieved. Experimental `.ctxpkg` export is described under Research below.
  141. ### 4. Prove — inspect what the Engine recorded
  142. Inspect source references, recorded policy decisions and delivery evidence from
  143. supported paths. `lean-ctx inspect` explains observed context operations. A
  144. context-only integration records its prepared result; it cannot prove a later
  145. model call made by the host.
  146. - **Cockpit** (`lean-ctx cockpit`): local browser view with token tracking, compression stats, spend and recorded calls
  147. - **Audit export:** retain the recorded evidence for review within its stated scope.
  148. - **Context Proof** (`ctx_proof`, `ctx_verify`): exportable audit trail (verifier, SLO, pipeline and provenance records) plus runtime-checked policy claims (PathJail per touched file, budget)
  149. ## Usage and cost — measure the result
  150. Context controls and evidence come first. Usage estimates and calculated costs
  151. help you assess their operational effect; they do not prove answer quality.
  152. ### Shadow Mode — a simulated baseline
  153. Shadow Mode estimates what the same work would have cost without LeanCTX,
  154. without changing the active workflow. The baseline is **simulated** from the
  155. uncompressed token counts and the same outcome signals, not a second measured
  156. run, so its reports estimate cost, tokens and CPAO deltas; they do not measure
  157. answer quality.
  158. LeanCTX records local cost and outcome signals without adding those reports to
  159. agent context. CPAO (cost per accepted outcome) is one comparison metric; Shadow
  160. Mode provides simulated savings estimates. Keep estimates, provider-measured
  161. usage and outcome quality separate.
  162. ```bash
  163. lean-ctx savings --period week # costs, token savings, and CPAO
  164. lean-ctx value-report --format markdown --last 20 # recent outcome quality
  165. lean-ctx shadow --latest # latest baseline comparison
  166. ```
  167. ### Quick start: usage tracking
  168. ```bash
  169. # Enable shadow mode for savings comparison
  170. lean-ctx config set shadow.enabled true
  171. # After using LeanCTX for a while:
  172. lean-ctx savings
  173. lean-ctx shadow --latest
  174. ```
  175. <details>
  176. <summary><strong>Feature overview (see generated MCP registry for the current count)</strong></summary>
  177. - **Web & Research** (`ctx_url_read`): pull a public web page, PDF, or YouTube transcript into context as compressed, citation-backed text — `facts`/`quotes` return claims with a confidence score + source URL, relevance-ranked research-compression distils to a token budget, SSRF-guarded (http/https only)
  178. - **Graph-Powered Intelligence**: hybrid search (BM25 + embeddings + graph proximity via RRF), incremental git-diff updates
  179. - **LSP-backed symbols**: `ctx_patch op=replace_symbol` edits a whole symbol body and `ctx_callgraph` finds references, through rust-analyzer, typescript-language-server, pylsp or gopls
  180. - **Multi-Agent — Research** (`ctx_agent`, `ctx_handoff`): experimental local agent handoff with context transfer bundles, diary system, and shared state; not a hosted or generally available team service
  181. - **Archive Full-Text Search** (`ctx_expand search_all`): FTS5-powered cross-archive search over all previously archived tool outputs
  182. - **PR Context Packs**: `lean-ctx pack --pr` builds a PR-ready context pack (changed files, related tests, impact, artifacts)
  183. - **Context Packages — Research**: `lean-ctx pack create` bundles local Knowledge, Graph and Session state into `.ctxpkg` files with SHA-256 integrity; this is experimental local packaging, not a generally available Context Kits or hosted sharing product
  184. - **Context Time Machine — Research**: `lean-ctx snapshot create|list|show|verify|restore|publish|import` handles git-anchored, signed local snapshots and file-based sharing; dashboard replay and restore are experimental, and hosted history or a hosted registry is not a generally available product
  185. - **Observability**: `lean-ctx cockpit` shows local activity and recorded context metrics (Savings · Spend · Report · Proof, recorded calls in the Ledger); `lean-ctx gain` is the terminal summary (`--json` for scripts), and `gain --svg`/`--share` creates a shareable card or self-hostable page
  186. - **Usage ledger**: `lean-ctx savings` is a local per-event ledger with tokenizer transparency, bounce-netting and a tamper-evident SHA-256 chain; provider-measured savings require the proxy's counterfactual holdout
  187. - **HTTP mode**: `lean-ctx serve` for Streamable HTTP MCP + `/v1/tools/call` (used by the Cookbook and external clients)
  188. </details>
  189. ## Addons — Research preview
  190. Addon manifests and gateway integration remain experimental Research interfaces.
  191. Local `addon release|add|list` commands handle signed packages; they do not
  192. provide a public marketplace, hosted registry, managed distribution or `addon
  193. search`. A package can carry a sandboxed WASM module or an `[mcp]` declaration
  194. for an external server.
  195. ```bash
  196. lean-ctx addon release ./my-addon # build a signed .ctxpkg — no artifact host, no CI
  197. lean-ctx addon add ./my-addon-1.0.0.ctxpkg # verify, disclose, ask, install
  198. lean-ctx addon list # what's installed, what loads, what's wired
  199. ```
  200. - **Publish it yourself** — the module travels *inside* the signed package, so
  201. the signature covers the executable bytes. Nothing external to host, hash or
  202. serve, and no pipeline of your own.
  203. - **Verified locally, then asked** — `add` re-checks the signature on your
  204. machine rather than trusting its source, checks every module against its
  205. pinned SHA-256, prints the publisher key and the exact command any declared
  206. server would run, and only then prompts.
  207. - **LeanCTX never installs the server for you** — no `uv tool install`, no
  208. `npx`. Fetching a declared tool stays your step, where your own package
  209. manager's trust model applies. The manifest says how to *run* it.
  210. - **Folded in, not just proxied** — opt-in post-processing runs addon output through the same pipeline as your code: compress to a budget, spill oversized blobs to a `ctx_expand` handle, index into BM25 / graph / knowledge. A typed `integration` routes specific tools straight into `ctx_expand`, `ctx_callgraph` and `ctx_knowledge`.
  211. - **Untrusted by default** — addon results pass through secret scrubbing and are tagged untrusted in the integration pipeline. Scrubbing covers configured detection patterns, not every possible secret.
  212. The local workflow verifies signatures and module hashes, shows the publisher
  213. key and declared command before installation, and never installs the external
  214. server. Opt-in post-processing can send addon results through compression,
  215. `ctx_expand`, BM25, graph and knowledge. Results remain untrusted; configured
  216. secret scrubbing does not cover every possible secret. See the
  217. **[status-qualified addon guide](docs/guides/addons.md)** for the boundary.
  218. ## Research directions
  219. LeanCTX remains the Context Gateway for AI Systems. These research directions
  220. extend its context capabilities; they are not supported product commitments.
  221. - **Hosted context history** — local snapshot create/show/verify/restore and signed file-based sharing are experimental Research; a hosted registry and model-view comparison remain future work.
  222. - **Context as Code** — declarative pipelines, profiles, and policies in TOML, versioned like infrastructure
  223. - **Unified Context Graph** — code, tests, commits, CI runs, and knowledge entries in a single semantic graph
  224. - **Cross-agent context controls** — explore context roles, budgets, and permissions while the host retains agent scheduling and workflow execution
  225. - **Context Observability** — SLOs on context consumption, anomaly detection, OpenTelemetry / Prometheus export
  226. The full roadmap lives in **[VISION.md](VISION.md)**.
  227. ## How it works
  228. LeanCTX works on **two planes** — what your agents *read* and what they *send to the model*:
  229. ```
  230. read path: AI tool → (MCP tools + shell) → lean-ctx → your repo + CLI
  231. wire path: AI tool → lean-ctx proxy → model provider (supported, configured requests)
  232. ```
  233. - **MCP server** *(read path)*: exposes `ctx_*` tools (read modes, caching, deltas, search, memory, multi-agent)
  234. - **Shell hook** *(read path)*: transparently compresses common commands so the LLM sees less noise
  235. - **Request proxy** *(wire path, opt-in)*: `lean-ctx proxy enable` routes supported requests through a local proxy. Configured transformations can reduce eligible prompt, history and tool-result content while respecting supported provider-cache boundaries. Provider-specific effort mapping (`proxy.effort`), verbosity controls and volatile-prefix handling have their own compatibility limits. Recovery requires retained, authorized artifacts; usage and cost evidence depend on the provider data the path observes.
  236. - **Property Graph**: multi-edge code graph powers impact analysis, related file discovery, and search ranking
  237. - **Session memory**: persists selected session state for recovery when authorized records remain available
  238. - **Cockpit** (`lean-ctx cockpit`): local browser view for inspecting context activity and records visible to LeanCTX
  239. <a id="get-started-30-seconds"></a>
  240. ## Get started
  241. ```bash
  242. # 1) Install (pick one)
  243. curl -fsSL https://leanctx.com/install.sh | sh # universal (no Rust needed)
  244. brew tap yvgude/lean-ctx && brew install lean-ctx # macOS / Linux
  245. npm install -g lean-ctx-bin # Node.js
  246. cargo install lean-ctx # Rust
  247. # 2) One-command setup for your agent
  248. lean-ctx wrap cursor # or: wrap claude / wrap codex
  249. # Inspect recorded context metrics after your AI's first lean-ctx call.
  250. lean-ctx cockpit # Savings · Spend · Report · Proof in the browser (also: lean-ctx dashboard)
  251. lean-ctx gain --terminal # the same numbers as a terminal summary (--json for scripts)
  252. lean-ctx cockpit stop # stop the background Cockpit server (--foreground keeps it in the terminal)
  253. ```
  254. `lean-ctx wrap` registers the MCP server and configures the supported local
  255. transport for that agent. Undo anytime with `lean-ctx unwrap cursor`.
  256. > **Claude Pro/Max:** subscription OAuth cannot use a custom
  257. > `ANTHROPIC_BASE_URL`. `lean-ctx wrap claude` therefore adds no proxy redirect
  258. > while enabling the `ctx_*` tools and shell-output compression; an existing
  259. > custom endpoint remains untouched.
  260. > Claude wire-level request compression requires `ANTHROPIC_API_KEY`. See
  261. > [advanced proxy setup](docs/reference/05-advanced.md).
  262. <details>
  263. <summary><strong>Alternative: full control</strong></summary>
  264. ```bash
  265. lean-ctx onboard # connect all detected AI tools (zero prompts)
  266. lean-ctx setup # interactive wizard with every option
  267. ```
  268. </details>
  269. **Building from source on Windows?** Clone the repo and run `./install.ps1` in PowerShell — it builds the release binary and installs it into Cargo's bin directory (pass `-BuildOnly` to build without installing).
  270. <details>
  271. <summary><strong>Windows code signing and Smart App Control</strong></summary>
  272. The current release workflow signs new Windows binaries as **Thinkery AG**,
  273. including the binaries inside ZIP archives and Python companion wheels.
  274. Earlier releases may still contain unsigned executables. Signing does not
  275. guarantee acceptance by every Windows security policy.
  276. If Windows blocks an older unsigned download, use WSL or build locally with
  277. `cargo install lean-ctx`; do not disable system-wide security protections for
  278. this tool. Windows-side MCP clients can launch the WSL installation with
  279. `wsl lean-ctx mcp`.
  280. See [Windows signing and verification](docs/windows-signing.md) and
  281. [#1820](https://github.com/yvgude/lean-ctx/issues/1820) for verification status.
  282. </details>
  283. <details>
  284. <summary><strong>Troubleshooting / Safety</strong></summary>
  285. - Disable immediately (current shell): `lean-ctx-off`
  286. - Run a single command uncompressed: `lean-ctx -c --raw "git status"`
  287. - Only activate in AI agent sessions: set `shell_activation = "agents-only"` in `~/.config/lean-ctx/config.toml`
  288. - Per-project config override: create `.lean-ctx.toml` in your project root (auto-merged with global config)
  289. - Docker projects sharing `/workspace`: create `.lean-ctx-id` with a unique name to prevent context collisions
  290. - Update: `lean-ctx update`
  291. - Diagnose (shareable): `lean-ctx doctor --json`
  292. </details>
  293. ## Real-world scenarios
  294. LeanCTX grows with you. Below are the journeys most people actually take — each
  295. links to a complete, function-by-function walkthrough in the
  296. **[Reference](docs/reference/README.md)** (every CLI command and the complete MCP
  297. tools are documented there).
  298. <table>
  299. <tr>
  300. <td width="50%" valign="top">
  301. ### 🟢 Your first setup
  302. *"I just installed it — now what?"*
  303. ```bash
  304. lean-ctx wrap cursor # one-command setup for your agent
  305. lean-ctx doctor # confirm you're wired up
  306. ```
  307. `wrap` configures the supported integration; `doctor` checks the resulting setup.
  308. → **[Journey 1 — Setup & Onboarding](docs/reference/01-setup-and-onboarding.md)**
  309. </td>
  310. <td width="50%" valign="top">
  311. ### 📖 Coding every day
  312. *"Stop re-reading the same files."*
  313. ```bash
  314. lean-ctx read src/server.rs -m map # API surface, ~13 tok on re-read
  315. lean-ctx -c "git status" # compressed shell output
  316. ```
  317. Your agent reads less and searches smarter — automatically.
  318. → **[Journey 2 — Daily Use](docs/reference/02-daily-use.md)**
  319. </td>
  320. </tr>
  321. <tr>
  322. <td width="50%" valign="top">
  323. ### 🧠 Resume where you left off
  324. *"My new chat forgot everything."*
  325. ```bash
  326. lean-ctx overview # task-aware project recap
  327. lean-ctx knowledge recall "auth" # facts that survive resets
  328. lean-ctx knowledge consolidate # import session + compact lifecycle
  329. lean-ctx knowledge consolidate --all # compact every project store
  330. ```
  331. Session memory + a project knowledge graph persist across chats.
  332. → **[Journey 3 — Memory & Knowledge](docs/reference/03-memory-and-knowledge.md)**
  333. </td>
  334. <td width="50%" valign="top">
  335. ### 🗺️ Understand a new codebase
  336. *"Where does this function ripple to?"*
  337. ```bash
  338. lean-ctx graph impact src/auth.rs # blast radius
  339. lean-ctx smells scan # code-smell hotspots
  340. ```
  341. A multi-edge property graph powers impact analysis + ranked search.
  342. → **[Journey 4 — Code Intelligence](docs/reference/04-code-intelligence.md)**
  343. </td>
  344. </tr>
  345. <tr>
  346. <td width="50%" valign="top">
  347. ### 🔌 Providers & multi-repo
  348. *"Pull in GitHub issues and our Postgres schema."*
  349. ```bash
  350. lean-ctx provider list
  351. lean-ctx serve --root ./api --root ./web # multi-repo
  352. ```
  353. External data flows through the same consolidation pipeline.
  354. → **[Journey 5 — Advanced & Integrations](docs/reference/05-advanced.md)**
  355. </td>
  356. <td width="50%" valign="top">
  357. ### 🛠️ Keep it healthy
  358. *"Update, fix, or cleanly remove."*
  359. ```bash
  360. lean-ctx doctor --fix
  361. lean-ctx update
  362. ```
  363. Self-healing diagnostics; surgical uninstall that only removes its own blocks.
  364. → **[Journey 6 — Lifecycle & Troubleshooting](docs/reference/06-lifecycle.md)**
  365. </td>
  366. </tr>
  367. <tr>
  368. <td width="50%" valign="top">
  369. ### 🎛️ Take control of the window
  370. *"Budget my context like a pro."*
  371. ```bash
  372. lean-ctx plan "refactor billing" --budget 8000
  373. lean-ctx compile --mode balanced
  374. ```
  375. Phi-scored planning + knapsack compilation + a context ledger.
  376. → **[Journey 7 — Context Engineering](docs/reference/07-context-engineering.md)**
  377. </td>
  378. <td width="50%" valign="top">
  379. ### 🤝 Run a team of agents
  380. *"Planner + coder + reviewer on one repo."*
  381. ```text
  382. ctx_agent action=register role=dev
  383. ctx_handoff action=create # baton-pass with full context
  384. ```
  385. Shared message bus, diaries, knowledge, and deterministic handoffs.
  386. → **[Journey 8 — Multi-Agent Collaboration](docs/reference/08-multi-agent.md)**
  387. </td>
  388. </tr>
  389. <tr>
  390. <td width="50%" valign="top">
  391. ### 🏢 Headless in CI
  392. *"The same engine, headless in pipelines."*
  393. ```bash
  394. lean-ctx bootstrap # zero-prompt CI setup
  395. ```
  396. Everything local works without an account. LeanCTX Hive (shared knowledge for teams
  397. and your own machines) follows with 3.12.1.
  398. </td>
  399. <td width="50%" valign="top">
  400. ### 🎚️ Tune & govern
  401. *"Make it behave exactly how we want."*
  402. ```bash
  403. lean-ctx compression standard
  404. lean-ctx harden # enforce token discipline
  405. ```
  406. Compression levels, tool profiles, themes, and rules governance.
  407. → **[Journey 10 — Customization & Governance](docs/reference/10-customization-and-governance.md)**
  408. </td>
  409. </tr>
  410. <tr>
  411. <td width="50%" valign="top">
  412. ### 📊 Measure usage and cost
  413. *"Show me the numbers."*
  414. ```bash
  415. lean-ctx cockpit # Savings · Spend · Report · Proof in the browser
  416. lean-ctx gain --deep --terminal # terminal: savings, cost, per-agent, heatmap (--json for scripts)
  417. lean-ctx gain --svg # shareable recap card (also: gain --share / gain --wrapped)
  418. lean-ctx savings # verified per-event ledger (auditable; savings verify)
  419. ```
  420. All analytics live in the Cockpit and the CLI — never burning agent tokens.
  421. → **[Journey 11 — Analytics & Insights](docs/reference/11-analytics-and-insights.md)**
  422. </td>
  423. <td width="50%" valign="top">
  424. ### 📚 The full reference
  425. *"I want to read everything."*
  426. Every command and the generated MCP registry, organized as user journeys, plus
  427. appendices for the [CLI map](docs/reference/appendix-cli-map.md),
  428. [MCP tools](docs/reference/appendix-mcp-tools.md), and
  429. [paths & config](docs/reference/appendix-paths-and-config.md).
  430. → **[Reference index](docs/reference/README.md)**
  431. </td>
  432. </tr>
  433. </table>
  434. ## Supported IDEs & AI tools
  435. LeanCTX provides an **MCP server**. Client support depends on transport, tool
  436. handling, and configuration; the matrix below records the integration scope.
  437. Two integration modes are selected for supported agents:
  438. | Mode | How it works | Best for |
  439. |---|---|---|
  440. | **Hybrid** | MCP for cached reads and references + shell hooks for command compression | Agents with shell access (Cursor, Claude Code, Codex, ...) |
  441. | **MCP** | Complete tool set via MCP protocol, no shell hooks | Protocol-only agents (JetBrains, VS Code, Zed, ...) |
  442. ### Agent compatibility matrix
  443. | Agent | Hybrid | MCP | Setup |
  444. |---|:---:|:---:|---|
  445. | Cursor | ● | | `lean-ctx init --agent cursor` |
  446. | Claude Code | ● | | `lean-ctx init --agent claude` |
  447. | CodeBuddy | ● | | `lean-ctx init --agent codebuddy` |
  448. | Augment CLI / VS Code | ● | | `lean-ctx init --agent augment` |
  449. | Codex CLI | ● | | `lean-ctx init --agent codex` |
  450. | Grok | ● | | `lean-ctx init --agent grok` |
  451. | Gemini CLI | ● | | `lean-ctx init --agent gemini` |
  452. | Windsurf | ● | | `lean-ctx init --agent windsurf` |
  453. | GitHub Copilot | ● | | `lean-ctx init --agent copilot` |
  454. | CRUSH | ● | | `lean-ctx init --agent crush` |
  455. | Hermes | ● | | `lean-ctx init --agent hermes` |
  456. | OpenCode | ● | | `lean-ctx init --agent opencode` |
  457. | Pi | ● | | `lean-ctx init --agent pi` |
  458. | Qoder | ● | | `lean-ctx init --agent qoder` |
  459. | Amp | ● | | `lean-ctx init --agent amp` |
  460. | Cline | ● | | `lean-ctx init --agent cline` |
  461. | Roo Code | ● | | `lean-ctx init --agent roo` |
  462. | Kiro | ● | | `lean-ctx init --agent kiro` |
  463. | Antigravity | ● | | `lean-ctx init --agent antigravity` |
  464. | Amazon Q | ● | | `lean-ctx init --agent amazonq` |
  465. | Qwen | ● | | `lean-ctx init --agent qwen` |
  466. | Trae | ● | | `lean-ctx init --agent trae` |
  467. | Verdent | ● | | `lean-ctx init --agent verdent` |
  468. | Aider | | ● | `lean-ctx init --agent aider` |
  469. | Mistral Vibe | | ● | `lean-ctx init --agent vibe` |
  470. | Continue | | ● | `lean-ctx init --agent continue` |
  471. | JetBrains IDEs | | ● | `lean-ctx init --agent jetbrains` |
  472. | QoderWork | | ● | `lean-ctx init --agent qoderwork` |
  473. | VS Code | | ● | `lean-ctx init --agent vscode` |
  474. | Zed | | ● | `lean-ctx init --agent zed` |
  475. | Neovim | | ● | `lean-ctx init --agent neovim` |
  476. | Emacs | | ● | `lean-ctx init --agent emacs` |
  477. | Sublime Text | | ● | `lean-ctx init --agent sublime` |
  478. > MCP clients need compatible transport, tool support, and configuration. The table lists setup targets; the [client constraints](docs/integrations/client-constraints-matrix-v1.md) distinguish verified integrations from generic compatibility.
  479. ### When to use (and when not to)
  480. **Great fit if you...**
  481. - use AI coding tools daily and your sessions are shell-heavy (git/tests/builds)
  482. - work in medium/large repos (50+ files / monorepos)
  483. - want local context processing with inspectable network and telemetry controls
  484. **Skip it if you...**
  485. - mostly work in tiny repos and rarely call the shell from your AI tool
  486. - always need raw/unfiltered logs (you can still use `--raw`, but ROI is lower)
  487. The honest fine print: the payoff depends on three levers — **reach** (own the
  488. window via the proxy/engine, not just the `ctx_*` tool layer), **context
  489. lifetime** (one long-lived session vs. a fresh process per phase), and
  490. **provider pricing** (prompt-cache-priced vs. re-billed every turn). They stack
  491. into a clear win where they line up and net to **break-even** where they don't.
  492. See the [win vs. break-even matrix](docs/reference/14-performance-tuning.md#win-vs-break-even-at-a-glance)
  493. for the full breakdown and how to tune for each case.
  494. <a id="demo"></a>
  495. ## Demo
  496. Try these in any repo:
  497. ```bash
  498. lean-ctx read rust/src/server/mod.rs -m map
  499. lean-ctx -c "git log -n 5 --oneline"
  500. lean-ctx gain # terminal summary
  501. lean-ctx cockpit # Savings · Spend · Report · Proof (browser)
  502. lean-ctx benchmark report .
  503. ```
  504. - The repo ships the exact tapes used to render the GIFs in `demo/`
  505. - Regenerate locally:
  506. ```bash
  507. vhs demo/leanctx.tape
  508. vhs demo/gain.tape
  509. vhs demo/benchmark.tape
  510. ```
  511. <a id="benchmarks"></a>
  512. ## Benchmarks
  513. Measurements and estimates require a declared workload and method. The earlier per-read-mode
  514. compression table (`map` / `signatures` over 50 files) is **withdrawn** along
  515. with the other historical figures in [BENCHMARKS.md](BENCHMARKS.md); measure
  516. your own repository with `lean-ctx benchmark report .` instead. Cache references
  517. can reduce repeated context; their token cost depends on the emitted result and tokenizer.
  518. Measure the Engine's own advertised schema, instruction, and briefing overhead
  519. with `lean-ctx doctor overhead --gate`. The deterministic
  520. `lean-ctx benchmark dual-arm --json` replay reports a **synthetic upper bound**:
  521. its baseline never uses the provider's prompt cache, while agent hosts can cache
  522. the prefix with or without LeanCTX. It is not a provider invoice, an on/off
  523. comparison or an outcome-quality evaluation. The on/off comparison the Engine
  524. offers is the proxy's opt-in compression holdout (`[proxy] compression_holdout`).
  525. Proxy rewrites preserve stable output for prompt-cache eligibility under the same
  526. inputs and settings, and the compression engine checks that critical facts
  527. (failing tests, error codes, locations) survive or it delivers the original.
  528. Actual cache hits, prices, and discounts depend on the provider. Quality results
  529. state their evidence tier (A mechanism … E production) — see
  530. [context-quality-v1](docs/contracts/context-quality-v1.md).
  531. A powered with/without quality study has not been run yet; the proxy's
  532. compression holdout measures prompt size on real traffic and reports answer
  533. quality as `unknown`. What each number can and cannot show, per data path:
  534. [measurement scope](docs/concepts/measurement-scope.md).
  535. - **Latest snapshot**: [BENCHMARKS.md](BENCHMARKS.md)
  536. - **Reproduce**: `lean-ctx benchmark report .`
  537. ## Adoption and compatibility
  538. - [GitHub activity](https://github.com/yvgude/lean-ctx) and [releases](https://github.com/yvgude/lean-ctx/releases) show the current repository counts and release history.
  539. - [Supported integration paths](docs/integrations/installation-matrix.md) distinguish verified setups from protocol compatibility.
  540. - [Generated MCP registry](docs/reference/appendix-mcp-tools.md) shows the current tool count and status.
  541. - [Published metrics](https://leanctx.com/metrics/) state their measurement scope; adoption counts do not establish savings or outcome quality.
  542. ## Docs
  543. - **Reference (every function, by user journey)**: [docs/reference/](docs/reference/README.md) — 11 journeys + CLI/MCP/config appendices
  544. - **For AI agents / LLMs**: [llms.txt](llms.txt) — a curated, machine-readable map of lean-ctx (per the [llms.txt](https://llmstxt.org) convention)
  545. - Getting started: https://leanctx.com/docs/getting-started
  546. - Tools reference: https://leanctx.com/docs/tools/
  547. - CLI reference: https://leanctx.com/docs/cli-reference/
  548. - What is LeanCTX: https://leanctx.com/what-is-leanctx/
  549. - Comparison (vs RTK, Context+, MemGPT): https://leanctx.com/compare/
  550. - Community and commercial options: https://leanctx.com/pricing/
  551. - FAQ: [discord-faq.md](discord-faq.md)
  552. - Feature catalog (SSOT snapshot): [LEANCTX_FEATURE_CATALOG.md](LEANCTX_FEATURE_CATALOG.md)
  553. - Monorepo guide: [docs/guides/monorepo.md](docs/guides/monorepo.md)
  554. - Semantic code intelligence: [docs/guides/semantic-intelligence.md](docs/guides/semantic-intelligence.md)
  555. - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)
  556. - Vision: [VISION.md](VISION.md)
  557. ## Privacy & security
  558. - **Inspectable telemetry controls:** run `lean-ctx telemetry status` to see the effective setting and `lean-ctx telemetry show` to inspect the payload; `lean-ctx telemetry disable` turns reporting off.
  559. - **Disableable update check** (config `update_check_disabled = true` or `LEAN_CTX_NO_UPDATE_CHECK=1`)
  560. - **40+ security hardening fixes** in v3.5.16 (path traversal, injection, CSPRNG, CSP, resource limits — [details](CHANGELOG.md))
  561. - **Context Governance Benchmark self-assessment**: graded **C2 — Managed** against the 32-control [CGB v1.0-draft](https://github.com/yvgude/context-governance-benchmark) spec, gaps declared — [docs/compliance/cgb-self-assessment.md](docs/compliance/cgb-self-assessment.md)
  562. - Context processing runs locally; configured source providers, proxy/model requests, submitted feedback, updates, and enabled telemetry have their own network paths.
  563. See [SECURITY.md](SECURITY.md).
  564. ## Uninstall
  565. One command removes **everything** — it stops all processes, then deletes hooks,
  566. editor configs, rules, autostart (LaunchAgent/systemd), the data dir, **and the
  567. binary itself**:
  568. ```bash
  569. lean-ctx uninstall # full clean removal
  570. lean-ctx uninstall --dry-run # preview every change, write nothing
  571. lean-ctx uninstall --keep-config # keep MCP configs + rules (for reinstall)
  572. lean-ctx-off # or just disable for the current shell session
  573. ```
  574. No binary on PATH (or you used the curl installer)? Run the same removal from the installer:
  575. ```bash
  576. curl -fsSL https://leanctx.com/install.sh | sh -s -- --uninstall
  577. ```
  578. If you installed via a package manager, `uninstall` removes everything it wrote and
  579. tells you the one command to finish removing the binary:
  580. ```bash
  581. brew uninstall lean-ctx # Homebrew
  582. cargo uninstall lean-ctx # cargo install
  583. npm uninstall -g lean-ctx-bin # npm
  584. ```
  585. ## Star History
  586. <a href="https://star-history.dera.page/#yvgude/lean-ctx&type=Date">
  587. <picture>
  588. <source media="(prefers-color-scheme: dark)" srcset="https://star-history.dera.page/svg?repos=yvgude/lean-ctx&type=Date&theme=dark" />
  589. <source media="(prefers-color-scheme: light)" srcset="https://star-history.dera.page/svg?repos=yvgude/lean-ctx&type=Date" />
  590. <img alt="Star History Chart" src="https://star-history.dera.page/svg?repos=yvgude/lean-ctx&type=Date" />
  591. </picture>
  592. </a>
  593. ## Contributing
  594. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Easy first PR: propose a new CLI compression pattern via the [issue template](.github/ISSUE_TEMPLATE/compression_pattern.md).
  595. ## License
  596. LeanCTX | OSS and its open interfaces (`rust/`, `packages/`, `docs/`,
  597. `scripts/`) are Apache-2.0. [LICENSE.md](LICENSE.md) and
  598. [LICENSE_MATRIX.toml](LICENSE_MATRIX.toml) are the path-level authority for
  599. that Apache host.
  600. The consolidated development tree also carries `sdk/` (client bindings) and
  601. `ee/` (commercial Runtime, Suite and services) next to the host. Both keep
  602. their own existing terms, are not Apache-2.0 and are not approved for
  603. publication; the host-only mirror contains neither directory. Their presence
  604. in one checkout relicenses nothing. [SOURCE_LAYOUT.md](SOURCE_LAYOUT.md) lists
  605. each path with its current terms.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.