diffctx — smart diff context for LLM code review

diffctx selects the minimum code an LLM needs to review a git diff. Instead of pasting whole files, it walks the dependency graph outward from the changed lines and stops once more context stops paying for itself.

Formerly published as treemapper — every command, flag, and API call works unchanged.

How it compares

Whole-repo packers (repomix and friends) seed on the repository and export everything; persistent code-graph servers answer structural queries against a maintained index. diffctx is diff-seeded: the input is a change, the output is the fragments needed to understand it, packed under a hard token budget — local, deterministic, no index, no model calls. Measured results and when the other two families fit better: COMPARISON.md.

Install

uvx diffctx . --diff HEAD~1             # zero-install, run once via uv
pipx install diffctx                    # recommended: isolated CLI, no venv needed
pip install diffctx                     # or: into an active environment
pipx install 'diffctx[mcp]'             # + MCP server for AI assistants

Without Python:

cargo install diffctx                   # native CLI from crates.io
npx diffctx . --diff HEAD~1             # npm wrapper over the native binary
docker run --rm -v "$PWD:/repo" ghcr.io/nikolay-e/diffctx . --diff HEAD~1

On Windows, via Scoop (this repository is the bucket):

scoop bucket add diffctx https://github.com/nikolay-e/diffctx
scoop install diffctx/diffctx

Every release carries prebuilt binaries; the current target set is Linux (x86_64/aarch64), macOS (arm64/x86_64) and Windows (x64/arm64), and a release older than a target's first build lacks it (v1.16.0 predates the macOS x86_64 and Windows arm64 archives). On Windows on ARM, diffctx[mcp] builds cryptography from source, which needs OpenSSL: that project publishes no wheel for the platform. Free-threaded CPython (3.14t) cannot load the abi3 wheel, so each release after 1.16.0 also ships a cp314t wheel per platform (the extension runs with the GIL off); on 1.16.0 itself pip and uv fall back to compiling the sdist. The native binary and Docker image cover diff mode with YAML/JSON output and write to stdout (redirect to capture); tree mode, Markdown output, the graph subcommand and the MCP server live in the Python package.

Quick start

diffctx . --diff HEAD~1       # smart context for last commit → paste into Claude/ChatGPT
diffctx . -f md -c            # full codebase export → clipboard in Markdown

diffctx . --diff HEAD~1 selects only the fragments an LLM needs to review the last commit, instead of dumping every changed file in full.

Diff context mode

Finds the minimal set of fragments needed to understand a change — imports, callers, type definitions, config dependencies — across 50+ file types. It builds a code graph (imports, co-changes, type refs), propagates relevance outward from the changed lines, and stops when relevance drops below --tau or the --budget token cap is hit.

--diff takes a git range (HEAD~1..HEAD, main..feature) or a duration window ending now — 24h, 8d, 90min, 1h30m, 2w (units s, m/min, h, d, w, composable). A window diffs the working tree against the last commit before it, so it covers the commits made inside the window plus the uncommitted and untracked work on top — diffctx . --diff 24h is "everything I touched today". A ref that happens to look like a duration (a branch 24h) keeps its git meaning.

Every JSON/YAML artifact opens with schema: diffctx.context.v1 and validates against schemas/diffctx.context.v1.json, generated from the engine's own type; it closes with a provenance block (engine version, input object ids, the effective configuration and its hash, the selection parameters, the tokenizer) and, when a limit stopped the run short, a coverage block naming it.

graph subcommand

Explore the underlying dependency graph directly, without a diff:

diffctx graph .                                  # Mermaid graph of directory deps (default)
diffctx graph . --summary                        # cycles, hotspots, coupling metrics
diffctx graph . --level fragment -f json         # fragment-level graph as JSON
diffctx graph . --level file -f graphml -o g.xml # file-level graph as GraphML

Usage

# full codebase export:
diffctx .                                 # Markdown to stdout + token count
diffctx . -f md -c                        # Markdown → clipboard
diffctx . -f json -o tree.json            # JSON → file
diffctx . --no-content                    # structure only, no file contents
diffctx . --max-depth 3                   # limit depth
diffctx . -i custom.ignore                # custom ignore patterns

# diff context mode (requires git repo):
diffctx . --diff                          # uncommitted changes (working tree vs HEAD)
diffctx . --diff HEAD~1                   # context for last commit
diffctx . --diff main..feature            # context for feature branch
diffctx . --diff 24h                      # everything changed in the last 24 hours
diffctx . --diff 8d                       # same over 8 days (also 90s, 10min, 1h30m, 2w)
diffctx . --diff HEAD~1 --budget 30000    # limit to ~30k tokens
diffctx . --diff HEAD~1 -c                # diff context to clipboard
diffctx . --diff HEAD~1 --with-raw-diff   # raw patch + selected context
diffctx . --diff HEAD~1 --mode locate     # ranked navigation JSON, no source

Every run reports token count and size on stderr — 12,847 tokens (o200k_base), 52.3 KB. Counts are exact only for the GPT-4o family; Claude, Gemini and others tokenize differently, so treat --budget as an upper bound and leave headroom (details). Unreadable files become placeholders like <binary file: N bytes>.

Python API

from pathlib import Path
from diffctx import build_diff_context, map_directory, to_json, to_markdown, to_text, to_yaml

ctx = build_diff_context(
    Path("."),
    "HEAD~1..HEAD",
    budget_tokens=None,       # None = auto; 0 = no fragments; -1 = uncapped; N = cap on the whole artifact
    alpha=0.6,
    tau=0.05,
    full=False,
    scoring_mode="ego",
    timeout=300,
    with_raw_diff=False,      # True also embeds the raw unified diff (not charged to budget)
)
print(to_markdown(ctx))

tree = map_directory(
    ".",
    max_depth=None,
    no_content=False,
    max_file_bytes=None,
    ignore_file=None,
    no_default_ignores=False,
    whitelist_file=None,
)
print(to_yaml(tree))

MCP server

diffctx includes an MCP server that lets AI assistants (Claude Code, Cursor, Windsurf, etc.) call diff context analysis automatically during code review. It is published in the official MCP registry as io.github.nikolay-e/diffctx. One-line setup (zero-install via uv):

# Claude Code
claude mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
# Codex CLI
codex mcp add diffctx -- uvx --from 'diffctx[mcp]' diffctx-mcp
# Gemini CLI
gemini mcp add diffctx uvx -- --from 'diffctx[mcp]' diffctx-mcp
# VS Code
code --add-mcp '{"name":"diffctx","command":"uvx","args":["--from","diffctx[mcp]","diffctx-mcp"]}'

With pip install 'diffctx[mcp]' already done, replace the uvx --from 'diffctx[mcp]' diffctx-mcp tail with plain diffctx-mcp.

The server exposes one tool, diffctx_context, that assistants call when reviewing PRs, explaining changes, or investigating broken tests. It ranks the code that explains a diff, then reads only the fragments the assistant picked — two calls that pay for the selection instead of a whole pack. The wider get_tree_map and get_file_context tools are opt-in via DIFFCTX_MCP_LEGACY_TOOLS=1. Filesystem confinement via DIFFCTX_ALLOWED_PATHS: see SECURITY.md.

Every stdio client takes the same server shape; only the config file differs:

{
  "mcpServers": {
    "diffctx": {
      "command": "uvx",
      "args": ["--from", "diffctx[mcp]", "diffctx-mcp"]
    }
  }
}

With pip install 'diffctx[mcp]' already done, "command": "diffctx-mcp" with no args works everywhere instead. Use the diffctx-mcp entry point, not the diffctx mcp subcommand: the latter only exists from 1.12.3 onward and would map a directory named mcp on older releases.

Ignore patterns

Respects .gitignore and .diffctx/ignore automatically — hierarchically at every directory level, with full gitignore semantics (negation !important.log, anchored /root_only.txt), and in tree mode the output file is always auto-ignored (--diff reports a saved tree.md like any other change). Three controls are tree mode only and are refused with --diff and graph: .diffctx/whitelist (-w) as an include-only filter, -i for an extra ignore file, and --no-default-ignores / --no-ignores to drop the built-in patterns or every ignore rule.

An excluded path never appears in the output in any role: in diff mode it is dropped both from changed_files and from the candidate universe, so it cannot come back as a related-context fragment either (including under --full). The same guarantee covers secret-like paths (id_rsa, *.pem, *.key, ...), which are filtered even without an ignore entry.

Token cache

Diff mode caches per-blob tokenization in the OS cache directory (e.g. ~/Library/Caches/diffctx/token-cache) — a pure speedup, safe to delete. DIFFCTX_TOKEN_CACHE_DIR relocates it; DIFFCTX_TOKEN_CACHE_MAX_BYTES caps its size (default 512 MB, 0 disables eviction).

Exit codes

License

Apache 2.0

• Documentation site — the pipeline end to end: diff → fragments → graph → relevance → selection
• Command-line reference — every flag with its default and meaning, rendered from diffctx --help
• GitHub Action — diff context as a CI step for LLM review
• Token counting — which encoder, and what --budget means for non-GPT models
• Comparison — measured results, and when a whole-repo packer or a persistent code-graph server fits better
• Benchmarks — every published number with what it was measured on, and how to reproduce it
• FAQ — heuristic or oracle, whose tokens, monorepos, the raw diff, secrets
• Paper — budgeted typed-graph retrieval for diff-aware context selection (Zenodo, 2026)
• Changelog
• Security policy — threat model and vulnerability reporting
• Parameter strategy — how --alpha, --tau, and edge weights are calibrated