system-diff

Draws your system from its code (parts, entry points, data, outside systems) and what each change adds, changes or removes. No dependencies; SVG pictures for PRs and READMEs.

What it does

• map: reads a commit straight from git (no checkout) or a folder, and writes system.json (everything it found) and system.svg (the picture): a column per role, from what people use through entry points, logic and data access to stored data and outside systems.
• diff: the typed difference between two commits, or a commit and your working tree: parts, endpoints, connections, outside systems, tables, settings and deployment files added, changed or removed. One sentence (headline.txt), the exact list (plan.txt, like terraform plan), and a picture of only what changed, with the parts it touches beside it (diff.svg). --narrate adds a plain-words summary from your own LLM.
• readme: keeps a generated system map in your README, between two markers.
• draw: hand-made pictures in the same look, from small JSON specs: maps, stages of a process, sequences.

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

Install

pipx install system-diff

Python 3.11 or newer, nothing else. pip install "system-diff[png]" adds PNG output through Playwright; system-diff png also uses Docker when it is there.

Use

system-diff map --dir . --out docs/diagrams          # the system as it is now
system-diff diff --base origin/main --out out        # what this branch does to it
system-diff diff --base HEAD --head . --out out      # what your uncommitted work does to it
system-diff readme --json docs/diagrams/system.json  # refresh the map in README.md

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.

In pull requests

This repository runs system-diff on itself: the map above is regenerated from its own code, CI fails when it is out of date, and every pull request gets its system diff as a comment (.github/workflows/system-diff.yml, which you can copy).

With AI coding agents

When an agent changes the code with you, the question is what it did to the system. system-diff answers it as you go:

pipx install system-diff
pipx inject system-diff mcp  # the MCP server's one dependency
system-diff setup claude     # the hook, a skill and the MCP server, in one step (--scope project, --undo)
system-diff watch            # http://127.0.0.1:8765/ : the system diff since you last marked it seen

• After every Claude Code turn, one line says what changed in the system since your checkpoint ("Adds 1 endpoint (DELETE /api/orders/{id}); changes 1 table (public.orders)."), or nothing when nothing structural did.
• The live page redraws as files change. Press Mark as seen once you have understood it: the next diff then shows only what is new to you. system-diff checkpoint does the same from the terminal.
• The MCP server gives the agent system_diff (the exact plan to explain from, and the picture), system_map, draw (pictures of processes and sequences in the same look) and checkpoint.
• The working tree is read as a snapshot (untracked files included) without touching your index, HEAD or branches, and the checkpoint lives under refs/system-diff/, in your clone only.

License

MIT