diffctx — smart diff context for LLM code review

CI PyPI crates.io npm License

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.

Coming from treemapper? That name is deprecated. Every command, flag, and API call works unchanged: treemapper → diffctx, treemapper-mcp → diffctx-mcp.

Why not just use tree or repomix?

tree repomix Claude Code Review diffctx
Primary use case directory listing full repo export automated PR review diff context for code review
Smart diff context ✗ ✗ ✓ ✓
Works with any LLM ✓ ✓ Claude only ✓
Free / local / offline ✓ ✓ $15–25/review ✓
GitHub required ✗ ✗ ✓ ✗
Multiple output formats ✗ limited — YAML/JSON/MD/txt
Python API ✗ ✗ ✗ ✓
MCP server ✗ ✗ ✗ ✓

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

The image runs as a non-root user (uid 10001) and writes to stdout — the native binary has no -o flag, so redirect to capture: ... --diff HEAD~1 > context.yaml.

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 pipeline in a Rust project — the library is imported as _diffctx (use _diffctx::pipeline::build_diff_context), since the crate doubles as the Python extension module (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 demo

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.

Flag Default Description
--scoring ego ego = bounded expansion around changed nodes (fast, predictable radius); ppr = Personalized PageRank (global, smoother decay, slower); bm25 = lexical retrieval against the diff hunks (baseline for sparse graphs)
--budget auto Hard token cap: N enforces a fixed cap, -1 disables it, 0 is a strict-zero floor (empty selection; use --full for changed files only)
--alpha 0.60 PPR damping; higher = context clusters tighter around changes (--scoring ppr only)
--tau 0.12 Relevance threshold for full fragment content; lower-scoring fragments are stubbed or dropped (lower = more context)
--full false Only the changed files, every fragment, no related-code context
--timeout 300 Wall-clock deadline in seconds; on expiry diffctx exits 124 instead of hanging

Calibration of --alpha, --tau, and the edge-weight priors: docs/engineering/parameter-strategy.md. Theory: diffctx: Budgeted Typed-Graph Retrieval for Diff-Aware Code Context Selection (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 above 1 MB). -c/--copy copies output via pbcopy (macOS), clip (Windows), or wl-copy/xclip/xsel (Linux). Unreadable files become placeholders like <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]', then register it — for Claude Code:

claude mcp add diffctx -- diffctx-mcp

The server exposes three tools — get_diff_context, get_tree_map, and get_file_context — that assistants call when reviewing PRs, explaining changes, or investigating broken tests. Tool reference and 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 full 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).

Token cache

Diff mode caches per-blob tokenization under ~/Library/Caches/diffctx/token-cache (macOS), $XDG_CACHE_HOME/diffctx/token-cache (Linux) or %LOCALAPPDATA%\diffctx\token-cache (Windows). It is a pure speedup: deleting it only costs one cold run.

Variable Effect
DIFFCTX_TOKEN_CACHE_DIR Relocate the cache
DIFFCTX_TOKEN_CACHE_MAX_BYTES Size cap, default 536870912 (512 MB); 0 disables eviction

Eviction is amortized: each run trims one of the cache's 256 shards back under its share of the cap, oldest entries first.

Exit codes

Code Meaning
0 Success — output contains content
1 Runtime error (bad path, permission denied, etc.)
2 Usage error (invalid flags/arguments)
3 Environment error (--diff outside a git repo, git not installed, no commits yet)
4 --diff produced no semantic context (clean tree, binary-only, everything filtered); output is still emitted. Deletion/rename/lockfile-only diffs list deleted_files/renamed_files/lockfile_changes and exit 0
124 --diff exceeded the --timeout wall-clock deadline
130 Interrupted (Ctrl-C)
141 Broken pipe (e.g. piping into head)

Repository layout

Rust product code lives in crates/diffctx-native/; the Python CLI and MCP package live in src/diffctx/. Evaluation code, immutable datasets, and paper artifacts are intentionally separated under eval/, datasets/, and paper/. See repository ownership boundaries for the lifecycle and entry point of each area.

License

Apache 2.0

Project links

Data verified by PyPI on Jul 26, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.14.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nikolayer from gravatar.com nikolayer

Credits

Author: Nikolay Eremeev

GitHub Statistics

Data verified by PyPI on Jul 26, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev full mcp tree-sitter

Tags

ai chatgpt claude code-analysis code-context code-review code-to-prompt codebase context context-selection diff-context directory-tree export git-diff json llm llm-context mcp model-context-protocol tree yaml

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

diffctx-1.12.2.tar.gz (257.7 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

diffctx-1.12.2-cp310-abi3-win_amd64.whl (8.6 MB view details)

Uploaded CPython 3.10+Windows x86-64

diffctx-1.12.2-cp310-abi3-manylinux_2_28_x86_64.whl (8.9 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ x86-64

diffctx-1.12.2-cp310-abi3-manylinux_2_28_aarch64.whl (8.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

diffctx-1.12.2-cp310-abi3-macosx_11_0_arm64.whl (8.9 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

File details

Details for the file diffctx-1.12.2.tar.gz.

File metadata

  • Download URL: diffctx-1.12.2.tar.gz
  • Upload date:
  • Size: 257.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for diffctx-1.12.2.tar.gz
Algorithm Hash digest
SHA256 d1c0287b2d2972c47b25b6f5dac563c7a2b9d18392f52811983701c14d9e2017
MD5 c19419560dc4c120c6efe4318ab33c63
BLAKE2b-256 53a32f26fb86eba3de0a4d63c7a3df1a722729d880916ba3d79c57b8660ae338

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.2.tar.gz:

Publisher: cd.yml on nikolay-e/diffctx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file diffctx-1.12.2-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: diffctx-1.12.2-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 8.6 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for diffctx-1.12.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 0a7b66f8f9ee7d06d3fb0d51ce31959acd08e5e79562f29fce301e9423694384
MD5 e242c766dd57ffcff2836a7ee9d3537e
BLAKE2b-256 10b90091111c7d97b58ac7b3526685d851d91553edff65a3a3ea85f796ae71e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.2-cp310-abi3-win_amd64.whl:

Publisher: cd.yml on nikolay-e/diffctx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file diffctx-1.12.2-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for diffctx-1.12.2-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 d8796b4f0322c062d0e4de41b2fe0ea408b2061d081fc2e4e01122b903e11c1e
MD5 1eb1f6993c2e6905e82375fff62a44be
BLAKE2b-256 6ff49d886132b7b27e662237f787f8ae6caaa374269e526d4fbe06f721208c06

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.2-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: cd.yml on nikolay-e/diffctx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file diffctx-1.12.2-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for diffctx-1.12.2-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6ae0ee5a46f311719ed05a18ea606361565b957c87f909476f2afd02b8372d64
MD5 7a0a25d603e56e6ceefde67a9df6754c
BLAKE2b-256 1536d5159ff2f0bf934bbb345be15f839c2a1a6924350f7d40e8d6be49fd0102

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.2-cp310-abi3-manylinux_2_28_aarch64.whl:

Publisher: cd.yml on nikolay-e/diffctx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file diffctx-1.12.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for diffctx-1.12.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 43312cc0553dce57dd63e30a97c9d29c182cef044a27fc1f0753de7a002adece
MD5 6904505f50385f216df288512c49525f
BLAKE2b-256 a26a9333f01d56e9381bf3f27271598eb18af73162569088445b73ddbf440074

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.2-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: cd.yml on nikolay-e/diffctx

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page