diffctx 1.12.3 → 1.14.0

package/README.md

@@ -10,25 +10,16 @@
 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`](https://pypi.org/project/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 | ✗ | ✗ | ✗ | ✓ |
-
-Fuller positioning — measured results, and when a whole-repo packer or a
-persistent code-graph server fits better: [COMPARISON.md](COMPARISON.md).
+> 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](COMPARISON.md).
 
 ## Install
 
@@ -54,18 +45,11 @@ scoop bucket add diffctx https://github.com/nikolay-e/diffctx
 scoop install diffctx/diffctx
 ```
 
-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](https://github.com/nikolay-e/diffctx/releases/latest).
-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](https://docs.rs/diffctx)).
+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
 
@@ -87,21 +71,24 @@ 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.
+
 | 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) |
+| `--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); `rrf` = reciprocal-rank fusion of `ego` and `bm25` (widest recall, no scale calibration between the two signals) |
 | `--budget`  | auto    | Hard cap in o200k_base tokens (see [Token counting](docs/product/token-budget.md)): `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) |
+| `--tau`     | 0.05    | 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 |
 | `--with-raw-diff` | false | Also embed git's raw unified diff ahead of the selected fragments — additive (selection unchanged), not charged to `--budget`, lock/ignored/secret-like sections omitted. Python CLI only |
-
-Calibration of `--alpha`, `--tau`, and the edge-weight priors:
-[`docs/engineering/parameter-strategy.md`](docs/engineering/parameter-strategy.md).
-Theory:
-[diffctx: Budgeted Typed-Graph Retrieval for Diff-Aware Code Context
-Selection (Zenodo, 2026)](https://doi.org/10.5281/zenodo.18824579).
+| `--mode` | `pack` | `locate` emits the same ranked selection as compact `diffctx.locate.v1` JSON — path, lines, score, provenance reasons, a blast-radius `summary` and per-item impact `group` (`test`/`type`/`config`), NO source bodies. Adds a `coverage` block naming what the run could not see (`unparsed_files`, `zero_edge_files`, `ppr_truncated`, `next_up`, a heuristic `confidence`) and an `overflow` ranking of what the budget left behind — omitted entirely when there is nothing to disclose. `diffctx . --diff --mode locate` = impact of your uncommitted change. The MCP tool takes it as `mode="locate"` |
 
 ### `graph` subcommand
 
@@ -130,23 +117,20 @@ diffctx . -i custom.ignore                # custom ignore patterns
 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
 ```
 <!-- END USAGE -->
 
 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>`.
-
-Counts come from tiktoken's `o200k_base` encoder and are exact only for the
-GPT-4o family; Claude, Gemini and others tokenize differently, so treat
-`--budget` as an upper bound in o200k tokens and leave headroom. Details:
-[`docs/product/token-budget.md`](docs/product/token-budget.md).
+(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](docs/product/token-budget.md)). Unreadable files
+become placeholders like `<binary file: N bytes>`.
 
 ## Python API
 
@@ -159,7 +143,7 @@ ctx = build_diff_context(
     "HEAD~1..HEAD",
     budget_tokens=None,       # None = auto; 0 = strict-zero floor (empty); -1 = uncapped; N = hard cap
     alpha=0.6,
-    tau=0.12,
+    tau=0.05,
     full=False,
     scoring_mode="ego",
     timeout=300,
@@ -181,19 +165,36 @@ print(to_yaml(tree))
 
 ## MCP server
 
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.nikolay--e%2Fdiffctx-blue)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.nikolay-e/diffctx)
+[![diffctx MCP server](https://glama.ai/mcp/servers/nikolay-e/diffctx/badges/score.svg)](https://glama.ai/mcp/servers/nikolay-e/diffctx)
+
 diffctx includes an [MCP](https://modelcontextprotocol.io) 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:
+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](https://docs.astral.sh/uv/)):
 
 ```bash
-claude mcp add diffctx -- diffctx-mcp
+# 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"]}'
 ```
 
-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:
+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`. Tool reference and JSON configs for Claude
+Desktop, Cursor, Continue, Windsurf, and Zed:
 [`src/diffctx/mcp/README.md`](src/diffctx/mcp/README.md).
 
 ## Ignore patterns
@@ -212,19 +213,10 @@ which are filtered even without an ignore entry.
 
 ## 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.
+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
 
@@ -239,14 +231,6 @@ its share of the cap, oldest entries first.
 | `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](docs/architecture/repository-layout.md)
-for the lifecycle and entry point of each area.
-
 ## License
 
 Apache 2.0
@@ -265,6 +249,8 @@ Apache 2.0
   `--budget` means for non-GPT models
 - [Comparison](COMPARISON.md) — measured results, and when a whole-repo packer
   or a persistent code-graph server fits better
+- [Paper](https://doi.org/10.5281/zenodo.18824579) — budgeted typed-graph
+  retrieval for diff-aware context selection (Zenodo, 2026)
 - [Changelog](CHANGELOG.md)
 - [Security policy](SECURITY.md) — threat model and vulnerability reporting
 - [Parameter strategy](docs/engineering/parameter-strategy.md) — how `--alpha`,

package/checksums.json

@@ -1,6 +1,6 @@
 {
-  "diffctx-1.12.3-aarch64-apple-darwin.tar.gz": "d62da2cd29e08130dc82936080d0b5734dc91bf392b9d7beb7696d7869bbd56c",
-  "diffctx-1.12.3-aarch64-unknown-linux-gnu.tar.gz": "a064e1edf242ddd448d8ed12445dacdcc32c5084ee82c62d54854e3b6b15abca",
-  "diffctx-1.12.3-x86_64-pc-windows-msvc.zip": "daf1064d4a4983305812443f79cb9a3d350c53468a513a127a4d5f079a19489c",
-  "diffctx-1.12.3-x86_64-unknown-linux-gnu.tar.gz": "83019a9eb2fa8a49eaa7999f5f6f9d88c72a88719c6ab456135ef0ed38f6f7fa"
+  "diffctx-1.14.0-aarch64-apple-darwin.tar.gz": "20223d07e8f304b631eff3556386564918037359dbbf12c2ca18335381c129fd",
+  "diffctx-1.14.0-aarch64-unknown-linux-gnu.tar.gz": "3922b1460a1f5e8f4f79a2c7c2dcc3d3da5dc9a9174719b44bf936cf57b86a6a",
+  "diffctx-1.14.0-x86_64-pc-windows-msvc.zip": "07b67a9da0c4331f75bb821ba3404bce349ca6c8063ff5f412c30dcc993bc6bf",
+  "diffctx-1.14.0-x86_64-unknown-linux-gnu.tar.gz": "2125f363fae2439162e4403e20bc90bc366bed098332c32714867273376b38a1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "diffctx",
   "mcpName": "io.github.nikolay-e/diffctx",
-  "version": "1.12.3",
+  "version": "1.14.0",
   "description": "Selects the minimum code an LLM needs to review a git diff",
   "keywords": [
     "git",