diffctx — smart diff context for LLM code review

CI PyPI crates.io License

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?

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

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 demo

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.

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/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

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-only diffs list deleted_files/renamed_files and exit 0
130 Interrupted (Ctrl-C)
141 Broken pipe (e.g. piping into head)

License

Apache 2.0

Project links

Data verified by PyPI on Jul 23, 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 23, 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.1.tar.gz (250.2 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.1-cp310-abi3-win_amd64.whl (8.6 MB view details)

Uploaded CPython 3.10+Windows x86-64

diffctx-1.12.1-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.1-cp310-abi3-manylinux_2_28_aarch64.whl (8.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

diffctx-1.12.1-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.1.tar.gz.

File metadata

  • Download URL: diffctx-1.12.1.tar.gz
  • Upload date:
  • Size: 250.2 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.1.tar.gz
Algorithm Hash digest
SHA256 6da21db8c43506a404ddf5aa906b0ffe706e87d4c00dc5726d3c447562bfaba8
MD5 278a55e598550dcb77de3c12b58d5e4e
BLAKE2b-256 2795301bcd060567fc03b6142cfca78094048acb82df8d3168630f58e3c8f879

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.1.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.1-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: diffctx-1.12.1-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.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ff5e81f9530dba90b0e1ebda0d8d25add063138616e17cf1cb06b9eb16f0d81c
MD5 07540f0ec1a822d6fd39cfb2bcfe697a
BLAKE2b-256 02b1367a40b9667a64993f258a44ab2fb927e63d6d41fa93e194143671bb69f2

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.1-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.1-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for diffctx-1.12.1-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 42c31e3fb32be642e713f42fcce42628ca18b69f3dbbb62685c8e6a219b59c92
MD5 f8f979f512b8d819f2793d9a63d1e55f
BLAKE2b-256 871b34a6ad15371439cab5dbbc26658994fe2bdde143b91751d86565d31741f8

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.1-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.1-cp310-abi3-manylinux_2_28_aarch64.whl.

File metadata

File hashes

Hashes for diffctx-1.12.1-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 88ba54931c83b217c479ca71ab066560b14750dca337545f4d47d9489e1cad69
MD5 aab1320e724f9eedb8dcc182e4bf9812
BLAKE2b-256 4fc8a78568812b35bf0514676d5866cf7f4b0f73b3dd35af4c3cf253a8a6f86d

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.1-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.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for diffctx-1.12.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 eb0ac3ae512567a71c5df9aecfef00f2e9ee32f159566b52904b9b7eed905d3e
MD5 db3bc5e19e0c80e3c25992dfc768b26d
BLAKE2b-256 54cdb8465413d897e84d9f5fe4aa5138d1f2035d8968af9c2c1a6316fa475d40

See more details on using hashes here.

Provenance

The following attestation bundles were made for diffctx-1.12.1-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