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
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
- The engine (Python 3.11+):
pip install "system-diff[mcp]" # or: pipx install "system-diff[mcp]"
- The plugin, in Claude Code:
/plugin marketplace add simplifiedmachine/system-diff#stable /plugin install system-diff - Restart Claude Code, and type
/system-diffto 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:
nNow ·rReview ·aAgents ·tTopics ·hHistory. Arrows pick a block (its connections light up), Enter zooms in,bgoes back,ffollows Claude./system-diff closehides it,/system-diff tuiopens 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.
xclears 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 --narrateadds a plain-words summary from your own LLM;[png]adds PNG output. - Status line (
system-diff setup claudewithout--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
- Read language-agnostic system files (OpenAPI, GraphQL, compose, Kubernetes, Terraform, SQL, .env) (#1)
- Go support (#2) · good first issue
- Java/Kotlin (Spring) support (#3)
- Add your language: a guide and a plug-in point for new languages (#4)
- Better diagrams for large systems (#5)
- Record how each connection was found, with a confidence (#26)
Next: run well everywhere
- Hooks on Windows without sh (#6)
- system-diff stop, and an idle timeout for engines (#7) · good first issue
- History in the terminal view (#8) · good first issue
- Follow renames through history (#9)
- macOS in CI (#10) · good first issue
Improve system-diff's own design
- The engine as the single source of truth (#11)
- Layers, enforced by a test (system-diff checking its own design) (#12)
- One view model, three renderers (split pane.py) (#13)
- The web app as real files (#14) · good first issue
- One background-job runner (#15)
- One state store for .git/system-diff/ (#16)
- One schema for the page format (#17)
- Graph tools for agents over MCP: find, neighbours, path, impact (#27)
Then
- Other coding agents: Cursor, Codex CLI, Gemini CLI, Aider (#18)
- Guardrails from objectives (#19)
- Export to C4/Mermaid, and import a target architecture (#20)
- Team mode: share objectives, checkpoints and history (#21)
Later
- Replay a session (#22)
- Design reviews in pull requests (#23)
- Monorepos and multi-repo systems (#24)
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.