Diffcontext

What trakshan-mishra/Diffcontext does

trakshan-mishra/Diffcontext is a context compiler for coding agents working against Python repositories. It identifies code related to a change rather than asking an agent to consume the whole project. Depending on the supplied target, the workflow can include callers, callees, overriding subclasses, tests, and other retrieved functions.

The result is formatted as model-ready context and constrained by a requested token budget. A metadata header records what was excluded, so the receiving agent can distinguish unavailable context from code that was not relevant to the selection. The project selects context; it does not generate or modify source code.

How it works

The repository is indexed into a dependency graph. A change can be represented by a git diff, a branch or reference, or a function location such as a file-and-symbol target. Retrieval then combines graph relationships with BM25 text matching and file-level signals. The selected candidates are ranked and packed using limits such as top_k and max_tokens.

A bug report or other issue text can optionally influence retrieval. The verify workflow uses a repository's git history to create co-change cases, evaluates whether related functions are found, and reports NULL RESULT when the requested retrieval does not fit. This provides a way to test suitability on the target repository instead of relying only on published measurements.

Setup and configuration

Install the base package with pip install diffcontext. The package requires Python 3.9 or newer and has no runtime dependencies. Add the MCP extra with pip install "diffcontext[mcp]" when connecting the workflow to Claude Code, Cursor, or Windsurf. The repository also supports editable installation from a local clone.

A typical command sequence indexes a project, compiles context from a recent reference, and evaluates retrieval from history:

diffcontext index /path/to/project
diffcontext compile --ref HEAD~1 --max-tokens 8000
diffcontext verify --from-history 20 --calibrate

The repository's MCP documentation contains the server configuration details.

Tools and capabilities

The trakshan-mishra/Diffcontext workflow provides these documented operations:

• Index a repository and maintain an incremental index.
• Analyze impact from function targets such as ./src/auth.py:validate_jwt.
• Compile selected context with token and result-count limits.
• Verify retrieval against cases mined from git history.
• Produce structured output and use a pluggable tokenizer through the library API.

The Python API exposes index_repository, analyze_impact, and compile. The command-line interface covers indexing, compilation, and verification. Python is fully supported.

Limitations and notes

trakshan-mishra/Diffcontext is not a precision-first selector: at the default top-k, many retrieved symbols may be supporting context rather than exact co-change partners. The gap cutoff can reduce the amount selected at a recall cost. Static analysis can miss thematic relationships without calls, conceptual links across subsystems, and dynamic dispatch. The documentation recommends checking with grep when a result reports no callers.

Published ContextBench results are qualified by oracle localization and a strong Django concentration, so they should not be treated as end-to-end issue-solving results for every codebase. The repository's own verification command is the appropriate way to assess retrieval behavior on a particular project.