git diff for knowledge graphs.
See what changed between two versions of a graph — and review it like a pull request.
Try it in your browser · Get started · Docs · Website · 中文
AI systems now write and rewrite knowledge graphs: GraphRAG pipelines, agent memories, ontology assistants, semantic layers. Someone has to review those changes. Text diffs show triples appearing and disappearing; most visual tools recolor nodes on a fresh force layout, so everything jumps. kgdiff shows what actually happened — a merge, a rename, a class moved under a new parent, a relation that now points somewhere else — on one stable map, in a viewer built for review.
npx @kgdiff/cli before.ttl after.ttl -o report.html --openOr install nothing: the playground diffs the example datasets, or two files of your own, in your browser. Nothing is uploaded.
Two releases of a schema.org-style vocabulary, in Turtle.
This is what git can tell you:
$ git diff --no-index --stat before.ttl after.ttl
before.ttl => after.ttl | 68 +++++++++++++++++++++++++++++++++++++++----------
1 file changed, 54 insertions(+), 14 deletions(-)and this is what kgdiff tells you, one line per decision a reviewer has to make (the node ids are cut out here to fit):
$ kgdiff before.ttl after.ttl --name-status | cut -f1,3
G Merged “Code” into “Software source code”
G Merged “employees” into “employee”
E Added “Review” —itemReviewed→ “Thing”
M Updated synonyms of “Corporation”
M Updated attributes of “Dataset”
M Updated attributes of “Event”
R Renamed “NGO” → “Non-governmental organization”
R Renamed “Scholarly artcle” → “Scholarly article”
A Added “Food establishment”, “Cafe or coffee shop” and 2 relations
V Moved “Restaurant” under “Food establishment”
M Edited “serves cuisine”
A Added “Social media posting”, “Discussion forum posting” and 2 relations
V Moved “Blog posting” under “Social media posting”
A Added “Virtual location” and 2 relationsG merged, R renamed, V moved, E relations, M modified, A added. The same graph
written as N-Triples, with its statements in another order or its prefixes renamed, diffs as
identical: kgdiff compares graphs, not files.
- Semantic, not syntactic. Nodes are matched across versions — by id, by replacement hints
such as OBO
replaced_by, or by label and neighbourhood when ids mean nothing, as in two LLM extraction runs — and every change gets a name: rename, rekey, types, synonyms, attributes, deprecation, hierarchy move, merge, split, retarget, predicate change. - One mental map. Both versions share one deterministic, label-aware layout. Nothing moves unless it changed; removed things stay where they were, as hollow ghosts.
- Color is meaning. Five families and nothing else — added, removed, content, structure, identity — plus gray for context. Every color has a non-color cue too, and a color-blind-safe palette is built in.
- Review is a workflow. Changes are grouped into hunks in dependency order. Step through them, replay the before → after morph, mark them reviewed, and export the invertible delta.
npx @kgdiff/cli v12.json v13.json # colored summary
npx @kgdiff/cli old.obo new.obo --stat # diffstat
npx @kgdiff/cli a.ttl b.ttl -o report.html # single-file interactive report, works offline
npx @kgdiff/cli a.ttl b.ttl --exit-code -q # exit 1 when the graphs differkgdiff is a native program for macOS, Linux (glibc and musl) and Windows. npx needs
Node.js ≥ 22 and installs the binary for your machine. Without Node.js, the same binary comes
from PyPI as pykgdiff (the command line only), or build it with cargo install kgdiff:
pipx install pykgdiff # or: uv tool install pykgdiff, pip install pykgdiff
uvx --from pykgdiff kgdiff a.ttl b.ttl # run it without installingEvery option: CLI reference. With git diff and git difftool:
Use kgdiff with git.
jobs:
kgdiff:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write # the comment
steps:
- uses: actions/checkout@v7
- uses: iiwish/kgdiff@v0
with:
files: ontology/*.ttlThe action compares each file with its version on the base branch, writes the summary into the job summary and into a pull request comment that later pushes update in place, and uploads the interactive report as an artifact. Pull requests from forks get the job summary and the report. Options, several graphs, failing the check: Review changes in CI.
<kgdiff-viewer theme="auto" locale="en" style="height: 640px"></kgdiff-viewer>
<script type="module">
import '@kgdiff/viewer';
const viewer = document.querySelector('kgdiff-viewer');
await viewer.load({
before: { text: await (await fetch('v1.ttl')).text(), filename: 'v1.ttl' },
after: { text: await (await fetch('v2.ttl')).text(), filename: 'v2.ttl' },
});
</script>Three ways to compare — Overlay, Swipe (drag a divider between before and after) and Replay (the old graph morphs into the new one, hunk by hunk) — each with or without Changes only; a searchable change list, a detail panel with character-level diffs, review progress, deep links, keyboard shortcuts, light and dark themes, English and Chinese. Use the whole viewer, or compose your own layout from its elements. Behaviour and events: Viewer: interaction and API.
import { diff, formatHunk, parseGraph } from '@kgdiff/core';
const before = (await parseGraph(beforeText, { filename: 'v1.obo' })).graph;
const after = (await parseGraph(afterText, { filename: 'v2.obo' })).graph;
const result = await diff(before, after);
for (const hunk of result.hunks) console.log(formatHunk(hunk, result, 'en').title);
// Merged “juvenile diabetes” and “insulin-dependent diabetes mellitus” into “type 1 diabetes mellitus”
// Merged “heart attack” into “myocardial infarction”
// …npm install @kgdiff/core is all it takes. The engine is written in Rust; in JavaScript it runs
as WebAssembly (@kgdiff/compute, loaded on the first call), with the same bytes out as the CLI.
Use the engine in code ·
Embed kgdiff in a Rust application ·
Migrating to 0.11.
| Family | Symbol | Changes |
|---|---|---|
| added | + |
new nodes and their relations |
| removed | − |
deleted nodes and their relations |
| content | ~ |
renames, types, synonyms, attributes, deprecation |
| structure | ⇄ |
moves in a hierarchy, retargeted relations, predicate changes |
| identity | ⊕ ⑂ |
merges, splits and id changes, from replacement hints or inferred |
Pairs of nodes kgdiff was not sure enough about are not matched: they are listed as possible matches, in the summary and in the viewer, for you to check. How it decides: How kgdiff tells changes apart, and the exact rules in Algorithms.
| You work with… | Start here |
|---|---|
| Ontology releases (OBO, OWL) | Ontologies: OBO and OWL |
| LLM and GraphRAG extractions, ids that mean nothing | Graphs without stable ids |
| Graph files kept in git | Use kgdiff with git · Review changes in CI |
| A product that shows graph changes to its users | Embed the viewer · Embed in a Rust application |
| A graph drawn with AntV G6 | Browse a graph with G6 · @kgdiff/g6 |
| Patches between versions | Deltas: apply and invert · Delta format · Versioning |
| Family | Formats |
|---|---|
| RDF | Turtle, N-Triples, N-Quads, TriG, RDF/XML (.rdf, .owl from Protégé / ROBOT), JSON-LD 1.1 (inline contexts; nothing is fetched) — labels by language preference, OWL existential restrictions as edges, blank nodes identified by content and context, statement annotations folded |
| OBO | OBO 1.4 — synonyms, is_a, relationships, obsoletion with replaced_by, alt_id |
| JSON | kgdiff native, d3 / NetworkX node-link, Cytoscape.js, AntV G6 v5, graphology, vis-network; GraphML (NetworkX, igraph, yEd, LightRAG) and GEXF (Gephi, NetworkX), read as node-link data |
The format is detected from the file name and the content. Mapping conventions: Formats. Missing yours? Request a format.
| Text diff | Ontology diff tools (ROBOT diff, …) | kgdiff | |
|---|---|---|---|
| Names merges, splits, renames, moves | lines added and removed | axiom- or entity-level, some renames | yes, grouped into hunks |
| Ignores serialization (order, prefixes, blank nodes) | no | axiom-level | yes, on a normalized graph model |
| Any graph, not only OWL | any text | OWL | RDF, OBO and JSON graph formats |
| Both versions on one stable map | — | text, tables or trees | yes, with replay |
| Review workflow | line by line in a PR | reports | hunks, reviewed state, keyboard |
| Invertible patch | git apply -R |
varies | yes, hash-checked |
kgdiff does not reason over OWL axioms: for axiom-level review, run robot diff alongside it
(Limits).
-
Deterministic. The same inputs give byte-identical diffs, deltas, layouts and reports (
--reproducibledrops the report's timestamp). CI checks that layouts hash the same on Linux, macOS, Windows and in WebAssembly. -
Invertible.
apply(A, diff(A, B).delta) ≅ B, and the inverse delta restoresA; applying hunks one by one in review order always succeeds. Property-tested with fast-check. -
One engine. The CLI, the libraries, the viewer and the playground run the same Rust code. A conformance corpus generated by the Rust crates is checked by the TypeScript read path on every commit, and every example dataset runs through the whole pipeline against the changes it should produce.
-
Measured (Apple M5, kgdiff 0.11; WebAssembly under Node 24 unless marked native):
What Time diff, 10k nodes / 30k edges ≈ 0.14 s (native: 30 ms) diff, 100k nodes / 300k edges, native ≈ 0.47 s parse 50k Turtle triples ≈ 0.11 s layout of a 10k-node diff (changes scope) ≈ 0.5 s visual resolution per frame, 5k nodes < 1 ms The standalone viewer is ≈ 119 kB gzip and carries no WebAssembly; the engine (≈ 390 kB gzip) loads only when something has to be computed. Every figure, with the targets still missed: RFC 0002, Phase 5 results.
Most people need one. It depends only on what you want to do:
| You want to… | Install |
|---|---|
| Compare graph files in the terminal or in CI | @kgdiff/cli (npx @kgdiff/cli a.ttl b.ttl), or the GitHub Action |
| … with Python tools, without Node.js | pykgdiff from PyPI (pipx install pykgdiff): the same kgdiff |
| Show a diff in a web page, without rendering code | @kgdiff/viewer (the <kgdiff-viewer> web component) |
| Compute diffs in your code, draw them yourself | @kgdiff/core and @kgdiff/compute, plus layout, scene or g6 |
| Embed the engine in a Rust application | the crates kgdiff-core, kgdiff-layout, kgdiff-report |
All packages and crates
| npm | |
|---|---|
@kgdiff/cli |
The command-line tool: installs and runs the native kgdiff of your platform. |
@kgdiff/viewer |
The <kgdiff-viewer> web component and the elements it is made of. |
@kgdiff/core |
Diff model: parseGraph, diff, JSON transports, invertible delta, hunk titles. |
@kgdiff/compute |
kgdiff's Rust engine in WebAssembly: diff, parsers, layout. |
@kgdiff/layout |
Deterministic, label-aware union layout; anchored and changes-only modes. |
@kgdiff/scene |
Diff semantics → visual primitives: design tokens, encodings, replay timeline, focus. |
@kgdiff/renderer |
Canvas 2D engine: smooth camera, LOD, label placement, picking, swipe, minimap. |
@kgdiff/g6 |
Render kgdiff scenes inside AntV G6 v5 graphs. |
| crates.io | |
|---|---|
kgdiff |
The command line, also usable as a library behind an I/O trait. |
kgdiff-core |
Matching, change classification, hunks and invertible deltas. |
kgdiff-formats |
The parsers: RDF, OBO and the JSON graph formats. |
kgdiff-layout |
The stable layout of a graph and of a diff, the layout document. |
kgdiff-report |
Terminal summary, --stat, Markdown, report payload and HTML reports. |
Also: the GitHub Action (action.yml, uses: iiwish/kgdiff@v0) and the
website with the playground (apps/site). @kgdiff/cli brings its platform
package (@kgdiff/cli-darwin-arm64, @kgdiff/cli-linux-x64-gnu, …) with it: never install
those yourself. Every npm package and crate of a release has the same version number.
| Start | What is kgdiff? · Getting started · FAQ |
| Guides | CI · git · Ontologies · LLM graphs · Matching · Viewer · Library · Rust |
| Reference | CLI · Formats · Viewer API · Viewer elements · Delta format |
| Concepts | Architecture · Algorithms · Visual language · RFCs |
The same documentation, in English and Chinese, is published at iiwish.github.io/kgdiff/docs.
0.11 (2026-11-12) moved all computing onto the Rust engine: the CLI natively, everything
else through @kgdiff/compute. 0.12 (2026-11-13) prepared the public API for growth: the Rust
API makes room for additions that need no breaking release, and the JavaScript API keeps only
what is documented (Migrating to 0.12).
kgdiff is 0.x, and 1.0 has no date. Before 1.0 the versions follow Cargo's convention: the second number is the major's part and the third the minor's. A patch release (0.12.x) carries fixes and additions, breaks no public API and changes no output byte; breaking changes wait for the next minor (0.13) and are gathered into one release (Versioning). 1.0 comes when all of these hold:
- At least one real host (Semlia) has run on the current version for about a month.
- The experimental APIs have been used by a host, and are made stable or fixed.
- The Python API is settled, or kgdiff states that only the command line is promised.
- The viewer's accessibility review (#16) is done.
- About two minor releases, or a month, have passed without a breaking change.
After 1.0 a patch release only fixes, a minor release only adds, and a major one may break. The experimental APIs, designed for embedding hosts, stay experimental until a host has used them (RFC 0002, Versioning).
What comes next. kgdiff stays on 0.x for a good while and improves there; nothing below waits for 1.0. Patch releases come on Tuesdays, and on Thursdays when a fix that users run into or an addition a host is waiting for is ready; a security fix comes at once. A breaking minor release comes no more often than about every six to eight weeks, with a migration guide. The plan by release, which the needs of the first host may reorder:
- 0.12.x, fixes and additions: shell completions, GraphML and GEXF input (0.12.2) · what embedding hosts asked of the scene and of the G6 adapter, and fixes from an audit of diff and apply (0.12.3 and after) · native binaries on GitHub releases and a Homebrew formula.
- 0.13, may break: what a graph holds about direction, large numeric ids and edge identity ·
the embedding interface of the
kgdiffcrate (CliIo) in Rust's idiom andDiffResultbehind accessors. - Later, in no fixed order: size and speed · a Python API and Jupyter (#14) · an MCP server, so agents can review the graph edits they make (#13) · KGCL and RDF Patch export · Cytoscape.js and Sigma.js adapters · three-way merge with conflict visualization · a Web Worker pipeline and a WebGL renderer for very large graphs · the plain view of one graph and groups in the layout (RFC 0003, parts 4c and 4d), when a host asks for them.
The working list, with what waits for what and why, is docs/roadmap.md. Follow along, or pick something up, in the roadmap issue.
Bug reports, format requests, guides and code are all welcome. Good places to start are the issues labelled good first issue and help wanted; questions and ideas go to Discussions.
pnpm install # Node.js ≥ 22, pnpm 11
pnpm --filter @kgdiff/compute build:wasm # the engine's WebAssembly, once and after changes under crates/
pnpm check # lint + typecheck + tests
cargo test --workspace # the Rust crates
pnpm dev:site # landing page and playground
cargo run -p kgdiff -- examples/datasets/enterprise-kg-en/before.json \
examples/datasets/enterprise-kg-en/after.jsonRead CONTRIBUTING.md first (the WebAssembly build needs a few tools), then Architecture. Please follow the code of conduct, and report vulnerabilities privately as SECURITY.md describes.
If you use kgdiff in research, please cite it: GitHub's Cite this repository button reads CITATION.cff.
MIT. The example datasets are CC0.


