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 from the changed lines outward and stops as soon as additional context stops paying for itself.

Coming from treemapper? That name is deprecated — it was a thin wrapper around diffctx. Every command, flag, and API call works unchanged: treemapper → diffctx, treemapper-mcp → diffctx-mcp.

Why not just use tree or repomix?

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

The [tree-sitter] extra adds AST-level parsing for more accurate context selection across 30+ languages.

Without Python:

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

Prebuilt binaries for linux (x86_64/aarch64), macOS (arm64) and Windows (x64) are attached to every release. The native binary covers diff mode with YAML/JSON output; tree mode, Markdown output, the graph subcommand and the MCP server live in the Python package. cargo add diffctx embeds the selection pipeline in a Rust project (docs.rs).

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 — functions, imports, type definitions — that an LLM actually needs to review the last commit, instead of dumping every changed file in full.

Diff context mode

Finds the minimal set of code 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 from the changed lines outward, and stops when relevance drops below --tau or the --budget token cap is reached.

Calibration of --alpha, --tau, and the edge-weight priors: docs/parameter-strategy.md. Theory: Context-Selection for Git Diff (Zenodo, 2026).

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 HEAD~1 --budget 30000   # limit to ~30k tokens
diffctx . --diff HEAD~1 -c               # diff context to clipboard

Every run reports token count and size on stderr — 12,847 tokens (o200k_base), 52.3 KB (tiktoken, the GPT-4o tokenizer; ~-prefixed approximation above 1 MB). -c/--copy sends output to the clipboard via pbcopy (macOS), clip (Windows), or wl-copy/xclip/xsel (Linux). Unreadable files are replaced by placeholders such as <binary file: N bytes>, <file too large: N bytes>, or <unreadable content: not utf-8>.

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 = strict-zero floor (empty); -1 = uncapped; N = hard cap
    alpha=0.6,
    tau=0.12,
    full=False,
    scoring_mode="ego",
    timeout=300,
)
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. Install with pip install 'diffctx[mcp]' and add to your MCP client config (e.g. ~/.claude/mcp.json for Claude Code):

{
  "mcpServers": {
    "diffctx": {
      "command": "diffctx-mcp"
    }
  }
}

The server exposes a get_diff_context tool that assistants call when reviewing PRs, explaining changes, or investigating broken tests. Configs for Cursor, Continue, Windsurf, and Zed: src/diffctx/mcp/README.md.

Ignore patterns

Respects .gitignore and .diffctx/ignore automatically — hierarchically at every directory level, with gitignore semantics (negation !important.log, anchored /root_only.txt). .diffctx/whitelist acts as an include-only filter, and the output file is always auto-ignored. --no-default-ignores disables the built-in patterns; --no-ignores disables all ignore rules (tree mode only).

Exit codes

License

Apache 2.0

• Changelog
• Security policy — threat model and vulnerability reporting
• Parameter strategy — how --alpha, --tau, and edge weights are calibrated