diffctx — smart diff context for LLM code review

CI PyPI 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

A standalone binary (no Python required) is on the releases page. The [tree-sitter] extra adds AST-level parsing for more accurate context selection across 30+ languages.

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.0.tar.gz (250.6 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.0-cp310-abi3-win_amd64.whl (8.6 MB view details)

Uploaded CPython 3.10+Windows x86-64

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

Uploaded CPython 3.10+manylinux: glibc 2.28+ ARM64

diffctx-1.12.0-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.0.tar.gz.

File metadata

  • Download URL: diffctx-1.12.0.tar.gz
  • Upload date:
  • Size: 250.6 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.0.tar.gz
Algorithm Hash digest
SHA256 77c25edf5a3d789fe099c57eb93a22994e9ea3b646872936ce92dd80dd338eb8
MD5 fad2527c14a7e139ae79b575df13d8a7
BLAKE2b-256 a82d0dacb5b7f435d266e8f3fb5ee3d6d4f6810f4c9155bdf435c4b29c9b2b29

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: diffctx-1.12.0-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.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 784dd36e06d8e917a8fbb5ebbb4ede358782a66aaf0804a2ff2ba3db0c213759
MD5 b8f57da1ef21e2f8324c5e635a1d0718
BLAKE2b-256 cdcb07c31f70a48d22d5e33abe37a3032aed4ff3c1b0cb1fec7549fd1a98a2f7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for diffctx-1.12.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c33000623db6419d60d3fd6d3f244acb1ba5168e9dbd0791641c90b1173ba0f0
MD5 c9601c3811291718ea848b3f358b08d6
BLAKE2b-256 f37c8298a5b7aa86bab77e3c89a7d276f86a0bde4f6a3aec858a47cc36af1b0c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for diffctx-1.12.0-cp310-abi3-manylinux_2_28_aarch64.whl
Algorithm Hash digest
SHA256 6b703a07b351dab5d65584ed7ea27771a0d7475c156dd23f475eb27b06c2aad3
MD5 18a316230a456ae7c067a4d15456cf3f
BLAKE2b-256 9dc39d2a17be26763be83f82049ff13d56f896a6888b92b4238cad813e9d2d8e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for diffctx-1.12.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 13b4e8218880698e7a274af0a7be9b08da8265facb9ce0e88f87c9673bb056ef
MD5 2a95997067275fcb41bcbea5d59d5091
BLAKE2b-256 715ee95488f967332dd72738fad893db38f9820a4db2832b2f0e2f55aea20a90

See more details on using hashes here.

Provenance

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