deep-diff-forge MCP server
Commit Nov 14, 2026Analyzes code changes by ranking file risk, explaining semantic intent, and providing machine-readable reviews for people and AI agents.
Also known as Louranicas/deep-diff-forge
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is deep-diff-forge MCP?
deep-diff-forge analyzes code changes by ranking file risk, explaining semantic intent, and providing machine-readable reviews for people and AI agents.
Summary generated from the project's README
About deep-diff-forge MCP server
Analyzing code changes by ranking file risk and explaining semantic intent is what deep-diff-forge enables for developers and AI agents. This tool acts as a review engine that treats a diff as a meaningful change rather than just a collection of added or removed lines. It uses tree-sitter to parse source code, allowing it to provide structural insights while ensuring the original patch remains exactly as Git would apply it.
Designed for local, single-user use on Linux and macOS, the server can be accessed via a CLI, a Unix-socket daemon, or as an MCP server. It provides machine-readable outputs through stable JSON and JSONL schemas, making it ideal for integration into automated scripts or agentic workflows. Users can utilize specific tools like review_patch and rank_patch to process changes. The system is built with a focus on safety, refusing to repair incoherent patches and instead returning documented exit codes to maintain patch truth.
What you can do with it
- 1Rank code change risksAn AI agent can identify which files in a large pull request require the most careful scrutiny.
- 2Automate machine-readable reviewsDevelopers can integrate structured code review data into their CI/CD pipelines using JSON output.
- 3Verify patch integrityA script can ensure that a code change is valid and follows strict Git application rules before merging.
- 4Enhance agentic code reviewsAI clients can use the MCP server to gain semantic understanding of a diff to provide better feedback.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablelouranicas/deep-diff-forge is public and reachablegithub.com/louranicas/deep-diff-forge ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/louranicas/deep-diff-forge ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDeep-Diff-Forge
A review engine for code changes. It keeps the patch exactly as Git would apply it, and layers understanding on top that can never corrupt it.
AI writes more of the code we merge, so reviewing a change has become harder than writing
one. Deep-Diff-Forge reads a diff as a review, not a blob of + and - lines. It ranks files
by risk, explains each ranking, parses source with tree-sitter, and serves the same answer
to people, scripts and agents:
- a terminal cockpit;
- a CLI with stable JSON;
- a Unix-socket daemon;
- an MCP server;
- Rust and Python SDKs.
Underneath sits one rule. The apply-able patch is truth, and nothing may rewrite it.
Status: 0.8.3, a security release, released 2026-11-11 (UTC) as the signed tag
v0.8.3. It fixes reviews in v0.8.2 that differed fromgit apply: a name left by a barediff --gitline, a new file's mode overridden bynew mode, and content under a mode Git reads as a submodule (advisory). It also carries three dependency updates (CHANGELOG).
- Declared scope: a local, single-user review tool on Linux and macOS (the exact targets), covering the CLI, daemon,
rpc, MCP and SDKs. All four targets are built and smoke-tested on current CI runners. The oldest OS versions listed are declared from the binaries, not run. The verdict and its evidence are below.- Releases: the latest release is v0.8.3, with Linux (x86_64 and arm64) and macOS binaries, an SPDX SBOM and build provenance.
- crates.io: publication is on hold by decision until the codebase is fully production-hardened.
Contents
- Why Deep-Diff-Forge
- The first principle
- How it works
- Install
- Quick start
- Command reference
- Output formats and schemas
- Exit codes
- MCP server
- SDKs
- The optional daemon
- Verified agent findings
- Benchmarks and evaluation
- Risk ranking
- Architecture
- Quality gates
- Review council and evidence gates
- Project status
- Contributing
- Documentation map
- License
Why Deep-Diff-Forge
Each existing tool optimises one layer of review:
| Tool | Optimises | Limit |
|---|---|---|
diff |
patch truth, exit codes, automation | no semantic or review intelligence |
delta, diff-so-fancy |
readable terminal rendering | line-oriented; pretty is not understanding |
difftastic |
structural (syntax-tree) diffing | its output is not an apply-able patch |
hunk |
review-first terminal UI and agent workflow | an interactive viewer, not a composable engine |
Deep-Diff-Forge makes these layers cooperate. The core is conservative and apply-able; the enrichment on top is ambitious and clearly separate. It is built for people reviewing large, often AI-generated changesets, and for the agents, scripts and CI that drive review more and more.
It is Bash-first and agent-first. Every action:
- has a deterministic command;
- produces machine-readable output (
--json,--jsonl); - returns a documented exit code that names the next action;
- works as a Unix filter, with no daemon required.
| Capability | deep-diff-forge | hunk |
delta |
difftastic |
diff-so-fancy |
diff |
|---|---|---|---|---|---|---|
| Review-first interactive UI | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Inline agent / engine notes | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Deterministic, explained risk ranking | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Versioned JSON / JSONL output | ✅ | ❌ 1 | ❌ | ❌ 2 | ❌ | ❌ |
Input sealing (input_sha256) |
✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| MCP server and SDKs | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Optional daemon (Unix socket) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Apply-able patch preserved | ✅ | ❌ 3 | ✅ 4 | ❌ | ✅ 4 | ✅ |
| Syntax highlighting | ✅ 5 | ✅ | ✅ | ✅ | ❌ | ❌ |
| Structural / token-level diffing | ✅ 6 | ❌ | ❌ | ✅ | ❌ | ❌ |
| Native VCS input | Git 7 | Git · jj · Sapling | ❌ | ❌ | ❌ | ❌ |
| Watch / auto-reload | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Pager / Unix-filter friendly | ✅ | ✅ 8 | ✅ | ✅ | ✅ | ✅ |
1 hunk's agent integration is a live in-session skill, not a schema'd document a script can consume.
2 difftastic has an experimental JSON display; Deep-Diff-Forge ships versioned schemas.
3 hunk renders patches but does not emit an apply-able patch.
4 They re-render a Git diff that stays apply-able.
5 Tree-sitter, terminal-injection-safe. Rust today; more grammars are welcome.
6 Token-level and reformat-aware, with best-effort moved-block detection. difftastic's tree-edit-distance diff is deeper.
7 --git-working-tree, --git-staged and --git-range A..B. deep-diff-forge <old> <new> compares two regular files through the same hardened Git.
8 hunk works as a pager but is a full-screen UI, not a stdout filter.
Comparisons are best effort against each tool's default behaviour. Corrections are welcome.
The first principle
A diff engine must preserve patch truth while exposing semantic intent.
Patch truth is the exact text that can be applied, and it is separate from every enrichment layer. Semantic analysis, risk ranking and agent notes may be absent, partial or wrong, but none of them can change the apply-able patch.
The reverse holds too. An internally incoherent patch is refused, not repaired:
- a hunk whose body disagrees with its
@@ -a,b +c,d @@counts; - a hunk cut off at end of file;
- a header missing its closing
@@; - a
GIT binary patchbody followed by anything but base85 lines; - a file header after the file's first hunk, a
---without its+++, or headers that contradict each other (a new file with old lines, a deleted file that is also renamed). - a rename or copy that names a path
git applyrefuses: absolute, or with a.,..or.gitcomponent; - a mode header that is not octal.
Each fails with exit 4. None is quietly turned into a plausible-looking model.
How it works
- One door to a sealed review. Every review document comes from
deep_diff_forge_patch::SealedReview, whether the patch was piped in or acquired from Git. It decodes the bytes, parses them within a 64 MiB budget in linear time, applies the input contracts, and seals them with SHA-256. This covers the CLI's--json,--rank,--clusterand layouts, the daemon'sdiff.computeanddiff.rank, MCP'sreview_patchandrank_patch, and the SDKs.--jsonlstreams through the pipeline crate under the same parser and contracts, but unsealed.- The cockpit,
diff.planandsession.openuse the same strict parser without a seal. - Git runs with a fixed argv, and paths, modes and blob IDs come from NUL-delimited records.
- One model.
deep-diff-forge-coreholds files, hunks, line anchors, the seal and the tool identity. It has no I/O and no parsing. - Enrichment reads, never writes. Projection, the risk graph, cluster lanes, tree-sitter syntax, agent notes and the learning loop each read the model.
- Every surface tells the same truth. For the same bytes,
--stdin-patch --json, the daemon'sdiff.compute,rpc, the MCPreview_patchtool and the SDK'sreviewproduce the same document, and parity tests prove it.
Install
Prebuilt binaries for Linux (x86_64 and, since v0.6.0, arm64) and macOS (Apple silicon and
Intel) are on the releases page
(supported platforms). The commands below fetch v0.8.3,
the latest release.
Each archive has a .sha256 file, and the release carries an SPDX SBOM:
curl -LO https://github.com/Louranicas/deep-diff-forge/releases/download/v0.8.3/deep-diff-forge-v0.8.3-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/Louranicas/deep-diff-forge/releases/download/v0.8.3/deep-diff-forge-v0.8.3-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c deep-diff-forge-v0.8.3-x86_64-unknown-linux-gnu.tar.gz.sha256
From source (main: 0.8.3, everything in this README). This needs Rust 1.88+ (edition 2024):
git clone https://github.com/Louranicas/deep-diff-forge.git
cd deep-diff-forge
cargo build --release --locked -p deep-diff-forge-cli
target/release/deep-diff-forge --version # deep-diff-forge 0.8.3
target/release/deep-diff-forge --self-test
Supported platforms
These four release targets are the whole platform scope. Each is built by release.yml and its
binary is run (--version and a review) before it ships.
| Target | Built and run on | Needs | Tests on every pull request |
|---|---|---|---|
x86_64-unknown-linux-gnu |
ubuntu-24.04 |
glibc 2.34 or newer | the whole suite (deploy gate-feature, required) |
aarch64-unknown-linux-gnu |
ubuntu-22.04-arm, natively |
glibc 2.34 or newer | the whole suite (Linux arm64 tests, not required; gates releases) |
aarch64-apple-darwin |
macos-26 (arm64) |
macOS 11 or newer | the whole suite (macOS tests, required); the launchd agent (macOS launchd agent, not required; skipped in releases) |
x86_64-apple-darwin |
cross-built on macos-26, run under Rosetta 2 |
macOS 10.12 or newer | none (the release smoke only) |
- The glibc floor, glibc 2.34, is enforced:
scripts/check_glibc_floor.shfails the release smoke when a Linux binary requires a newerGLIBC_symbol version. Measured 2026-10-31: the v0.5.0 x86_64 binary requires at mostGLIBC_2.34; it ran a review on AlmaLinux 9 (glibc 2.34), Ubuntu 22.04 (2.35) and Debian 12 (2.36), and the loader refused it on Debian 11 (2.31). The arm64 binary, built onubuntu-22.04-arm, passes the same check in CI (measured; built onubuntu-24.04-armit neededGLIBC_2.39, PR #79); it has not been run on an older arm64 distribution (unmeasured). - On glibc 2.34 to 2.38 the loader prints one warning line to stderr per run,
weak version `GLIBC_2.39' not found. The output and exit code are unchanged (measured on the three systems above). Rust's standard library referencespidfd_spawnpandpidfd_getpid(glibc 2.39) as optional symbols; glibc 2.39 or newer prints nothing. Building from source on such a system also avoids it. - A source build is for the system that built it. Linked with GNU ld on glibc 2.39 or newer
(a distribution's own Rust package, for example), the binary requires
GLIBC_2.39outright and does not start on an older glibc (measured 2026-11-10: built on Fedora 44, refused by the loader on Ubuntu 22.04). The release smoke holds every Linux release binary to the floor. - macOS minimums are the ones the v0.5.0 binaries declare (
LC_BUILD_VERSIONminos 11.0 for arm64,LC_VERSION_MIN_MACOSX10.12 for x86_64, read 2026-10-31). They are run only on the runner's current macOS, not on those versions. - Not supported: musl (Alpine and other musl distributions) is neither built nor tested: the syntax layer compiles C (tree-sitter), which needs a musl C toolchain, and nothing would run the result. Windows is not supported (the daemon needs Unix domain sockets; the CLI does not compile there). Other architectures and the BSDs are not built or tested.
Optional shortcuts:
alias ddf='deep-diff-forge'
git config --global alias.review '!git diff | deep-diff-forge review'
Quick start
git diff | deep-diff-forge review # the interactive cockpit
git diff | deep-diff-forge --stdin-patch --rank # what to look at first, and why
deep-diff-forge --git-staged --rank # the same, without the pipe
deep-diff-forge --git-range main..HEAD --json # a sealed review document
git diff | deep-diff-forge --stdin-patch --layout side-by-side
deep-diff-forge semantic src/lib.rs # tree-sitter symbols
deep-diff-forge structural old.rs new.rs # reformat-aware diff
deep-diff-forge explain 4 # what an exit code means
For agents: look before you read
An agent should learn where to look before it reads anything large. Register DDF with your
agent and allow the repositories it may read; the agent never has to paste a patch.
agent setup prints the exact registration for this binary and writes nothing:
deep-diff-forge agent setup --client claude --allow-repo ~/code/project # a `claude mcp add …` line
deep-diff-forge agent setup --client codex --allow-repo ~/code/project # a ~/.codex/config.toml block
deep-diff-forge agent doctor # proves MCP, the daemon and the CLI agree on one sealed patch
review_changewithselection: "staged"(orworking_tree, orrangewithA..B) returns the outline: every file in review-risk order with its score, signals and hunks. Each hunk carries its address, line ranges,@@heading and counts, and no line text yet.review_changewithview: "hunks"and theaddressesit cares about returns those hunks verbatim.- Every answer is sealed (
input_sha256) and fitsmax_bytes, 32 KiB by default, both copies counted, as printed (escapes included). Anext_cursorcontinues, and it belongs to that patch and that selection only: a cursor from another patch or selection, or one whose position is outside the selection (no page could have minted it), is refused.
Without --allow-repo, review_outline and review_hunks do the same for a patch the agent
passes. The same views exist on the CLI (--outline, --hunks), on the daemon's socket and
over rpc (review.outline, review.hunks, review.change).
deep-diff-forge --git-staged --outline # where to look
deep-diff-forge --git-staged --hunks --address 44a87108… # read one hunk
git diff | deep-diff-forge --stdin-patch --hunks --path src/lib.rs --max-bytes 8192
For gates and orchestrators, refuse empty or hunkless input so it can't pass as a clean review:
git diff | deep-diff-forge --stdin-patch --rank --json --require-files --require-hunks
Command reference
deep-diff-forge --help is the authoritative list, and deep-diff-forge <command> --help prints one command's usage and what it does, with exit 0. A test runs it for every command --help lists.
Review a change
deep-diff-forge --stdin-patch [MODE] [--require-files] [--require-hunks]
deep-diff-forge {--git-working-tree [--include-untracked] | --git-staged | --git-range A..B} [--repo PATH] [MODE | --acquisition-json]
deep-diff-forge [--] <old> <new> [MODE] [--require-files] [--require-hunks]
# MODE: --json | --jsonl | --rank | --cluster [--parallel N] | --layout inline|side-by-side
# | --outline | --hunks [--address A]... [--path P]... (both: [--max-bytes N] [--cursor C])
Choose one MODE: a second is refused with exit 2 before any input is read. --json also
selects the JSON form of --rank and --cluster (and is accepted, redundantly, with
--outline and --hunks, which always print JSON). An option that takes one value is
refused when given twice; only --address and --path repeat.
| Mode | Output |
|---|---|
| (none) | One line per file: status, path, +adds -dels, hunk count. |
--json |
One deep-diff-forge.review.v0 document: files, hunks, line anchors, summary, seal. |
--jsonl |
One {"event":"diff.file",…} event per file, streamed. |
--rank |
Files by review risk, highest first, with their signals. Add --json for deep-diff-forge.rank.v0. |
--cluster [--parallel serial|auto|N] |
The same ranking through bounded parallel lanes with a deterministic join and a receipt. Add --json for deep-diff-forge.cluster.v0. |
--layout inline / --layout side-by-side |
Text projections with old and new line numbers, as wide as the file's largest. A \ note row follows what a row cannot show: a non-UTF-8 line shown lossily, \ No newline at end of file, and a removed/added pair whose printed text looks the same (a tab against the spaces it advances to, a literal \x1b against a raw ESC, a trailing or no-break space, or in side-by-side a change past the column width). Inline prints tabs raw and judges them by 8-column tab stops; side-by-side shows a tab as four spaces. Letters that only look alike (Cyrillic а against Latin a) are not noted. |
--require-files |
Refuse a patch with 0 files: exit 7, empty stdout, refused: 0 files in input (--require-files). |
--require-hunks |
Refuse a patch with 0 hunks or 0 changed lines (header-only, rename-only, context-only): exit 7, refused: 0 hunks in input (--require-hunks). |
--outline |
deep-diff-forge.review-outline.v0: files in review-risk order, each hunk's address, ranges, @@ heading and counts, no line text. |
--hunks [--address A]... [--path P]... |
deep-diff-forge.review-hunks.v0: the chosen hunks verbatim (all, by address or by path). A long hunk continues at a line (complete: false). |
--max-bytes N · --cursor C |
For --outline / --hunks: the most bytes the answer may take (1 KiB–16 MiB, default 64 KiB), and the next_cursor of the previous page. The page prints as one line of JSON, the daemon's page byte for byte. |
--acquisition-json |
Git input only: the deep-diff-forge.git-acquisition.v0 identity of what Git returned. |
Git selections run Git with a fixed argv and stop it after 120 s (TimedOut, exit 3), so a
stalled filesystem or hook cannot hang the caller. A repository's own content filters (from its
local or worktree configuration and their includes) never run; the user's global and system
filters, such as Git LFS, stay on by decision, and nothing else they configure runs
(SECURITY.md). A filter name that is not UTF-8
refuses the acquisition (InvalidSelection, which exits 2 today, measured 2026-11-01).
Compare two files
deep-diff-forge <old> <new> reviews two regular files: Git writes the patch with
git diff --no-index, and DDF seals those exact bytes and prints any MODE above. Git runs from
/ on the canonical paths, with no attributes file and no CRLF conversion, so neither a
repository around the files nor the user's attributes can run a filter or change the bytes
compared. File headers therefore name the canonical path without its leading /
(a/home/me/old.rs). Put -- first when a path is also a command name
(deep-diff-forge -- doctor notes.txt).
| Refusal | Exit |
|---|---|
A path that does not exist or cannot be inspected (cannot read the old file: …) |
3 |
The path itself is a symbolic link, a directory, or a FIFO, socket or device (old file refused: … is a directory, not a regular file); a linked parent directory is resolved, not refused |
4 |
Git cannot open a file it was given, as when it is removed after the checks (`git diff --no-index` exited with status 1: error: Could not access …) |
3 |
| Two files whose sizes together exceed the 64 MiB input budget, checked before Git reads them | 4 |
| Fewer than two paths, an unknown option, or conflicting modes | 2 |
A first word that is neither a command nor an existing path, without -- (unknown command: …) |
2 |
Directories are out of scope: a tree comparison brings nested repositories, links and special
files with it, which --git-range and the working-tree selections already handle for a
repository. The check and Git's read are separate steps, so a concurrent writer can still
change a file in between; compare files you control. Git's answer is checked too: exit 0 must
come with no patch and exit 1 with one, and anything on Git's stderr is a failure (exit 3), so a
file that vanishes in between is never reviewed as unchanged.
A gate should always pass both guards. When both fail, the files guard reports first.
deep-diff-forge MCP questions
What makes deep-diff-forge different from standard diff tools?
Unlike standard diff tools, it layers semantic understanding and risk ranking on top of the patch without corrupting the original apply-able text.
Does the tool modify the original git patch?
No, the engine follows a first principle where the apply-able patch is treated as truth and enrichment layers are strictly read-only.
What platforms are supported?
It is a local, single-user tool designed for Linux (x86_64 and arm64) and macOS (Apple silicon and Intel).