Skip to main content

system-diff

See what Claude Code is doing to your system while it works, learn your system as it goes, and have a team of agents build it in parallel, block by block.

system-diff is two things:

  1. The System diff pane. 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.
  2. A multi-agent orchestrator for system development. plan_agents splits the work by the system's blocks, one agent per area; the agents run in parallel, claim their blocks, and tell each other what they change over an async bus whose topics are the blocks. The pane's Agents tab shows them live: a lane per agent, its blocks in its colour.

Install

Three steps. First the engine, in a terminal (Python 3.11 or newer):

pip install "system-diff[mcp]"

(or pipx install "system-diff[mcp]"). Then, in Claude Code:

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

and restart Claude Code. The pane opens beside the chat, and the same views open in your browser.

The pane sits beside the chat in Claude Code's fullscreen layout (from 110 columns wide). Where it opens above the chat instead (Windows, tmux), 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, and the pane finds system-diff through python -m system_diff too.

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

The plugin brings everything, in every session and every project:

  • The System diff pane beside the chat. Claude Code opens it by itself when the terminal is wide enough; /system-diff opens it again, /system-diff close hides it, /system-diff tui opens the same in a terminal of its own.
  • The same views in your browser, at http://localhost:8765/: started with each session, linked in the pane.
  • The hooks that follow what Claude reads and edits, ask it to plan a team, and carry the agents' messages.
  • The MCP server Claude uses to explain the system, show what changed and plan a team, and its skill.

Where the engine comes from. The plugin uses, in order: a project's own .venv with system-diff in it (a project that pins it), then the system-diff you installed (pip install "system-diff[mcp]" or pipx). Where there is none, the pane says how to install it, and the hooks stay quiet and never hold a session up.

Other ways in. From a clone, claude --plugin-dir mods/system-diff loads the plugin for one launch. Without the plugin, system-diff setup claude wires the hooks, the skill and the MCP server into Claude Code by hand. Upgrading from a version before the plugin carried the hooks: run system-diff setup claude --undo (with --scope local or project where you set it up there), so they do not run twice. Should another marketplace you added also have a plugin called system-diff, /plugin install system-diff@system-diff names this one.

You get both features at once:

  • The pane shows what Claude does to the system and teaches you the parts it touches (below).
  • The orchestrator has Claude plan a team for each prompt that spans the system's blocks: agents run in parallel, each on its own blocks, talking over the bus, and the pane's Agents tab shows them as they work (see A team of agents).

The System diff pane

A tab beside Claude Code's own file diff: your system drawn the way a system designer draws it, live, with what Claude is changing in it. /system-diff close (or "× close" in its tab row) hides it; /system-diff brings it back.

  • Now follows Claude, in the order your attention needs it:
    • What Claude is doing ("● Claude is working ✎ Editing API") and what you asked.
    • WORTH A LOOK: the few changes most worth understanding, ranked by consequence (a new outside system, stored data, an entry point, a new dependency or a boundary crossed, a part added or removed). Each says in plain words why it matters and what it touches, lit in the diagram; the rest are in Review.
    • You asked … → changed …: your request beside the parts it changed, and the changed parts it did not name.
    • OBJECTIVES: what you keep asking Claude for, learned from your requests (below).
    • The system diagram:
      • What it draws: who uses the system (people, programs, AI agents), where they come in, the containers that do the work with their components inside, and the data and outside systems it relies on. Flows join them, named for what they carry (HTTPS, MCP, SQL, a terminal).
      • Colours: Claude's component is lit in blue; what this turn added is green, changed yellow, removed red.
      • Pick: click the diagram, then ← ↑ ↓ → picks a box. Its flows in and out light up with the boxes at their other ends, and a line says what it uses and what uses it.
      • Zoom: Enter (or a second click) zooms in on a container's components, with the lines between them. b goes back, f follows Claude again.
      • Scroll: [ ] scroll a wide diagram across; shift ↑ ↓, Page Up/Down or the wheel scroll a tall one.
      • Zoom: ⊖ and ⊕ in the tab row (or - and =) draw the diagrams compact (narrower boxes, no flow labels) or tiny (titles only), to fit more of the system in a narrow pane; below 110 columns it is compact by itself.
    • This turn: each change to the design, and what it trades off.
    • Learn: how the part Claude works on is designed.
      • The principle its place calls for: an edge of the system, an adapter, a shared foundation, a coordinator.
      • Where it sits, and what to watch, such as cycles and layering.
      • The basics of a technology only where it is new: new to the system this turn, or one you marked new to you.
    • What just happened: the system diff, step by step. Each change an edit made is said in plain words, with why it matters and the file it came from. Edits that changed no structure are told once.
  • Review: everything you have not marked as seen, across turns: the system diagram since your checkpoint with its changes coloured, every block to pick and zoom into, then every change read for design and the exact list. 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. Before you have marked anything, it starts from before your last commit, and lists the parts whose code changed even when their structure did not.
  • Agents: the team at work. A lane per agent in its own colour, live: time runs left to right since the turn began, with a mark where it read (◎), edited (✎), changed the system (▲) or told the others something (✉), then what it is doing now and how many of its blocks it has touched. Pick an agent to light its blocks; the system diagram draws each agent's blocks in its colour, with @agent after them; the bus, newest first; and a warning when two agents edit one block, or one edits a block claimed for another.
  • Topics: the stack, technology by technology. Pick one and the parts that use it light up in the diagram (pick a block in the diagram and the technologies it uses light up); space marks it new to you, so Learn explains its basics.

One meaning per colour, so your eye goes where it should:

  • Blue: 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.

n r a t switch views.

History: how the system got here

h: History lists how the system changed, newest first, each step said as what you asked and what it got: "2 days ago · You asked: “add document uploads to flows” → it got: a call to Amazon S3, 3 endpoints under /flows/documents". Pick one for every change and why it matters; ↵ shows it on the diagram. h on any box shows that box's own history. It is recorded as Claude works (your requests come from the hooks, or from Claude Code's own session history) and read back from the last 50 commits; kept in .git/system-diff/history.jsonl. system-diff history [--part id] prints it.

What you are optimising for: objectives

While you iterate with Claude you keep asking for the same things ("fast on large repositories", "must work on Windows"). system-diff learns these from your requests, in the background with the LLM your Claude Code uses (only your requests are read, never code), and keeps them as objectives: (The LLM is the gateway your Claude Code uses, or the claude command itself, so Bedrock, Vertex and subscriptions work; SYSTEM_DIFF_LLM=off turns every LLM use off.)

  • shown in the pane, the web page and the terminal view, each with how often you asked and its evidence on hover;
  • given to Claude with every request, and to every agent of a team in its brief, so later iterations keep them;
  • marked on changes that touch one; and, when agents test or measure one, their verdict (holds, broken) shows next to it and in the Agents tab (the check_objective MCP tool).

x on an objective clears it, if it is wrong. system-diff objectives lists them (clear, restore, learn). They are kept in .git/system-diff/objectives.json: on your machine, never committed. SYSTEM_DIFF_OBJECTIVES=0 turns the learning off.

How it stays fast

One engine per repository (the web page's server, started by the first view that needs it) keeps the system in memory. Claude's edits reach it from the hooks as they happen, other edits through a look at file times (in Python, no git), and only the files that changed are read again: a page is about 0.1 s, an edit shows within a second or two. It runs git a handful of times when it starts and not per look, which matters where starting a program is slow. Each file's reading is kept by its content, so every branch and worktree reuses it. Each branch keeps its own checkpoint (what you have seen there). system-diff doctor times a look on your machine and says what is slow.

In a browser

The same views (Now, Review, Agents, Topics) as a web page at http://localhost:8765/, on your machine only (in a GitHub Codespace, forward the port: gh codespace ports forward 8765:8765 -c <codespace> on your own computer, or VS Code's Ports panel). The session-start hook starts it in the background; system-diff watch starts it by hand. Hover a block to pick it and light its flows, click to zoom in. The pane shows the link in its tab row (🌐) while it runs. [web] start = false in system-diff.toml turns the start with the session off. A Send to Claude box sends what you type to the live session, through the pane, as your own message; only the page system-diff serves can send.

In a separate terminal

The same views in a terminal tab or window of their own, beside Claude Code: system-diff tui (or system-diff tui --view review) in the project. It draws the pane's own page with the pane's keys: ← ↑ ↓ → pick a block, Enter zooms in, b goes back, f follows Claude, n r a t switch views, [ ] scroll across, shift+↑ ↓ and Page Up/Down scroll down, - = zoom, q quits. From Claude Code, /system-diff tui opens one where it can (a tmux window, Windows Terminal, macOS Terminal, a Linux desktop's terminal) and always answers with the command to run in a new terminal. Standard library only, on Linux, macOS and Windows.

A team of agents, by the system's blocks

Claude does most work alone unless asked otherwise, so system-diff asks it to plan a team:

  • Planning: at each prompt, the hook tells Claude to call plan_agents with the task. The plan splits the task by the system's blocks, one agent per area it touches (a container, else a part). Each agent gets the blocks it owns (claimed for it), the blocks it depends on, and a brief to launch it with. Claude then launches the agents in parallel as subagents. Turn this off with [agents] orchestrate = false in system-diff.toml.
  • The bus: an async publish/subscribe channel whose topics are the blocks. Each agent follows the blocks its own depend on. Every change an agent makes to a block's structure is published on that block's topic as it happens ("API no longer answers DELETE /orders/{id}"), with why it matters. Agents publish their own notes with publish (to a block, to "all", or to "agent:"). Each agent's unread messages reach it with its next tool result of any kind (a read, an edit, a shell command, a search), once: nobody waits on anybody.
  • Claims: claim gives an agent its blocks. An edit to someone else's block is published to its owner and shown under Needs your attention.
  • One agent, one area: when an agent (the main conversation included) edits blocks in two or more areas in one turn, the edit hook tells it, once that turn, to plan a team with plan_agents and hand the rest to agents.

The MCP tools: plan_agents, claim, publish, subscribe, inbox, team. It all stays in .git/system-diff/ (agents.json, bus.jsonl), never pushed.

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.
  • Messages from other agents on the bus arrive with an agent's next tool result of any kind, not only after an edit.
  • 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, 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.

License

MIT

Metadata

Release files for system-diff 0.8.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.8.0
File Size Uploaded Provenance Actions
system_diff-0.8.0.tar.gz 393.9 kB With provenance Details for system_diff-0.8.0.tar.gz

Built distribution (wheel)

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

Total release size: 705.3 kB

Release files / system_diff-0.8.0.tar.gz

Download URL system_diff-0.8.0.tar.gz
Size 393.9 kB
Tags Source
SHA-256 checksum
How to use checksums
47fb19fbf2aedf5308c920b26b1e370b413690e4139d87563090256c19ee1594
BLAKE2b-256 checksum
How to use checksums
619646c6575fca3b4e469e4e93f676122c0a61ec280cd8f82a598e4b34c74256
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 12, 2026.

Transparency log

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

Download URL system_diff-0.8.0-py3-none-any.whl
Size 311.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a2100c79f1d5ebfe7cc1db54fd471fd48e2143e49921fee245c45925173b940
BLAKE2b-256 checksum
How to use checksums
ac985947d4384e6ba524e63fb5d7658113b9f6b5d21b22631b7380b525464364
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 12, 2026.

Transparency log

Security for system-diff 0.8.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.8.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 12, 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