Context Intelligence Layer for all Coding Agents

██╗     ███████╗ █████╗ ███╗   ██╗     ██████╗████████╗██╗  ██╗
██║     ██╔════╝██╔══██╗████╗  ██║    ██╔════╝╚══██╔══╝╚██╗██╔╝
██║     █████╗  ███████║██╔██╗ ██║    ██║        ██║    ╚███╔╝
██║     ██╔══╝  ██╔══██║██║╚██╗██║    ██║        ██║    ██╔██╗
███████╗███████╗██║  ██║██║ ╚████║    ╚██████╗   ██║   ██╔╝ ██╗
╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝     ╚═════╝   ╚═╝   ╚═╝  ╚═╝

它的定位

Files · repositories · tool results · configured providers
                          │
                          ▼
                LeanCTX Context Gateway
             Select · Control · Learn · Prove
                          │
                          ▼
                Your AI application / agent
                          │
                          ▼
                     Your model

• **选择：**通过搜索、结构化视图、压缩和复用，为 AI 提供任务所需的上下文。
• **控制：**对受支持的调用应用已配置的路径权限、内容筛选器和上下文预算。
• **学习：**在已配置的访问和保留规则范围内，保留本地任务记录，并在不同会话间关联代码与知识。
• **验证：**检查源代码引用、策略决策和用量证据。 仅提供上下文的集成会记录准备好的结果；后续模型调用由宿主负责。

对于编码工作流，请从 Claude Code、Cursor 或 Codex 开始。 安装矩阵区分了首选集成路径与其他兼容性参考。

什么是 LeanCTX？ · LeanCTX 的定位 · 架构

观看实际效果：

读取 + Shell 地图模式读取 + 压缩的 CLI 输出

增益（实时） Token 用量 + 预估成本差异

基准测试 按语言 + 模式测量压缩率

_{所有 GIF 均由 demo/ 中可复现的 VHS 录制生成。}

开发者为何使用 LeanCTX

• 聚焦输入 — 减少重复读取和嘈杂输出对上下文窗口的占用。
• 已配置的控制 — 限制文件访问，并在交付前筛选受支持的结果。
• 连续性 — 在不同会话间保留本地任务、发现和决策记录。
• 现有工具 — 使用 lean-ctx setup 配置受支持的集成。
• 可检查的用量 — 区分 Token 估算值、提供方观测数据和计算得出的成本。
• 模型选择 — 保留你自己的模型调用和应用工作流。

觉得 LeanCTX 有用？ 点亮星标 — 这有助于其他人找到适用于 AI 系统的上下文网关。

LeanCTX 引擎内部

引擎将选择、控制、学习和验证融入现有 AI 工具的上下文路径。宿主仍掌控任务、Agent 循环和模型。

1. 选择——每项任务所需的上下文

搜索和结构视图可帮助 Agent 在阅读整个文件前找到相关信息。受支持的读取和 Shell 路径可返回文件和命令输出的重点视图，并附带用于查看详细内容的引用。

• 文件读取：16 种读取模式（full、map、signatures、diff、lines:N-M、density:X、……）——符合条件的缓存重读会返回精简引用，而不是重复内容
• 目标密度（density:0.4）：采用 SDE 风格的预算压缩——保留熵最高的行，直到剩余约 40% 的原始令牌数；结果确定
• 按需展开：signatures 会提供行范围，并指向 lines:N-M 以便有针对性地展开——先看概要，需要时再查看正文
• Shell 输出：85 种以上 Shell 输出模式可压缩 git、npm、cargo、docker、kubectl、terraform 等命令输出（250 多条直通规则）
• Tree-sitter AST：对 27 种语言进行结构化理解，而不只是压缩文本
• 源码恢复（CCR）：受支持的精简视图会保留源码或归档引用，以便通过 ctx_expand、ctx_retrieve 或引用 API 展开。能否恢复取决于权限、保留策略以及源内容是否仍然可用。读取模式与详细信息 →

2. 控制——在受支持的路径上应用已配置的规则

• **PathJail 和角色：**将工具的文件系统访问限制在已配置的范围内。
• **内容过滤器：**已配置的检测器可在受支持的路径上发出警告、编辑内容或阻止操作。检测覆盖范围和执行情况取决于集成方式和设置。
• **上下文预算：**限制所选输入和受支持工具输出的规模。
• **由宿主选择模型：**宿主选择模型，并在 Engine 所观察路径之外执行任何模型调用。

请查看安全策略，了解默认设置、受支持的控制措施和覆盖范围限制。文件系统边界并非操作系统沙箱。

3. 学习——关联不同会话中的工作

保留有用的任务记录，并发现代码与本地知识之间的关联。此处的学习指保持上下文连续性，而不是训练模型。

• 会话记忆（CCP）：在不同聊天间保留任务／事实／决策——结构化恢复查询可在压缩后继续使用
• 知识图谱：带有效期的时序事实、情景记忆与程序记忆
• **属性图：**多边代码图（导入、调用、导出、type_ref）可用于影响分析和搜索排序
• **受权限约束的复用：**检索存储的上下文时，访问和保留规则仍然适用。实验性的 .ctxpkg 导出功能见下文的 Research 部分。

4. 证明——检查 Engine 记录的内容

检查受支持路径中的源码引用、记录的策略决策和交付证据。lean-ctx inspect 可说明观察到的上下文操作。仅提供上下文的集成会记录其准备好的结果；它无法证明宿主之后发起的模型调用。

• Context Manager：浏览器仪表板，提供实时令牌跟踪、压缩统计信息和使用率仪表
• **审计导出：**在其声明的范围内保留记录的证据以供审查。
• 上下文证明（ctx_proof、ctx_verify）：可导出的审计跟踪（验证器、SLO、管道和来源记录），以及经运行时检查的策略声明（每个已触及文件的 PathJail、预算）

用量与成本——衡量结果

上下文控制和证据优先。用量估算和计算得出的成本有助于评估其运营影响，但不能证明答案质量。

Shadow Mode — 模拟基线

Shadow Mode 估算在不使用 LeanCTX 的情况下，同一项工作会花费多少，而不改变当前工作流。基线是根据未压缩的 token 数和相同的结果信号模拟得出，并非第二次实际测量的运行，因此其报告估算成本、token 数和 CPAO 差值；不会衡量答案质量。

LeanCTX 会在本地记录成本和结果信号，而不会将这些报告添加到 Agent 上下文中。CPAO（每个已接受结果的成本）是一项比较指标；Shadow Mode 提供模拟的节省估算。请将估算值、提供商测量的用量和结果质量分开看待。

lean-ctx savings --period week                 # costs, token savings, and CPAO
lean-ctx value-report --format markdown --last 20  # recent outcome quality
lean-ctx shadow --latest                       # latest baseline comparison

快速开始：用量跟踪

# 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

插件清单和网关集成仍属于实验性的研究接口。 本地 addon release|add|list 命令用于处理已签名的软件包；它们不提供公共市场、托管注册表、托管分发或 addon search。软件包可以包含沙箱化的 WASM 模块，也可以声明外部服务的 [mcp]。

lean-ctx addon release ./my-addon   # build a signed .ctxpkg — no artifact host, no CI
lean-ctx addon add ./my-addon-1.0.0.ctxpkg   # verify, disclose, ask, install
lean-ctx addon list                 # what's installed, what loads, what's wired

• 自行发布 — 模块随已签名的软件包一同分发，因此签名涵盖可执行字节。无需托管、哈希或提供任何外部内容，也无需自行搭建流水线。
• 先在本地验证，再征求许可 — add 会在你的机器上重新检查签名，而非信任其来源；检查每个模块是否与固定的 SHA-256 匹配；显示发布者密钥和声明的服务将运行的确切命令，然后才会提示你确认。
• LeanCTX 永远不会替你安装服务 — 不会运行 uv tool install 或 npx。获取声明的工具仍由你负责，并遵循你自己的包管理器信任模型。清单说明了如何运行它。
• 融入流程，而非仅做代理 — 启用后，后处理会让插件输出经过与代码相同的流水线：压缩至预算范围，将超大内容存入 ctx_expand 句柄，并索引到 BM25 / 图谱 / 知识库。类型化的 integration 会将特定工具的请求直接路由到 ctx_expand、ctx_callgraph 和 ctx_knowledge。
• 默认不可信 — 插件结果会经过密钥清理，并在集成流水线中标记为不可信。清理仅涵盖已配置的检测模式，并不能覆盖所有可能的密钥。

本地工作流会验证签名和模块哈希，在安装前显示发布者密钥和声明的命令，并且绝不会安装外部服务。启用后，后处理可以将插件结果送入压缩、ctx_expand、BM25、图谱和知识库。结果仍然不可信；已配置的密钥清理无法覆盖所有可能的密钥。关于此边界，请参阅**注明状态的插件指南**。

研究方向

LeanCTX 仍是 AI 系统的上下文网关。这些研究方向将扩展其上下文能力；它们并非受支持的产品承诺。

• 托管上下文历史 — 本地快照创建、查看、验证、恢复以及基于文件的签名共享均为实验性研究；托管注册表和模型视图比较仍是未来工作。(概念 →)
• 上下文即代码 — 使用 TOML 声明式定义流水线、配置文件和策略，并像基础设施一样进行版本控制
• 统一上下文图谱 — 在单一语义图谱中整合代码、测试、提交、CI 运行记录和知识条目
• 跨 Agent 上下文控制 — 探索上下文角色、预算和权限，同时由宿主保留 Agent 调度和工作流执行
• 上下文可观测性 — 针对上下文消耗设定 SLO、检测异常，并导出 OpenTelemetry / Prometheus 数据

完整路线图请参阅 VISION.md。

工作原理

LeanCTX 在 两个平面上运行——Agent 读取的内容和它们发送给模型的内容：

read path:   AI tool  →  (MCP tools + shell)  →  lean-ctx  →  your repo + CLI
wire path:   AI tool  →  lean-ctx proxy        →  model provider   (supported, configured requests)

• MCP 服务（读取路径）：提供 ctx_* 工具（读取模式、缓存、增量、搜索、记忆、多 Agent）
• Shell 钩子（读取路径）：透明压缩常见命令，让大模型看到更少噪声
• 请求代理（线路路径，选择启用）：lean-ctx proxy enable 会将受支持的请求通过本地代理路由。配置的转换可以缩减符合条件的提示词、历史记录和工具结果内容，同时遵守受支持的提供商缓存边界。提供商专属的工作量映射（proxy.effort）、详细程度控制和易变前缀处理各有其兼容性限制。恢复需要保留且已授权的构件；使用情况和成本证据取决于该路径可观测到的提供商数据。
• 属性图：多边代码图为影响分析、相关文件发现和搜索排序提供支持
• 会话记忆：保留选定的会话状态，以便在授权记录仍可用时恢复
• 上下文管理器：用于检查 LeanCTX 可见的上下文活动和记录的浏览器仪表板

开始使用

# 1) Install (pick one)
curl -fsSL https://leanctx.com/install.sh | sh      # universal (no Rust needed)
brew tap yvgude/lean-ctx && brew install lean-ctx    # macOS / Linux
npm install -g lean-ctx-bin                          # Node.js
cargo install lean-ctx                               # Rust

# 2) One-command setup for your agent
lean-ctx wrap cursor      # or: wrap claude / wrap codex

# Inspect recorded context metrics after your AI's first lean-ctx call.
lean-ctx gain

lean-ctx wrap 会注册 MCP 服务，并为该 Agent 配置受支持的本地传输方式。可随时使用 lean-ctx unwrap cursor 撤销。

**Claude Pro/Max：**订阅 OAuth 无法使用自定义 ANTHROPIC_BASE_URL。因此，lean-ctx wrap claude 不会添加代理重定向， 但会启用 ctx_* 工具和 Shell 输出压缩；现有自定义端点不会受到影响。 Claude 线路级请求压缩需要 ANTHROPIC_API_KEY。请参阅 高级代理设置。

lean-ctx onboard          # connect all detected AI tools (zero prompts)
lean-ctx setup            # interactive wizard with every option

**在 Windows 上从源代码构建？**克隆代码仓库，并在 PowerShell 中运行 ./install.ps1——它会构建发布二进制文件并将其安装到 Cargo 的 bin 目录中（传入 -BuildOnly 可仅构建而不安装）。

真实场景

LeanCTX 会伴随你不断成长。以下是大多数人实际经历的使用历程——每个链接都指向一份完整的逐函数指南，详见 参考文档（其中记录了每条 CLI 命令和全部 MCP 工具）。

lean-ctx wrap cursor  # one-command setup for your agent
lean-ctx doctor       # confirm you're wired up

lean-ctx read src/server.rs -m map   # API surface, ~13 tok on re-read
lean-ctx -c "git status"             # compressed shell output

lean-ctx overview                    # task-aware project recap
lean-ctx knowledge recall "auth"     # facts that survive resets
lean-ctx knowledge consolidate       # import session + compact lifecycle
lean-ctx knowledge consolidate --all # compact every project store

lean-ctx graph impact src/auth.rs    # blast radius
lean-ctx smells scan                 # code-smell hotspots

lean-ctx provider list
lean-ctx serve --root ./api --root ./web   # multi-repo

lean-ctx doctor --fix
lean-ctx update

lean-ctx plan "refactor billing" --budget 8000
lean-ctx compile --mode balanced

ctx_agent action=register role=dev
ctx_handoff action=create        # baton-pass with full context

lean-ctx team serve --config team.toml
lean-ctx bootstrap            # zero-prompt CI setup

lean-ctx compression standard
lean-ctx harden               # enforce token discipline

lean-ctx gain --deep          # savings, cost, per-agent, heatmap
lean-ctx wrapped              # shareable recap (also: gain --svg / gain --share)
lean-ctx savings              # verified per-event ledger (auditable; savings verify)

LeanCTX 提供 MCP 服务。客户端支持情况取决于传输方式、工具处理方式和配置；下表记录了集成范围。 对于支持的 Agent，有两种集成模式可供选择：

Agent 兼容性矩阵

MCP 客户端需要兼容的传输方式、工具支持和配置。表中列出了设置目标；客户端限制区分了已验证的集成和通用兼容性。

适用场景（以及不适用场景）

适合你，如果你……

• 每天使用 AI 编码工具，且会话中经常使用 shell（git/测试/构建）
• 在中型或大型代码仓库（50+ 个文件/单体仓库）中工作
• 希望在本地处理上下文，并能检查网络和遥测控制

不适合你，如果你……

• 大多在小型代码仓库中工作，很少从 AI 工具调用 shell
• 始终需要原始/未过滤的日志（仍可使用 --raw，但投资回报率较低）

坦诚地说，收益取决于三个因素——覆盖范围（通过代理/引擎控制整个窗口，而不只是 ctx_* 工具层）、上下文生命周期（一个长期会话，还是每个阶段启动一个新进程）以及提供商定价（按提示词缓存定价，还是每轮重新计费）。这些因素相互叠加；条件吻合时收益明显，不吻合时则总体盈亏平衡。 请参阅收益与盈亏平衡矩阵，了解完整分析以及各情况下的调优方法。

演示

在任意代码仓库中尝试：

lean-ctx read rust/src/server/mod.rs -m map
lean-ctx -c "git log -n 5 --oneline"
lean-ctx gain --live
lean-ctx dashboard                              # Context Manager (browser)
lean-ctx benchmark report .

• 代码仓库中附带了用于生成 GIF 的原始录制文件，位于 demo/
• 在本地重新生成：

vhs demo/leanctx.tape
vhs demo/gain.tape
vhs demo/benchmark.tape

基准测试

测量和估算都需要声明工作负载和方法。此前按读取模式区分的压缩表（对 50 个文件使用 map / signatures）已撤回，BENCHMARKS.md 中的其他历史数据也一并撤回；请改用 lean-ctx benchmark report . 测量自己的代码库。缓存引用可以减少重复上下文；其 token 成本取决于生成的结果和分词器。

使用 lean-ctx doctor overhead --gate 测量 Engine 自身声明的 schema、指令和简报开销。确定性的 lean-ctx benchmark dual-arm --json 回放给出的是合成上限：其基线从不使用提供商的提示词缓存，而 Agent 宿主无论是否使用 LeanCTX，都可以缓存前缀。它不是提供商账单，不是启用与停用的对比，也不是结果质量评估。可用的对比方法包括 lean-ctx eval ab 子命令（需要通过 --suite 指定套件文件）、lean-ctx eval footprint 中注入上下文的占用量对比（需要通过 --suite 指定套件，并通过 --compare 指定基线），以及代理的可选压缩留出集（[proxy] compression_holdout）。

准确性在明确限制范围内设有门槛。无需模型的 A/B 门槛会检查 JSON 压缩器是否保留了夹具中的所有标准答案，同时减少 token；还会检查代理重写在相同输入和设置下，是否保留稳定输出以满足提示词缓存资格。实际缓存命中、价格和折扣取决于提供商。启用与停用测试台（lean-ctx eval testbench）会将固定版本的真实代码库分别通过原始转储基线和 lean-ctx 运行，使用相同的 token 预算；它通过 LLM 评审器为自由格式 QA 评分，并使用各代码库自身的测试为代码评分，然后生成 FINDINGS.md（token 数 / 轮数 / 用时 / 质量）和回归文件。CI 回放的是小型、已提交的录制数据：它是机制门槛（可捕获管线故障或评分变化），并不能证明压缩能保留答案质量。每份评估报告都会注明证据等级（A 机制……E 生产环境）；配对任务少于 30 个的运行会标记为 UNDERPOWERED，并且除非作为显式的 --mechanism 检查运行，否则会导致 --gate 失败——请参阅 context-quality-v1。 目前尚未开展具有足够统计效力的启用与停用质量研究；代理的压缩留出集会测量真实流量中的提示词大小，并将答案质量报告为 unknown。不同数据路径下，每项数据能说明和不能说明的内容：测量范围。

• 最新快照：BENCHMARKS.md
• 复现：lean-ctx benchmark report .

采用情况与兼容性

• GitHub 活动和版本发布展示当前代码库计数和版本发布历史。
• 支持的集成路径区分已验证的设置与协议兼容性。
• 生成的 MCP 注册表展示当前工具数量和状态。
• 已发布的指标注明其测量范围；采用数量不能证明节省了成本，也不能证明结果质量。

文档

• 参考（按用户历程涵盖每个函数）：docs/reference/ — 11 个历程 + CLI/MCP/配置附录
• 面向 AI Agent / 大模型：llms.txt — lean-ctx 精选的机器可读地图（遵循 llms.txt 约定）
• 快速入门：https://leanctx.com/docs/getting-started
• 工具参考：https://leanctx.com/docs/tools/
• CLI 参考：https://leanctx.com/docs/cli-reference/
• 什么是 LeanCTX：https://leanctx.com/what-is-leanctx/
• 对比（与 RTK、Context+、MemGPT 对比）：https://leanctx.com/compare/
• 社区和商业选项：https://leanctx.com/pricing/
• 常见问题：discord-faq.md
• 功能目录（SSOT 快照）：LEANCTX_FEATURE_CATALOG.md
• Monorepo 指南：docs/guides/monorepo.md
• 语义代码智能：docs/guides/semantic-intelligence.md
• 架构：ARCHITECTURE.md
• 愿景：VISION.md

隐私与安全

• **可检查的遥测控制：**运行 lean-ctx telemetry status 查看生效的设置，运行 lean-ctx telemetry show 检查负载；lean-ctx telemetry disable 可关闭报告。
• 可禁用的更新检查（配置 update_check_disabled = true 或 LEAN_CTX_NO_UPDATE_CHECK=1）
• v3.5.16 中包含 40 多项安全加固修复（路径遍历、注入、CSPRNG、CSP、资源限制 — 详情）
• Context Governance Benchmark 自我评估：依据 32 项控制措施的 CGB v1.0-draft 规范评定为 C2 — Managed，并声明了差距 — docs/compliance/cgb-self-assessment.md
• 上下文处理在本地运行；已配置的来源提供方、代理/模型请求、提交的反馈、更新及启用的遥测各自有独立的网络路径。

参见 SECURITY.md。

卸载

一条命令即可删除所有内容 — 它会停止所有进程，然后删除钩子、 编辑器配置、规则、自动启动项（LaunchAgent/systemd）、数据目录，以及 二进制文件本身：

lean-ctx uninstall                 # full clean removal
lean-ctx uninstall --dry-run       # preview every change, write nothing
lean-ctx uninstall --keep-config   # keep MCP configs + rules (for reinstall)
lean-ctx-off                       # or just disable for the current shell session

PATH 中没有二进制文件（或你使用了 curl 安装程序）？运行安装程序中的相同卸载命令：

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

如果你通过包管理器安装，uninstall 会删除它写入的所有内容，并告知你 最后移除二进制文件所需的一条命令：

brew uninstall lean-ctx        # Homebrew
cargo uninstall lean-ctx       # cargo install
npm uninstall -g lean-ctx-bin  # npm

Star 历史

参与贡献

请从 CONTRIBUTING.md 开始。适合首次提交 PR 的任务：通过 问题模板 提议一种新的 CLI 压缩模式。

许可证

采用混合许可：Trust Core 保持 Apache-2.0 许可，而明确映射的 v4 模块可能采用商业性源码可见条款。请参阅 LICENSE.md 和 LICENSE_MATRIX.toml。