AI 코딩 어시스턴트에게 변경 중인 코드와 실제로 관련된 코드만 보여주십시오.
DiffContext는 LLM 코딩 에이전트를 위한 컨텍스트 컴파일러입니다. Python 리포지토리와 변경 사항(깃 디프, 브랜치, 또는 단일 함수 이름)을 입력하면 그 변경을 안전하게 수행하기 위해 모델이 실제로 필요로 하는 작은 함수 집합을 반환합니다: 깨질 호출자, 이를 오버라이드하는 하위클래스, 이를 테스트하는 테스트가 포함됩니다. 사용자가 제공하는 어떤 토큰 예산에도 맞추어 모델에게 무엇을 생략해야 했는지 알려줍니다.
실제 코드베이스에 LLM을 통합하는 사람들을 위해 만들어졌습니다 — 에이전트 루프, PR 리뷰 봇, CI 검사 등 프롬프트에 무엇을 넣을 것인지 결정해야 하고 리포지토리를 보내기에는 너무 큰 모든 곳을 대상으로 합니다.
그리고 DiffContext는 스스로 평가합니다. 리포지토리를 가리키면 git 히스토리를 채굴해서 실제 동시 변경 쌍들에 대해 검색을 실행하고, 맞지 않으면 NULL RESULT를 출력합니다 — 그 사실을 발견하는 것이 바로 기능입니다.
50,000줄짜리 프로젝트에서 한 함수를 변경(다른 함수 사용)하라는 지시를 하면
선택할 수 있는 좋은 방법이 없습니다. Let's consider: 전체 리포지토리를 붙여
넣기 (맞지 않고 매우 큰 컨텍스트에서 모델이 저하됨), 그 함수 하나만
붙여넣기 (모델은 보지 못한 세 개의 호출부를 손상시킴), 또는 이름으로 grep하기
(grep은 오버라이드하는 하위클래스나 functools.partial을 통해 이를 수신하는
핸들러를 찾지 못함 — 우리는 grep의 재현율이 아무리 많은 예산을 투입해도
평탄(plateau) 상태가 되는 것을 측정했습니다).
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 3.9+.
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-as-judge 아님)로 심사된 128개의 ContextBench Python 작업에서 **컨텍스트는 pass@1을 대략 4배: 5.5% → 25.8%**로, exact McNemar p < 0.0001입니다.
두 가지 전제 조건, 둘 다
benchmarks/contextbench/RESULTS.md
§6에 있음: (a) 모든 arm에 주어진 시드 함수는 oracle 정답
패치에서 추출 — 따라서 이 사항은 *"올바른 위치 접근이 주어졌을 때, 컨텍스트
품질이 중요한가?"*를 측정하며 엔드 투 엔드 이슈 해결
(로컬리제이션이 모든 arm에 공짜로 부여됨)을 측정하지 않습니다;
(b) 유효하지 않은 128개 작업 중 121개가 django, 따라서 상당 부분
django에 대한 결과입니다.
정직한 보완: 세 컨텍스트 변형(기본 / gap / depboost)은 서로 통계적으로
구별 불가능합니다, p = 0.36–0.81. 이점은 컨텍스트 유무의 차이일 뿐,
이 셀렉터와 저 셀렉터의 차이가 아닙니다. 전체 결과:
benchmarks/contextbench/RESULTS.md.
코드 생성기가 아닙니다. 컨텍스트를 선택하고 패키징합니다; 코드 작성은 모델 담당입니다.
정밀도를 우선하지 않습니다. 광범위한 그물을 던집니다 — 기본 top-k에서
평균 정밀도가 0.1 미만입니다. 토큰당 비용을 고려한다면 --cutoff gap을
사용하십시오.
아직 다중 언어가 아닙니다. Python은 완전 지원. TypeScript/JS (ESM)는 작동은 하는 시험용입니다; CommonJS는 측정된 실패 모드입니다.
코드를 읽는 것을 대체하지는 않습니다. 정적 분석에는 사각 지점이 있었고, 아래와 docs/BENCHMARKS.md에서 구체적으로 설명합니다.
근거 진실값(ground truth)은 정히스토리에서 채굴됩니다 — 개발자가 특정 함수들을 한 커밋에 함께 수정했음을 보여주면, 도구가 다른 함수들도 찾는가? — 9개의 Python 리포지토리에 걸친 701개 실제 커밋에서 측정되었고, 푸시할 때마다 CI 게이트로 를 다시 실행해 품질이 조용히 퇴보할 수 없게 합니다.
실제 동시 변경 파트너 검색, 하이브리드 검색을 이용한 커밋별 히트/재현율:
django | click | flask | httpx | pydantic | black\p* | 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.
동일한 토큰 예산에서 grep과 맞닥 뜨면, grep은 4k 토큰 이후 0.215에서 멈추며
DiffContext는 8k에서 0.576에 도달합니다. (2.7배). 솔직한 반전: 기본 top-k에서
평균 정밀도는 0.1 미만 — 검색된 대부분의 심볼은 정확한 동시 변경 집합이
아니라 보조 컨텍스트입니다. --cuttop gap은 가장 큰 점수 구간에서 잘라내
정밀도 ~4배가 코스트도 클 ~30% 재현율 감소(동시 변경 벤치마크; Context하고
2.2배 / ~14%)에서 실현됩니다.
2026-07 시즌의 검토는 도구가 아니라 평가 방법을 저장했습니다. 발표된 세 가지 수는 준속하지 못했습니다:
Calibration — 유일하게 인용가능한 수치(r=0.274, n≈25)는 핫폴블 인덱스에서 측정되었습니다. n=1,080으로 깨끗이 재측정하면 레거시 점수가 r=0.016 (p=0.60): 관계가 전혀 없습니다. '모름' 쪽으로 축소해 수정 → r=0.287 (p=0.0001) — 확률이 아니라 총 의 신호입니다.
혼합 가중치 — 배포 중 [0.5, 0.35, 0.15] \은 리포지토리 하나를 남긴 교차검증(leave-one-repo-out)에서 실패 — let's 더 그래프가 가벼운 혼합 방식이 각 fold에서 선택되었습니다. 이제 [0.3, 0.5, 0.2]입니다.
Dense 기준선 — TF-IDF 대리인에 over dense retrieval이 있을 — 0.664 BM25 이긴 5/5으로. 실제 MiniLM encoder일 때 0.597이며 BM25를 2/5만 이깁니다. 기존의 두 결론이 기록된 형태로 수정되었습니다.
전체 기록: docs/auditing-my-own-benchmark.md · 원본 감사 세션: benchmarks/RIG_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([...])), 구조화 출력, 대체 가능한 토크나이저:
docs/ARCHITECTURE.md.
언어 | 상태 | 검색 품질 |
Python | 완전 지원 | 벤치마킹됨: 701 commits, 5 repos + 4 검증 repos |
TypeScript / JS (ESM) | 시고 없음 | 코드 스타일에 따라 평균 recall 0–68% |
JavaScript (CommonJS) | 미지원 | express에서 0.0% 측정 — 사용하지 말 것 |
정적 분석에는 천장이 있습니다: 서로 호출이 없는 테마 형제, 하위시스템 간
개념적 링크(모든 메서드가 0/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 서비스 + 웹 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.
Project memory, semantic code search, and grounded agent context.
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.
