Skip to main content

system-diff

git diff shows you lines. system-diff shows you what Claude just did to your system.

PyPI CI Python License: MIT

The System diff: your system drawn as a designer would, live, with where Claude is working

AI agents now write code faster than any person can read it. One prompt, forty files changed, three hundred lines of output, and a question at the end: "Shall I go on?" You say yes, because you can't tell. You are still in the loop, but you are steering blind.

system-diff keeps the human in the loop at the level that matters: the system. While Claude Code works, it shows the system the way a designer draws it (who uses it, where they come in, the parts inside, the data and outside systems they rely on) and what each change does to it, in plain words: a new call to Amazon S3, three new endpoints, the API now reaching the database directly, past the logic layer. What matters most comes first, with why it matters. So you know what you are saying yes to.

The vision

Version control gave us a history of text. As more of our software is written by agents, we need a history of design: what changed in the system, who asked for it, which agent did it, and whether it still holds what we care about. system-diff is a step towards that: a living, visual model of your system that every agent's work is measured against, that you can read in a glance, and that teaches you as it goes.

The future we are building for: people design, agents build, and nobody loses the plot. Teams of agents working in parallel on different blocks of a system, the person seeing all of it at once, the system's history told request by request. If that future excites you, come build it with us.

What you see

Now
Now: the system, where Claude is working, and what is worth a look, ranked by consequence, each with why it matters.
Review
Review: everything since you last looked: added, changed and removed, on the diagram.
Agents
Agents: a team of agents building in parallel, each on its own blocks, in its own colour, talking over a bus.
Topics
Topics: the stack, technology by technology; pick one and the parts that use it light up.

And History: how the system got here, step by step, as "You asked: “add document uploads” → it got: a call to Amazon S3, three endpoints under /flows/documents", for the whole system or any one block.

It lives in a pane beside the chat in Claude Code, in your browser at http://localhost:8765/, and in a terminal of its own (system-diff tui). All three show the same live picture.

Install

  1. The engine (Python 3.11+):
    pip install "system-diff[mcp]"        # or: pipx install "system-diff[mcp]"
    
  2. The plugin, in Claude Code:
    /plugin marketplace add simplifiedmachine/system-diff#stable
    /plugin install system-diff
    
  3. Restart Claude Code, and type /system-diff to open the pane beside the chat. system-diff follows the system from the start of every session either way (the web page shows it); /system-diff autostart on (or /config) opens the pane with each session.

Stable and nightly. The commands above install the latest stable release (PyPI, and the plugin from the stable branch). To test what is coming, run nightly from main: pip install "system-diff[mcp] @ git+https://github.com/simplifiedmachine/system-diff@main" and /plugin marketplace add simplifiedmachine/system-diff. Bugs found there are very welcome as issues.

Windows, tmux, and a pane that opens above the chat

The pane sits beside the chat in Claude Code's fullscreen layout (110+ columns). Where it opens above the chat instead, turn that layout on, then open a new terminal and start Claude Code again:

setx CLAUDE_CODE_NO_FLICKER 1                                    # Windows (PowerShell or cmd)
echo 'export CLAUDE_CODE_NO_FLICKER=1' >> ~/.bashrc              # macOS and Linux (~/.zshrc for zsh)

On Windows, python -m pip install "system-diff[mcp]" works where pip is not on PATH. The plugin's MCP server is started as system-diff mcp, directly (no shell), so the system-diff command must be on PATH: pip prints where it put it (Python's Scripts folder) if that is not. If anything is slow or quiet, python -m system_diff doctor says why: how long starting a program takes there, how long the hooks took, and why the engine last stopped.

In Claude Code

  • The pane: n Now · r Review · a Agents · t Topics · h History. Arrows pick a block (its connections light up), Enter zooms in, b goes back, f follows Claude. /system-diff close hides it, /system-diff tui opens it in a terminal of its own.
  • In the chat: one line under an edit that changes the system's structure, and one at the end of the turn.
  • Ask Claude "what is the API part?" or "what did this change do to the system?": it answers from system-diff's MCP tools, with a diagram.
  • Teams of agents: for work that spans the system, Claude plans a team with plan_agents, one agent per block; they claim their blocks and tell each other what they change over a bus. Watch them in the Agents tab.
  • Objectives: system-diff learns what you keep asking for ("fast on large repos", "must work on Windows"), shows it, keeps it in front of Claude and every agent, and marks changes that touch it. x clears one you disagree with.

Everything stays on your machine, under .git/system-diff/: never committed, never sent anywhere. The only exception is the optional LLM features (regrouping the diagram, learning objectives), which send structure, never code, to the LLM your own Claude Code already uses. SYSTEM_DIFF_LLM=off turns them off.

Several projects

Each repository gets its own engine, on the first free port from 8765 (the first project you open is on 8765, the next on 8766, and so on, up to 8774), and keeps serving only its own repository. The web page shows a row of project tabs on top, one per running engine, with its branch and a dot when it changed since you last looked; a tab is a plain link to that project's own page, in the same view ([ and ] switch). system-diff hub prints one address that lists every running project (http://localhost:8765/projects/page while an engine runs there); bookmark it. Engines list themselves in a folder of your own (~/.local/state/system-diff/engines/, ~/Library/Application Support/system-diff/engines/ on macOS, %LOCALAPPDATA%\system-diff\engines\ on Windows), without their tokens, and remove themselves when they stop.

How it works

  • A resident engine per repository keeps your system in memory: parts, entry points, connections, settings, stored data and outside systems, read from the code (Python and TypeScript/JavaScript today: FastAPI, Flask, Express, Next.js, React, Vue, Svelte, SQLAlchemy, Alembic, Prisma, compose files…).
  • Edits arrive as events: Claude's from its hooks, everyone else's from file times. Only changed files are read again, and git is read directly in Python, so a look takes about 0.1 s and an edit shows within a second, even in large repositories on slow machines.
  • Changes are ranked by consequence (outside systems and data first, internals last) and said in plain words.
  • Deterministic: the same code gives the same picture, byte for byte. The LLM only ever adds names and groupings, labelled as its proposals.

The design principles are in docs/design.md.

Configuration

With no config, system-diff makes a first picture from the code:

  • Parts: every folder of code is a part named by its path; tests and build tooling are left out.
  • Front end: a front end goes under What people use, and the paths it calls are matched to the endpoints that answer them.
  • Data and outside systems: databases and outside services are found from the compose file and the client libraries the code imports; tables from the migrations and the models.
  • Who uses it: a front end's people, an API's callers, an MCP server's AI agents, a command line's developer.

A system-diff.toml at the repository root names the parts and says what is what:

tests = ["tests/**"]

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

[[actors]]                  # who uses the system, drawn first
id = "customers"
label = "Customers"
uses = ["web:browser"]      # part: what the flow carries

[[components]]
id = "api"
label = "API"
kind = "interface"          # ui | interface | logic | data: the column it is drawn in
group = "Backend"           # the container it is drawn in, with the others of its group
about = "orders and payments"
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.
  • 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.
  • Web page by hand (system-diff watch): the pane's views in a browser, at http://localhost:8765/, without Claude Code.

Roadmap

Where system-diff is going, also as a board: system-diff roadmap. Every item is an issue: comment on it to take it on, or open a new one. Good places to start are labelled good first issue.

Next: reach more systems

Next: run well everywhere

Improve system-diff's own design

Then

Later

Contributing

system-diff is young, and the most useful things it could do haven't been built yet. Contributions of every size are welcome: a bug report with the doctor's output, a new language, a better diagram layout, a sharper explanation of a change, documentation, ideas.

  • Report a bug: open an issue with what you did, what you expected, what happened, your OS and versions, and the output of python -m system_diff doctor. Screenshots of the pane or the web page help a lot.
  • Suggest a feature: open an issue describing the problem it solves for you, or pick one from the roadmap.
  • Send a pull request: read CONTRIBUTING.md for the setup (a two-minute pip install -e ".[dev]"), how the code is laid out, and what a good PR looks like: tests with it, CI green on Linux and Windows, and the system map regenerated (system-diff map --dir . --out docs/diagrams). Your PR's comment shows what it does to system-diff's own design.

Good first issues are labelled good first issue.

License

MIT. See LICENSE.

Metadata

Release files for system-diff 0.9.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.9.0
File Size Uploaded Provenance Actions
system_diff-0.9.0.tar.gz 2.0 MB With provenance Details for system_diff-0.9.0.tar.gz

Built distribution (wheel)

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

Total release size: 2.4 MB

Release files / system_diff-0.9.0.tar.gz

Download URL system_diff-0.9.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
08235c9fd171140ecf69569dc812de49eed03dc55b63e52418ade3556bd8735e
BLAKE2b-256 checksum
How to use checksums
7f44b5d62fd563e25bbdb9ac1a7dc30b084c64bb755ccb85c97853db8b29e567
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 17, 2026.

Transparency log

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

Download URL system_diff-0.9.0-py3-none-any.whl
Size 409.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
95b92db88975a28eb8874b9fc488680fbdbacbe522ccb500777bdec7778e3c9b
BLAKE2b-256 checksum
How to use checksums
4c8f297f031310e625ff1839f16ba481fcf9010da2679a601f0a4b0d45bfbfac
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 17, 2026.

Transparency log

Security for system-diff 0.9.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.9.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 17, 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