Skip to main content

system-diff

See what Claude Code is doing to your system while it works, and learn your system as it goes.

Claude Code edits files; system-diff tells you what those edits do to the system: which part Claude is working on and what that part is, the endpoints, connections, stored data and outside systems it adds, changes or removes, why each of those matters, and when one needs you to look before Claude goes on. Right in Claude Code, beside the chat. So you follow what is happening, learn the parts and the technology behind them, and steer Claude well when it asks.

System map, generated from the code

How this map is made

Regenerated by system-diff from the code: the parts and their columns from system-diff.toml, the connections from imports, API calls and the settings each part reads, the outside systems from the settings a deploy configuration sets, and the tables from the migrations. Parts used everywhere are drawn without the arrows into them, and each part keeps only its strongest connections; system-diff map writes all of them to system.json.

Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).

In Claude Code

pipx install "system-diff[mcp,tui]"
system-diff setup claude --no-status-line   # the hooks, a skill and the MCP server (--scope project, --undo)

Then, in Claude Code, the System diff pane:

/plugin marketplace add simplifiedmachine/system-diff
/plugin install system-diff

Python 3.11 or newer. Claude Code opens the pane by itself when the terminal is wide enough; /system-diff opens it again after you close it. (Should another marketplace you added also have a plugin called system-diff, /plugin install system-diff@system-diff names this one.) From a clone, claude --plugin-dir mods/system-diff loads it for one launch. Upgrading from an earlier version: run system-diff setup claude again; it updates the hooks it added before, and frees /system-diff for the pane.

The System diff pane

A tab beside Claude Code's own file diff: the system diff, live, in four views.

  • Now follows Claude, top to bottom in the order your attention needs it:
    • What Claude is doing and what that part is: "● Claude is working ✎ Editing API · an entry point: where people, other programs or AI tools reach the system", and what you asked.
    • ▲ Needs your attention, only when something does: an endpoint removed or added, stored data changed, a new outside system, a part removed. Each with why it matters ("whatever called it now gets an error"). The moment to ask Claude why, or steer it.
    • This turn: every change to the system as a sentence ("API now uses Billing") with its reason in gray ("a change in Billing can now break API").
    • The part, zoomed in on: a diagram of what calls it and what it calls, its own endpoints and settings, what changed marked. Click it, then ← ↑ ↓ → pick a block and Enter zooms in on it, as far as you want to walk the system; b goes back, f follows Claude again, Esc hands the keys back.
    • About the part: what it is and does, what is changing in it and why that matters.
    • What just happened: › what you asked, ◎ what Claude read, ✎ what it edited, ▲ what each step did to the system, ✓ when it finished.
    • Learn: a topic behind the part, a new one every 20 seconds: the technologies its code imports (FastAPI, SQLAlchemy, React, subprocesses, threads…) and the ideas behind its role (entry points, layers, migrations, coupling…), in plain words.
  • Map: the whole system, a row of blocks per column (what people use, entry points, logic, data access, stored data, outside systems); the same keys pick and zoom in.
  • Changes: exactly what changed since your checkpoint, and this turn. Once you have understood it, tell Claude "mark it as seen" (or run system-diff checkpoint): from then on you see only what is new to you.
  • Topics: everything the system is built with, and which parts use each.

One meaning per colour, so your eye goes where it should: blue is where Claude is and what you picked, yellow what changed and what needs you, green what is new, done or to learn, white what to read, gray the background (why, when, labels), red only what was taken away. Keys while the pane has the focus (ctrl+x tab, or a click): n m c t switch views.

In the conversation

  • After an edit that changes the system's structure, one line under it: "System diff: API now answers GET /health · a new way in: it needs the same checks as the others". Edits that change no structure stay quiet.
  • At the end of each turn, one line on what the turn did to the system, or which parts it edited when the structure stayed the same; nothing for a turn that only talked.
  • Ask Claude "what is the API part?" or "what does this change do?": the MCP server gives it explain (the facts to teach from, and a diagram to show you), system_diff (the exact list of changes; base: turn for this turn only), system_map, draw (pictures of a process or a sequence of calls) and checkpoint (mark what you have seen, so the next diff shows only what is new to you).

The pane and the hooks send nothing anywhere: the working tree is read as a snapshot (untracked files included) without touching your index, HEAD or branches; the checkpoint and the start of each turn live under refs/worktree/system-diff/ (each worktree its own, for Claude sessions in parallel), and what the hooks note under .git/system-diff/, never pushed. Only the optional lessons you ask an LLM for (e in the terminal view, diff --narrate) go to your own LLM, and they carry the structure, never the code.

Configuration

With no config, every folder of code is a part named by its path. A system-diff.toml at the repository root names the parts and says what is what:

tests = ["tests/**"]

[code]
roots = ["app/", "web/src/"]

[[components]]
id = "api"
label = "API"
kind = "interface"          # ui | interface | logic | data: the column it is drawn in
paths = ["app/api/**"]

[[externals]]
id = "postgres"
label = "PostgreSQL"
shape = "db"
env = ["DATABASE_URL"]      # the settings that reach it

Every key, and how the code is read: the wiki.

Add-ons

The same engine, outside the pane. Deterministic: the same code gives the same picture, byte for byte, and a part that did not change keeps its place.

  • Pull requests: every pull request gets its system diff as a comment, and CI fails when the README's map is out of date (.github/workflows/system-diff.yml, which you can copy). This repository runs it on itself.
  • Command line:
    system-diff map --dir . --out docs/diagrams          # the system as it is now: system.json, system.svg
    system-diff diff --base origin/main --out out        # what this branch does to it: headline, plan, diff.svg
    system-diff diff --base HEAD --head . --out out      # what your uncommitted work does to it
    system-diff readme --json docs/diagrams/system.json  # keep the map in README.md current
    system-diff show API                                 # one part zoomed in, and what it is, in any terminal
    system-diff draw SPEC.json                           # hand-made pictures in the same look
    
    diff --narrate adds a plain-words summary from your own LLM; [png] adds PNG output.
  • Terminal view (system-diff tui): the pane's views as a full-screen terminal app, for a terminal beside any agent. It opens by itself next to Claude Code in tmux, zellij, WezTerm, kitty and Windows Terminal; in VS Code, setup adds a task that opens it with the folder.
  • Status line (system-diff setup claude without --no-status-line): the pane's first lines under Claude Code's prompt, for when the pane is not open.
  • Browser page (system-diff watch): the same with the SVG pictures, at http://127.0.0.1:8765/.

License

MIT

Metadata

Release files for system-diff 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for system-diff 0.2.0
File Size Uploaded Provenance Actions
system_diff-0.2.0.tar.gz 119.9 kB With provenance Details for system_diff-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for system-diff 0.2.0
File Interpreter ABI Platform Actions
system_diff-0.2.0-py3-none-any.whl Python 3 none any Details for system_diff-0.2.0-py3-none-any.whl

Total release size: 226.5 kB

Release files / system_diff-0.2.0.tar.gz

Download URL system_diff-0.2.0.tar.gz
Size 119.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5e905787f957626bbc174bf160bddd3eb82e0bd7d3cffce3c7e494d41293c170
BLAKE2b-256 checksum
How to use checksums
fba77fbe2ebe2efa72640cc7cc707be751359e839af63e340c9f9bb930d97243
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / system_diff-0.2.0-py3-none-any.whl

Download URL system_diff-0.2.0-py3-none-any.whl
Size 106.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
920116dfc73879a11bc4d0c1c553203818c15fbac3d5fd5ec0246e55f1456dbb
BLAKE2b-256 checksum
How to use checksums
5ccbb22a9530ab38d6db7c1cef7996645d85d289c3e1cb657600c9064fab57db
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for system-diff 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for system_diff-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page