只向 AI 编程助手展示它正在进行的更改所真正相关的代码。
[
)(https://github.com/trakshan-mishra/Diffontext/actions)
!License: MIT LICENSE
DiffContext 是一个面向 LLM 编码代理的上下文编译器。给它一个 Python 仓库和一个更改——一个 git diff、一个分支或一个函数名称——它就会返回模型安全地做出该更改真正需要的一小组函数：会出错的调用方、覆盖它的子类、以及与它相关的测试。它会配您拥有的任何 token 预算，并告诉模型它必须丢弃什么。
它的构建目标是那些将 LLM 接入真实代码库的人——代理循环、PR 审查机器人、CI 检查——凡是需要决定要把什么代码放入提示词而仓库又太大无法全部发送的场景。
而且它能自我评估：将工具指向你的仓库，它会挖掘你的 git 历史，针对真实共同变更对运行检索，并在不符合时打印 NULL RESULT——而这正是该功能。
假设你让助手修改一个 50,000 行项目中的某个函数，你有三种糟糕的选择：粘贴整个仓库（它放不下，而且模型在非常长的上下文中表现更差），只粘贴该函数（模型将破坏它从未见过的三个调用方），或通过名称搜索（grep 无法找到覆盖其行为的子类，或通过 functools.partial 接收它的处理函数——无论给多少预算，其检索召回率都会停滞）。
DiffContext 是第四种选择。将仓库一当性解析为真正的依赖图，然后针对任意更改选择真正重要的少数函数，并将它们打包到最小有效的提示词中。
git change ──► changed functions ──► hybrid retrieval ──► token budget ──► LLM-ready context
graph ∪ BM25 ∪ file top-k + tokensRelated MCP server: Serena
pip install diffcontext零运行依赖项，Python 39+。
用于 MCP 集成（Claude Code / Cursor / Windsurf）：
pip install "diffcontext[mcp]"配置参见 docs/MCP.md。
从源代码进行开发：
git clone https://github.com/trakshan-mishra/Diffcontext.git
cd Diffcontext && pip install -e .diffcontext index /path/to/project # cold: seconds; warm: ~0.02s
diffcontext compile --ref HEAD~1 --max-tokens 8000
diffcontext verify --from-history 20 --calibrate更多命令：USAGE.md。生产环境配方：docs/USE_CASES.md。
diffcontext verify --from-history 20 --calibrate 从 你的 仓库的 git 历史中挖掘真正案例并评估检索质量；不匹配时打印 NULL RESULT，而非返回一个没有意义（无意义）数字。正如提示的：发现“不匹配”本身就是特性。
是的——通过端到端衡量，而非间接。在由每个仓库自己的测试套件（而非 LLM 判定）判定的 128 个 ContextBench Python 任务上，传递率约增加一倍：5.5%→25.8%，exact McNemar p < 0.0001。
另外有两个限定，一书于 benchmarks/contextbench/RESULTS.md §6：(a) 给每个参与组的种子函数是 oracle（来自正确答案补丁）——因此检验的是“给定正确的本地化，上下文质量是否重要？”，而非端到端任务解决能力（本地化对每个组是不免费的）；(b) 128 个有效任务中有 121 个是 django，所以这基本上是 django 的结果。“”
诚实的对照同样是可靠：三种上下文变体（default / gap / depboost）在统计上是不可区分的，p=0.36–0.81。最大优势是“有上下文 vs 没有上下文”，而不是“这个选择器 vs 那个选择器”。完整结果：benchmarks/contextbench/RESULTS.md。
不是代码生成器。它选择与打包上下文，由模型写代码。
不是说优先精度。它建的网很广——默认 top-k 下平均精度在 0.1 以下。若你按 token 付费，则可 --cutoff gap。
还不支持多语言。Python 已完全支持。TypeScript/JS (ESM) 是可用原型，CommonJS 是已测出失败模式。
.cont not a replacement for reading the code. 静态分析有盲区，见下文和 docs/BENCHMARKS.md。
Ground truth 由 git 历史挖掘——*开发者在同一提交中更改了these这些函数；给定`` s不依靠一个，能试探出其他吗？已在 9 个 Python 仓库的 701 个真实提交上测量震，每次 push 时都会在 CI 中重新运行，因此质量不能悄悄衰退。
对真实 co-change 对按提交进行的命中 / 召回，混合检索：
django | click | flask | httpx | pydantic | black* | requests* | |
Hit | 0.894 | 0.889 | 0.863 | 0.935 | 0.758 | 0.897 | 0.953 |
Recall | 0.774 | 0.750 | 0.694 | 0.772 | 0.536 | 0.712 | 0.762 |
*验证性仓库，从未用于调参。完整表表（覆盖全部 9 个仓库）：benchmarks/README.md。
头-向—vs 对等预算下：grep 在 4k tokens 之后召回停滞在 0.215，而 DiffContext 在8k 达到0.576（2.7×）。诚实的另一面：默认 top-k 下平均 拼精度低于 0.1 的符节号主要是支持性上下文，非准确 co-赶change集。--cutoff gap 在最大得分跳跃处截断，精度大约 4×，仍回归约 30%（co-赶 change evaluate；在 Co撞bench 上 2.2× /约 14%）。
2026 年 7 月一项审查针对评估而不是工具本身。三个已发布数字未通过：
校准——唯一可引用的数字（r=0.274， n≈25）测量在不污染索引上施加。重新测量 n=1,080 后，旧得 0.016（p=0.低），即无关。通过向“不确定”收缩修后；得到 r=0.287 (p=0.0001) 它是排名信号，不是概率。
混合权重}——当前 [0.5,0.35,0.15] 未通过留仓库验证； 每个除以获得组合：新的偏ep 视。修复 （现在为 [0.3,0.5,0.2]）。
Dense 基线——TF-IDF 替代者篡改性的；Dese 检索 (0.6656，5/5 全面超过 BM25)。基于真MiniLM 编码器只有 0.597，且只 2/5 次超过。两点先前结论已经更正。
完整说明：docs/auditing-my-own-benchmark.md · 原始报告：benchmarks/RIGOR_REPORT_2026-07.md。
from diffcontext.pipeline import index_repository, analyze_impact, compile
idx = index_repository("/path/to/repo")
impact = analyze_impact(idx, ["./src/auth.py:validate_jwt"])
ctx = compile(idx, impact, max_tokens=8000, top_k=20)
print(ctx.text) # paste-ready, meta-header discloses what was dropped增量 API（idx.update([...])）、结构化输出、可插拔 tokenizer：docs/ARCHITECTURE.md。
语言 | 状态 | 检索质量 |
Python | 完整 | 基准：701 项提交， 5 个仓库 + 4 个验证仓库 |
TypeScript / JS (ESM) | 原型 | 平均召回 0–68%，取决于代码风格 |
JavaScript (CommonJS) | 不支持 | 在 express 中实测 0.0% — 不要使用 |
静态分析有一上限：不存在调用关系的同主题兄弟代码、跨子系统的概念连接（比如所有方法得分 5/20）、以及动态分发，反映出这些是衡量出来的盲区——在 docs/BENCHMARKS.md 中有详细列出。 有疑问处，先运行 grep -rn "function_name(" --include="*.py" . 之后再完全信任“没有调用方”的结论。
docs/ARCHITECTURE.md — 流水线、模块图、代理 API
docs/BENCHMARKS.md — 全部数字、下游 pass@1、限制
docs/MCP.md — Claude Code / Cursor / Windsurf 的 MCP 服务器
docs/ROADMAP.md — 排序更优先的计划。
diffcontext-service — FastAPI 服务 + Web UI
observability — 检索管线追踪
CONTRIBUTING.md — 设置、CI 检验、适配器开发
MIT
Compile LLM-ready context for a change.
Give it changed symbol IDs (e.g. ./src/auth.py:validate_jwt) or a git ref (e.g. HEAD~1), and it returns the callers, callees, and related functions the model needs to make the change safely — packed into max_tokens with a disclosure header showing what was dropped.
Optionally pass task_description (the bug report or issue text) to bias retrieval toward symbols relevant to the described problem — the one signal the graph alone can't provide.
Args: repo_path: Absolute path to the repository. If omitted, uses the --repo from server startup. changed_symbols: List of changed symbol IDs (e.g. ["./src/auth.py:validate_jwt"]). Mutually exclusive with git_ref. git_ref: Git ref to detect changes from (e.g. "HEAD~1"). Mutually exclusive with changed_symbols. When only task_description is given (no changed_symbols or git_ref), defaults to "HEAD". task_description: The bug report or issue text. Biases retrieval toward symbols semantically related to the described problem, not just structurally near the changed symbols. max_tokens: Token budget for the context (default 8000). meta: Disclosure header level: "full" (default), "compact", or "off". The pass@1 effect of meta level is UNMEASURED.
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | full | |
| git_ref | No | ||
| repo_path | No | ||
| max_tokens | No | ||
| changed_symbols | No | ||
| task_description | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It exposes useful behavioral details: output is 'packed into max_tokens', a disclosure headers shows what was dropped, retrieval can be biased by task_description, and the pass@1 effect of the meta level is explicitly marked 'UNMEASURED'. These are substantive disclosures, not merely rephrased schema information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action and then expands into concrete input formats, defaults, and caveats. It contains no filler, yet it is rather long due to the detailed Args block. Every sentence earns its place, and the most critical behavioral caveat ('UNMEASURED') is included without unnecessary qualification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter tool with no annotations and no input-schema descriptions, the description covers all required behavior: input formats, defaults, output composition, token budget, disclosure header, and task bias. The one gap is explicit behavior when all inputs are omitted: it only explains defaulting to HEAD when 'task_description' is given, not what happens when no parameters at all are passed. This is a small but real completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although input-schema content coverage is 0%, the description's Args block thoroughly documents all six parameters with examples, defaults, mutual exclusivity, and behavioral caveats. It explains the exact meaning of changed_symbols and git_ref, the default git_ref when only task_description is passed, and the enum-like behavior of meta. This fully compensates for the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource: 'Compile LLM-ready context for a change.' It further clarifies the resource by naming the accepted inputs (changed symbol IDs or git ref) and the returned content (callers, callees, related functions). It does not explicitly differentiate from the sibling tools, but the purpose is clear enough to be usable in isolation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong input-selection guidance: changed_symbols vs git_ref are mutually exclusive, and task_description alone implies HEAD. However, it says nothing about when to use compile_context over its siblings (find_impact, explain_selection, verify_retrieval), so the when-to-use guidance is limited to parameter choices rather than tool-disambiguation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain why symbols were included or dropped from context.
Returns the included symbols (with scores and token costs) and the dropped symbols (scored but cut by the token budget), so an agent can inspect or filter the selection.
Args: repo_path: Absolute path to the repository. If omitted, uses the --repo from server startup. symbol: The changed symbol ID to build context for. max_tokens: Token budget (default 8000).
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | No | ||
| repo_path | No | ||
| max_tokens | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden here. It is transparent about the behavior: included symbols are returned with scores and token costs, and dropped symbols are scored but cut by the token budget. It does not explicitly state side effects or authorization requirements, but its read-only nature is strongly implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, then the return behavior, then a compact Args block. Every sentence adds value; there is no filler or unrelated detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no annotations, the description covers the essential aspects needed to invoke the tool: what it does, what it returns, and what each parameter means. The only notable gap is the lack of comparative routing guidance against the sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema property descriptions have 0% coverage, so the description must compensate. It does: repo_path is 'Absolute path to the repository' with a fallback to the --repo startup value, symbol is described as 'The changed symbol ID to build context for,' and max_tokens is defined as a 'Token budget' with a default. This adds meaningful semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb and resource: 'Explain why symbols were included or dropped from context.' It also details what is returned. It does not explicitly compare itself to siblings such as compile_context or verify_retrieval, but the purpose is specific enough to be distinguished from them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: after context selection, an agent can 'inspect or filter the selection.' It also explains parameter defaults such as using the startup repo when repo_path is omitted. However, it does not explicitly state when to use this tool over its siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find what breaks if you change a symbol.
Returns the blast radius: direct callers, direct callees, and transitive impact. The "what breaks if I change this" query.
Args: repo_path: Absolute path to the repository. If omitted, uses the --repo from server startup. symbol: Symbol ID (e.g. ./src/auth.py:validate_jwt).
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | No | ||
| repo_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It clearly discloses the output: direct callers, direct callees, transitive impact, and even describes behavior when repo_path is omitted, using the server startup --repo. It does not explicitly call itself read-only, but the language 'Find... Returns' strongly implies a query-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and each sentence earns its place. The summary 'The "what breaks if I change this" query' is a useful clarifying mental model rather than unnecessary repetition. The two argument descriptions are compact and relevant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a fairly simple 2-parameter lookup tool, the description covers the inputs, the core behavior, and the scope of results, and an output schema exists to fill in any return-format uncertainty. It doesn't go quite further to explicitly mention read-only constraints, staleness, or required indices, but there are no annotations and the description is still sufficiently rich for most AI agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, but the description fully compensates for both parameters: repo_path is defined as an absolute path with the startup --repo fallback, and symbol is given an exact Symbol ID example (./src/auth.py:validate_jwt). This adds significant, actionable detail beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding what breaks if a symbol is changed, and what it returns: direct callers, direct callees, and transitive impact. It is specific enough to be distinguished from generic helpers, but it does not explicitly differentiate from sibling tools like compile_context or verify_retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase "The 'what breaks if I change this' query" gives a strong, useful usage frame: call this when you are about to change a symbol and want to assess impact. However, there is no explicit statement about when not to use it, no comparison to alternatives, and no exclusions, so the guidance remains implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mine git history and grade retrieval quality on your repo.
Generates test cases from co-change history, runs DiffContext retrieval against them, and reports hit/recall. Prints NULL RESULT when the tool doesn't fit your repo — finding that out IS the feature.
Args: repo_path: Absolute path to the repository. If omitted, uses the --repo from server startup. n: Maximum number of test cases to generate from git history (default 20).
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| repo_path | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though no annotations were provided, the description reveals significant behavioral traits: it generates test cases from co-change history, runs DiffContext retrieval, reports hit/recall, and optionally prints NULL RESULT when the repo doesn't fit. Calling out the NULL RESULT as a feature is genuinely useful and goes beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is short, front-loaded with the main purpose, then narrows to mechanism and parameters. The NULL RESULT sentence is pointed and earns its place. The Args section provides compact parameter context without re-describing what the schema already defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is an output schema and only two simple parameters, the description is complete: it covers what the tool does, the algorithm, output metrics, edge-case behavior, and all parameter semantics. An agent has enough information to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries all param documentation. It clearly adds meaning by explaining repo_path as an absolute path with a startup fallback to --repo, and describes n as the maximum number of test cases with a default of 20. This covers both parameters meaningfully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Mine git history and grade retrieval quality on your repo,' and then defines the mechanism (generate test cases, run retrieval, report hit/recall). It clearly explains what the tool does, but it does not explicitly contrast it with sibling tools like compile_context or find_impact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context: you use this when you want to assess retrieval quality over git history, and the NULL RESULT warning indicates what to expect if the repository isn't a good fit. However, it does not state explicit when-to-use versus known sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.5.4compile_contextexplain_selectionfind_impactverify_retrievalScored across 4 tools
compile_context and find_impact overlap substantially because both return callers/callees for a symbol or change, requiring an agent to read descriptions carefully to pick the right one. Their intended uses are reasonably distinct—compile_context produces token-budgeted LLM context, while find_impact answers 'what breaks'—and explain_selection and verify_retrieval are clearly separate.
All tool names follow the same snake_case verb_noun pattern: compile_context, find_impact, explain_selection, verify_retrieval. There are no mixed conventions or vague names.
Four tools is an appropriately focused set for this domain: a primary retrieval/context tool, an impact-focused variant, an introspection tool, and an evaluation tool. None of the tools feel redundant or extraneous.
The main workflow is covered: generate context, inspect impacts, explain selection decisions, and verify retrieval quality on the repo. There is a minor gap in that there is no tool to directly explore the raw dependency graph outside these retrieval wrappers, but that is a narrow gap for this tool's stated purpose.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
