skim-mcp

skim

为 Agent 模型（Claude Code / 桌面版 Claude）提供节省 Token 的先略读再展开 I/O。

独立社区项目——与 Anthropic 无关联、未获其认可或赞助。 无遥测；完全在你的机器上运行。请参阅商标、隐私与许可证。

模型无需将整个大型文件读入上下文，而是调用 skim_open(path)，获取紧凑的骨架——结构、签名，以及（对于日志/数据）保留的关键值，例如 id、数字、日期和错误代码——还有锚点 id。模型可以低成本读取骨架，然后调用 skim_expand(handle, anchors=[...])，只提取所需的确切片段，原样且无损。

压缩是惰性的，而非有损的：不会改写或丢弃任何内容，只是延后读取。只需再调用一次即可展开——这正是它适用于无法摄取潜在向量的闭源模型的原因。

它能做到而其他工具做不到的事

主流工具在上下文中有损——repo-map 和 --compress 会丢弃函数体；摘要工具和压缩模型会改写内容。最接近的同类工具要么只支持代码，要么向模型展示转换后的视图，并将原文保存在旁路缓存中。skim 的原则更严格：进入上下文的内容都是原样源码，未展示的内容都可以通过锚点一次展开获取——Agent 可以根据已读内容编辑代码，无需重新读取。这一原则适用于所有场景：

• 文件——Python（ast）以及约 17 种语言（tree-sitter）；函数体会折叠，可通过一次 expand 获取。
• 整个代码库——skim_repo 会生成按优先级排序、符合 Token 预算的映射；可从任意文件展开确切代码。
• 命令输出——skim_run 会压缩冗长的测试 / 构建 / 日志输出，并可完整还原。
• 数据与日志——通用处理路径带有保留保证（id、数字、错误代码、否定词会提升到骨架中，绝不会被静默丢弃），并会对重复块进行去重。

架构和经验证的既有技术定位，请参阅 DESIGN.md。

可验证，而非空口声称

在你能够核验之前，压缩比例只是营销说辞。skim 附带了核验工具：

uv run skim-verify path/to/your/gnarliest_file.py     # any file at all; exit code tells CI

五项不变量可在你的文件上本地验证：每个非空行都可还原，展开内容与原始字节完全一致，锚点均在有效范围内，还原结果与解码后的文件一致，并且输出具有确定性。测试套件通过 Hypothesis 模糊测试，在每条路径上验证相同约束；如果任何可读文件上出现可复现的 FAIL，那就是 Bug——请报告。优先摘要的工具无法提供这条命令，因为对它们而言，等效检查会按设计失败。

关于成本与正确性的问题，有一个专门的开放评测标准——eval/ACCURACY.md 会按完整读取与 skim 两种方式为每个评测问题计算成本（包括 skim 表现较差的条目），任何其他上下文工具也可以按照相同协议评分。

专为审计而构建

• 整个软件包不到 2,000 行标准库 Python 代码（读取引擎约 1,200 行）——无需下载 ML 模型，没有框架，没有遥测，依赖仅一个（mcp，另有可选的 tiktoken/tree-sitter 扩展）。花一个下午即可完成全部安全审查：SECURITY.md 是威胁模型。
• 所有非只读功能都有一个终止开关：SKIM_RUN_DISABLED=1 会移除 shell 工具，SKIM_PATCH_DISABLED=1 会移除文件编辑器；读取器仍可正常工作。
• **Windows 是一等平台，而非移植目标：**命令输出按 UTF-8 解码（不会出现 cp1252 乱码），超时后确实会终止整个进程树（taskkill /F /T），skim_patch 会保留 CRLF，CI 也会在 windows-latest 和 Ubuntu 上运行完整测试套件。

试用核心功能（无需安装）

python demo.py path/to/file.py            # measured before/after token counts
python demo.py                            # demo on examples/sample.log (retention + dedup)

结果（硬数据）

以下所有数字均由 uv run python benchmarks.py 实时生成——完整的可复现数据表见 BENCHMARKS.md。在运行中的解释器标准库（真实代码）上测量；Token 数量通过 tiktoken cl100k_base 计算（Claude 分词器的近似值；比率对分词器具有稳健性）。

真实代码的 Token 节省情况——60 个 Python 标准库文件：387,911 → 122,660 tokens（减少 68%，缩至 3.16 倍）；单文件缩减 1.5×–11×；100% 无损、结果确定；运行时间近似线性（每 1,000 行约 4 ms）；纯 CPU 运算，无 GPU、无网络、无模型调用。

多语言支持（tree-sitter，[lang] 扩展）——JS / TS / Go / Rust / Java / C / C++ / Ruby / PHP / C# 等语言使用同一套无损引擎。例如：一个 481 行的 JavaScript 模块 → 缩至 6.6 倍 / 节省 85%，且无损。

真实任务的前后 1:1 对比（分布级）——"读取此模块中最大的函数"；模型打开文件、读取骨架，再仅展开所需的那个函数。答案相同，完整 skim 成本（骨架 + 展开）均计入，覆盖 24 个大型模块：

文件	行数	读取的函数	完整读取	skim（骨架+展开）	节省
tarfile.py	3,032	_proc_pax（119 行）	25,180	8,906	65%
optparse.py	1,682	parse_args（37 行）	12,830	5,610	56%
pathlib.py	1,436	walk（43 行）	11,242	5,421	52%
bdb.py	921	effective（48 行）	7,279	3,243	55%
socketserver.py	864	serve_forever（27 行）	5,824	3,615	38%
24 个文件合计			176,897	71,877	59%

每项任务的节省幅度：跨 24 项任务，中位数 51%，平均值 51%，范围 30–91%——这是诚实呈现的分布，而非挑选最佳案例。需要读取文件大部分内容时，收益会缩小。

正面对比——相同的 30 个文件（compare.py + 通过 npx 运行真实 Repomix）：

方案	tokens	占完整读取的比例	是否无损？
完整读取（Claude Read）	184,277	100%	是
skim	64,043	34.8%	是（延迟展开）
Repomix --compress	105,963	57.5%	否（函数体被丢弃）
仅签名（Aider/Basemind 机制）	20,276	11.0%	否

skim 是唯一无损的方案，Token 用量比 Repomix --compress 少 40%。Repo-map 方案体积约小 3 倍，但会不可逆地丢弃函数体、文档字符串和注释。（Basemind 是纯 Rust 实现，未安装；其数据行复现了仅签名机制——详见 COMPARISON.md。）

**正确性：**80 个文件中的 54,215 行非空代码没有一行无法恢复；202 项测试 / 约 80% 覆盖率，并使用 Hypothesis 对两条路径进行属性模糊测试；约 18,000 个案例的对抗测试（发现的每个 Bug 都已修复，并通过回归测试锁定）。复现方式：uv run python bench.py / pytest / benchmarks.py。

作为 MCP 服务运行

一行命令（首次运行时从 PyPI 安装，包含 tree-sitter 语言包）：

claude mcp add skim -- uvx --from "skim-mcp[lang,tokens]" skim-mcp

或从源代码运行：

git clone https://github.com/helloderekg/skim-mcp.git && cd skim-mcp
uv sync --extra lang                       # MCP SDK + multi-language (tree-sitter); drop --extra lang for Python-only

注册到 Claude Code（使用仓库的绝对路径；在 Windows 上使用正斜杠也可以）：

claude mcp add skim -- uv run --directory /abs/path/to/skim-mcp skim-mcp

或配置 Claude Desktop——添加到 claude_desktop_config.json（Windows 上为 %APPDATA%\Claude\， macOS 上为 ~/Library/Application Support/Claude/），然后重启：

{
  "mcpServers": {
    "skim": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/skim-mcp", "skim-mcp"]
    }
  }
}

（如果找不到 uv，请使用 where uv / which uv 查到的完整路径。）

工具

• skim_open(path, query="") → 紧凑的结构概览 + 锚点 ID（阅读结构概览；ID 位于其 expand("aN") 标记中）。传入 query 还可在同一次调用中获取 matches（行号 + 覆盖该行的锚点），无需再单独搜索。
• skim_expand(handle, anchors=[...]) → 精确的原文片段。参数可以是锚点 ID（"a7"），也可以是字面 行范围（"L120-180"），适用于 grep 已经给出行号的情况。
• skim_search(handle, query) → 查找包含某个字符串的锚点/行号，无需读取其内容。
• skim_run(command) → 运行 shell 命令，并获取其输出的紧凑、可展开视图（测试 / 构建 / 日志）。
• skim_repo(path, query) → 为整个仓库生成无损、按相关性排序且受令牌预算限制的地图；可从任意 文件展开精确代码。传入查询时按查询匹配度排序，否则按 导入图中心性（基于文件间导入关系计算 PageRank）排序， 因而最关键的模块会优先显示。
• skim_patch(handle, anchor, new_text) → 在磁盘上精确替换一个已展开的片段，并安全应对文件变动：若文件自 skim_open 后发生更改，则拒绝操作；保留 LF/CRLF 换行格式；从磁盘重新验证结果，并返回新的 handle。 由于展开的内容是原文，基于它构建的编辑可以安全应用——只读文件的 8%，照样能编辑它。 （SKIM_PATCH_DISABLED=1 可关闭此功能。）
• 片段也可以作为 MCP 资源使用：@skim:skim://doc/<handle>/span/<anchor> 可通过引用获取片段。

实际使用示例

修复一个你几乎不需要了解的大型模块中的 bug。 任务：“tarfile.py（3,032 行，25,180 个令牌）中的 _proc_pax 为什么会错误处理 pax 标头？” Claude 调用 skim_open，阅读包含所有签名的结构概览，找到 _proc_pax，展开对应的锚点，然后根据 精确的 119 行函数体给出答案。测得的成本：8,906 个令牌，包括结构概览和展开内容。答案相同，令牌减少 65%（参见基准测试表——24 个此类任务的中位数为 51%）。

快速了解陌生仓库。 skim_repo(".", query="rate limit") 会在单个令牌预算内返回最相关文件的结构概览， 并按相关性排序；每个文件都有自己的 handle。Claude 阅读地图，展开两个不同文件中相关的两个函数，然后开始编辑；仓库的其余部分虽未读取，但仍可随时访问。

CI 检查失败，输出中有 400 行噪声。 skim_run("pytest -q") 会返回退出代码和紧凑视图：重复的样板内容会折叠为“与 a3 相同”的指针，而保留层会将关键字面内容（错误代码、文件路径、计数）提升到视图中，无需展开任何内容即可看到失败原因。需要完整回溯信息时，Claude 只需展开相应代码块。

何时不该精简（坦诚说明）。 对于 40 行的配置文件，或你打算整体重写的文件，直接读取即可。对于很小的输入，结构概览包装器带来的开销会超过节省的成本；计量器会将这些情况显示为负值，而不是将其隐藏。skim 最适用于日常场景：你只需要从 2,000 行中读取 40 行。

让 Claude 使用 skim

挂载 skim 后，工具就可用了——但这并不意味着 Claude 会使用它们。 Claude 会根据任务选择工具，而对于“读取／审查此文件”，它默认使用内置的 Read，而不是 skim_open。较小的模型（例如 Haiku）尤其不太可能主动使用 MCP 工具。因此，只有实际调用 skim，它才能节省令牌。可以通过两种方式实现：

1. 针对每项任务提出要求：

使用 skim 审查 src/big_module.py 开始前用 skim_repo 梳理此仓库 通过 skim_run 运行测试

2. 让它自动执行——在 CLAUDE.md 中添加规则（项目级文件，或全局文件 ~/.claude/CLAUDE.md）， 这样 Claude 每轮都会主动使用 skim，无需提醒：

When the skim MCP tools are available, prefer skim_open (files) and skim_repo (directories/repos) over
the built-in Read for anything larger than ~300 lines, and skim_run for verbose command output. Expand
only the spans you need — skim is lossless, so skimming first is never risky, only cheaper.

skim 还会向模型提供一条“优先使用 skim”的指令，但模型不一定会遵循服务级指令——CLAUDE.md 规则的约束力更强，尤其对较小的模型而言。你随时可以确认它是否已配置好：在某个会话中告诉它 “用 skim 打开 <a big file>”，然后观察 计量器的变化。

或者让 skim 在一条幂等命令中完成两个步骤——注册并添加规则：

uv run skim-mcp install                              # from a source checkout (project ./CLAUDE.md rule)
uvx --from "skim-mcp[lang,tokens]" skim-mcp install  # from PyPI
skim-mcp install --rule global                       # write the rule to ~/.claude/CLAUDE.md instead
skim-mcp install --print-only                        # show what it would do, change nothing

重复运行不会造成规则重复；如果 claude CLI 不在 PATH 中，它会打印准确的手动命令和 Claude Desktop JSON。

实时查看节省情况

挂载 skim 后，在另一个终端中运行计量器——这是一个小型 localhost 仪表板（纯标准库，无网络、无依赖），它会读取服务写入的同一个 skim_calls.jsonl，并每秒刷新一次：

uv run skim-meter                        # -> http://127.0.0.1:17321
uv run skim-meter --once                 # one-shot text snapshot instead of the web view
uv run skim-meter --price-per-mtok 3     # optional: also show ~dollars saved at YOUR rate

它会实时显示：输入令牌数（完整读取这些文件／运行这些命令所需的令牌数）、输出令牌数（skim 实际放入上下文的内容——骨架以及每次展开／搜索的结果）和节省比例 = 1 - out/in，并按会话细分。数据如实反映情况——展开会拉低节省比例，而对微小输出运行 skim_run 甚至可能导致净损失。

按会话统计： 每个 skim 服务进程都会为每次调用添加会话 ID，而 Claude Code 会为每个会话启动一个进程——因此仪表板会列出所有会话（即使尚未使用 skim），并按最近活动时间排序。每一行会显示你设置的 SKIM_SESSION_LABEL，否则显示该会话首次接触的文件／仓库（否则显示 idle），并列出其启动时间和短 ID，以便区分。点击 Clear 按钮（或运行 skim-meter --clear）会将日志归档到带时间戳的 ghost 文件，并将计量器重置为零——不会丢失任何内容。（MCP 不会告知服务是哪个 子 Agent 发起了调用，因此服务端能提供的最细粒度划分是连接／会话。）

测试

uv sync --extra dev
uv run pytest                  # unit + property-based fuzzing of the invariants (202 tests, ~80% coverage)
uv run python bench.py         # invariant sweep + compression over the standard library
uv run python check_invariant.py <file>   # check one file against the invariants

该测试套件通过手写边界用例、真实标准库，以及使用 Hypothesis 对代码路径和通用路径进行模糊测试，确保对任何输入都满足六项不变量——无损、往返完全一致、重建完全一致（full_text 与解码后的文件逐字节相同）、位于边界内、确定性，以及绝不崩溃。

亲自衡量展开循环的效果： eval/QUESTIONS.md 是一份包含 7 个问题的欠取评估（每个答案都隐藏在锚点之后，并由测试锁定）； uv run python eval/score_expand_loop.py 会根据真实会话日志进行评分，而 eval/ACCURACY.md 会为每个问题评估成本（完整读取与 skim，包含负值）——这是一把准确度与成本的标尺，也欢迎其他上下文工具使用。

局限性（如实说明）

• 代码骨架支持 Python（ast）和约 17 种通过 tree-sitter 支持的语言——JS、TS、Go、Rust、Java、C、C++、Ruby、PHP、C#、Kotlin、Swift、Scala、Bash、Lua、R。安装可选的 [lang] 扩展；其他文本会回退到通用（无损）分块路径。其余约 300 种 tree-sitter 语法将逐步支持（每种语言的折叠功能都会先通过真实解析验证，再随版本发布）。
• 密集的重复日志会使用 Drain 风格模板（~412x GET /api/<*> took <*>ms），让骨架展示重复的内容；结构化 JSON/CSV 骨架仍在路线图中，因此这类内容的压缩效果有限。
• 这取决于模型是否调用 expand。 如果模型需要展开的正文，却直接根据骨架作答，答案可能有误。引导提示可以缓解这一问题；skim_calls.jsonl 可用于衡量这一情况。
• 在 if / try 代码块内定义的函数不会显示为签名（仍可无损展开）。
• skim_run 会在你的计算机上运行 shell 命令（以捕获并压缩其输出），权限与服务进程相同——这与 Agent 的 Bash 工具属于同一类能力。只应在允许 Agent 运行命令的环境中挂载 skim；遭到提示词注入的模型可能会调用破坏性命令。设置 SKIM_RUN_DISABLED=1 可将 skim 设为只读挂载（shell 工具会拒绝执行，读取器仍可正常工作）。完整威胁模型见 SECURITY.md。
• 句柄保存在服务进程的内存中。 它们在会话期间有效（Claude Code 每个会话运行一个 skim 进程）；重启后，旧句柄会返回明确的 unknown handle 错误——请重新打开。句柄基于内容哈希，因此重新打开后内容已更改的文件会获得新句柄，过期的锚点 ID 绝不会悄然指向不同的行。
• 节省效果取决于用法： 对于只读取部分内容的大文件，节省显著；对于小文件或需要读取大部分内容的情况，效果有限。令牌数量使用 tiktoken 估算（作为 Claude 分词器的近似值）；比例结果稳定可靠。

状态与路线图

已发布： Python ast + 多语言 tree-sitter 代码骨架（约 17 种语言，均通过真实解析验证）、带保留策略、去重和 Drain 风格密集日志模板的通用分块路径、skim_run（无损压缩命令/测试输出，并使用进程树安全超时）、skim_repo（全仓库无损映射，按查询匹配度或导入图 PageRank 排序）、作为 MCP 资源的跨度、欠取评估测试框架，以及 skim-meter（实时令牌节省仪表板）——全部通过严密的测试套件保障。

路线图： JSON/CSV 的结构化数据骨架（模式 + 值统计）、其余 tree-sitter 语言；如果欠取评估显示模型未充分利用可用答案，则加入混合推送模式（自动展开相关性排名最高的锚点）；以及运行器适配器，以便按 准确性与成本权衡标准 为其他上下文工具评分。

贡献、安全与更新日志

CONTRIBUTING.md 介绍每项变更都必须遵守的五条不变量（无损、往返精确、范围内、确定性、绝不崩溃），以及如何添加语言。 SECURITY.md 介绍威胁模型和私下报告问题的方式。 CHANGELOG.md 记录版本发布情况；RELEASING.md 介绍发布流程。

商标、隐私与许可证

独立项目。 skim 是一个社区开源项目，与 Anthropic PBC、OpenAI 或任何其他公司均无关联、未获其认可，也未受其赞助。 “Claude”、“Claude Code”和“Anthropic”是 Anthropic, PBC 的商标；“Model Context Protocol” / “MCP”用于描述协议兼容性；“Aider”、“Basemind”和“Repomix”是其各自所有者的商标。所有标记仅用于指称、识别和比较，不代表任何认可。未使用任何第三方徽标。

基准测试。 本仓库中的数据是在文档所述条件下（工具版本、标志、语料库、令牌计数器、日期）测得的，可通过已发布的脚本复现；在其他条件下不作保证。Aider、Basemind 和 Repomix 的对比数据是使用当时最新的公开版本得出的；欢迎通过 issue 提出修正。

隐私与遥测。 skim 完全在你的计算机上运行。它不会发出网络请求，也不会收集、传输或出售任何数据。唯一写入的数据是本地的 skim_calls.jsonl 日志（skim 工具调用记录——文件路径和范围锚点，供你自行调试）；它绝不会离开你的计算机。你可以随时删除该文件，或设置 SKIM_LOG_FILE 将日志重定向到其他位置。日志可能包含你自己文件中的路径／片段；请像对待任何本地日志一样妥善处理。

许可证。 MIT。运行时依赖 mcp（MIT，© Anthropic PBC）和 tiktoken（MIT，© OpenAI）——详见 NOTICE。仅用于开发的测试依赖 hypothesis 采用 MPL-2.0 许可证，未经修改且从不随包发布。

mcp-name: io.github.helloderekg/skim-mcp