system-diff 0.1.0__tar.gz → 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- system_diff-0.2.0/.claude-plugin/marketplace.json +16 -0
- system_diff-0.2.0/PKG-INFO +175 -0
- system_diff-0.2.0/README.md +143 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/docs/diagrams/system.json +166 -24
- {system_diff-0.1.0 → system_diff-0.2.0}/docs/diagrams/system.svg +60 -9
- system_diff-0.2.0/mods/system-diff/.claude-plugin/plugin.json +11 -0
- system_diff-0.2.0/mods/system-diff/hooks/diagram.tsx +182 -0
- system_diff-0.2.0/mods/system-diff/hooks/hooks.json +1 -0
- system_diff-0.2.0/mods/system-diff/hooks/pane.test.tsx +139 -0
- system_diff-0.2.0/mods/system-diff/hooks/register.tsx +233 -0
- system_diff-0.2.0/mods/system-diff/types/index.d.ts +33 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/pyproject.toml +3 -2
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/__init__.py +1 -1
- system_diff-0.2.0/src/system_diff/activity.py +247 -0
- system_diff-0.2.0/src/system_diff/agent.py +417 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/cli.py +80 -5
- system_diff-0.2.0/src/system_diff/companion.py +164 -0
- system_diff-0.2.0/src/system_diff/compare.py +183 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/config.py +9 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/diff.py +16 -1
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/extract.py +28 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/graph.py +128 -2
- system_diff-0.2.0/src/system_diff/learn.py +439 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/mcp_server.py +56 -22
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/narrate.py +14 -7
- system_diff-0.2.0/src/system_diff/panel.py +247 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/sources.py +8 -0
- system_diff-0.2.0/src/system_diff/statusline.py +94 -0
- system_diff-0.2.0/src/system_diff/textmap.py +313 -0
- system_diff-0.2.0/src/system_diff/topics.py +230 -0
- system_diff-0.2.0/src/system_diff/tui.py +388 -0
- system_diff-0.2.0/src/system_diff/watch.py +341 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/system-diff.toml +42 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/tests/conftest.py +8 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/tests/test_checkpoint_watch_mcp.py +9 -8
- system_diff-0.2.0/tests/test_terminal_and_learning.py +493 -0
- system_diff-0.1.0/PKG-INFO +0 -131
- system_diff-0.1.0/README.md +0 -102
- system_diff-0.1.0/src/system_diff/agent.py +0 -197
- system_diff-0.1.0/src/system_diff/compare.py +0 -105
- system_diff-0.1.0/src/system_diff/watch.py +0 -177
- {system_diff-0.1.0 → system_diff-0.2.0}/.gitattributes +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/.github/workflows/ci.yml +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/.github/workflows/release.yml +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/.github/workflows/system-diff.yml +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/.gitignore +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/LICENSE +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/__main__.py +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/pictures.py +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/png.py +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/src/system_diff/readme.py +0 -0
- {system_diff-0.1.0 → system_diff-0.2.0}/tests/test_system_diff.py +0 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "system-diff",
|
|
3
|
+
"owner": {
|
|
4
|
+
"name": "simplifiedmachine"
|
|
5
|
+
},
|
|
6
|
+
"metadata": {
|
|
7
|
+
"description": "system-diff for Claude Code: see what Claude is doing to your system as it works, and learn it as you go."
|
|
8
|
+
},
|
|
9
|
+
"plugins": [
|
|
10
|
+
{
|
|
11
|
+
"name": "system-diff",
|
|
12
|
+
"source": "./mods/system-diff",
|
|
13
|
+
"description": "A System diff pane beside the chat: what Claude is doing to your system as it works, what needs your attention, a diagram to walk with the arrow keys, and topics to learn."
|
|
14
|
+
}
|
|
15
|
+
]
|
|
16
|
+
}
|
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: system-diff
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: 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.
|
|
5
|
+
Project-URL: Homepage, https://github.com/simplifiedmachine/system-diff
|
|
6
|
+
Project-URL: Documentation, https://github.com/simplifiedmachine/system-diff/wiki
|
|
7
|
+
Project-URL: Issues, https://github.com/simplifiedmachine/system-diff/issues
|
|
8
|
+
Author: simplifiedmachine
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: architecture,code-review,code-visualization,developer-tools,diagrams,pull-requests,system-design
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
18
|
+
Classifier: Topic :: Software Development :: Documentation
|
|
19
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Provides-Extra: dev
|
|
22
|
+
Requires-Dist: mcp>=1.10; extra == 'dev'
|
|
23
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
24
|
+
Requires-Dist: textual>=1.0; extra == 'dev'
|
|
25
|
+
Provides-Extra: mcp
|
|
26
|
+
Requires-Dist: mcp>=1.10; extra == 'mcp'
|
|
27
|
+
Provides-Extra: png
|
|
28
|
+
Requires-Dist: playwright>=1.40; extra == 'png'
|
|
29
|
+
Provides-Extra: tui
|
|
30
|
+
Requires-Dist: textual>=1.0; extra == 'tui'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# system-diff
|
|
34
|
+
|
|
35
|
+
**See what Claude Code is doing to your system while it works, and learn your system as it goes.**
|
|
36
|
+
|
|
37
|
+
Claude Code edits files; system-diff tells you what those edits do to the *system*: which part Claude is working on
|
|
38
|
+
and what that part is, the endpoints, connections, stored data and outside systems it adds, changes or removes, why
|
|
39
|
+
each of those matters, and when one needs you to look before Claude goes on. Right in Claude Code, beside the chat.
|
|
40
|
+
So you follow what is happening, learn the parts and the technology behind them, and steer Claude well when it asks.
|
|
41
|
+
|
|
42
|
+
<!-- system-map:begin -->
|
|
43
|
+

|
|
44
|
+
|
|
45
|
+
<details><summary>How this map is made</summary>
|
|
46
|
+
|
|
47
|
+
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`.
|
|
48
|
+
|
|
49
|
+
Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).
|
|
50
|
+
|
|
51
|
+
</details>
|
|
52
|
+
<!-- system-map:end -->
|
|
53
|
+
|
|
54
|
+
## In Claude Code
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
pipx install "system-diff[mcp,tui]"
|
|
58
|
+
system-diff setup claude --no-status-line # the hooks, a skill and the MCP server (--scope project, --undo)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then, in Claude Code, the System diff pane:
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
/plugin marketplace add simplifiedmachine/system-diff
|
|
65
|
+
/plugin install system-diff
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Python 3.11 or newer. Claude Code opens the pane by itself when the terminal is wide enough; `/system-diff` opens
|
|
69
|
+
it again after you close it. (Should another marketplace you added also have a plugin called system-diff,
|
|
70
|
+
`/plugin install system-diff@system-diff` names this one.) From a clone, `claude --plugin-dir mods/system-diff`
|
|
71
|
+
loads it for one launch. Upgrading from an earlier version: run `system-diff setup claude` again; it updates the
|
|
72
|
+
hooks it added before, and frees `/system-diff` for the pane.
|
|
73
|
+
|
|
74
|
+
### The System diff pane
|
|
75
|
+
|
|
76
|
+
A tab beside Claude Code's own file diff: the *system* diff, live, in four views.
|
|
77
|
+
|
|
78
|
+
- **Now** follows Claude, top to bottom in the order your attention needs it:
|
|
79
|
+
- **What Claude is doing** and what that part is: "● Claude is working ✎ Editing API · an entry point: where
|
|
80
|
+
people, other programs or AI tools reach the system", and what you asked.
|
|
81
|
+
- **▲ Needs your attention**, only when something does: an endpoint removed or added, stored data changed, a new
|
|
82
|
+
outside system, a part removed. Each with why it matters ("whatever called it now gets an error"). The moment to
|
|
83
|
+
ask Claude why, or steer it.
|
|
84
|
+
- **This turn**: every change to the system as a sentence ("API now uses Billing") with its reason in gray ("a
|
|
85
|
+
change in Billing can now break API").
|
|
86
|
+
- **The part, zoomed in on**: a diagram of what calls it and what it calls, its own endpoints and settings, what
|
|
87
|
+
changed marked. **Click it, then ← ↑ ↓ → pick a block and Enter zooms in on it**, as far as you want to walk the
|
|
88
|
+
system; `b` goes back, `f` follows Claude again, Esc hands the keys back.
|
|
89
|
+
- **About the part**: what it is and does, what is changing in it and why that matters.
|
|
90
|
+
- **What just happened**: › what you asked, ◎ what Claude read, ✎ what it edited, ▲ what each step did to the
|
|
91
|
+
system, ✓ when it finished.
|
|
92
|
+
- **Learn**: a topic behind the part, a new one every 20 seconds: the technologies its code imports (FastAPI,
|
|
93
|
+
SQLAlchemy, React, subprocesses, threads…) and the ideas behind its role (entry points, layers, migrations,
|
|
94
|
+
coupling…), in plain words.
|
|
95
|
+
- **Map**: the whole system, a row of blocks per column (what people use, entry points, logic, data access, stored
|
|
96
|
+
data, outside systems); the same keys pick and zoom in.
|
|
97
|
+
- **Changes**: exactly what changed since your checkpoint, and this turn. Once you have understood it, tell Claude
|
|
98
|
+
"mark it as seen" (or run `system-diff checkpoint`): from then on you see only what is new to you.
|
|
99
|
+
- **Topics**: everything the system is built with, and which parts use each.
|
|
100
|
+
|
|
101
|
+
One meaning per colour, so your eye goes where it should: **blue** is where Claude is and what you picked, **yellow**
|
|
102
|
+
what changed and what needs you, **green** what is new, done or to learn, **white** what to read, **gray** the
|
|
103
|
+
background (why, when, labels), **red** only what was taken away. Keys while the pane has the focus (ctrl+x tab, or a
|
|
104
|
+
click): `n` `m` `c` `t` switch views.
|
|
105
|
+
|
|
106
|
+
### In the conversation
|
|
107
|
+
|
|
108
|
+
- **After an edit that changes the system's structure**, one line under it: "System diff: API now answers GET
|
|
109
|
+
/health · a new way in: it needs the same checks as the others". Edits that change no structure stay quiet.
|
|
110
|
+
- **At the end of each turn**, one line on what the turn did to the system, or which parts it edited when the
|
|
111
|
+
structure stayed the same; nothing for a turn that only talked.
|
|
112
|
+
- **Ask Claude** "what is the API part?" or "what does this change do?": the MCP server gives it `explain` (the facts
|
|
113
|
+
to teach from, and a diagram to show you), `system_diff` (the exact list of changes; `base: turn` for this turn
|
|
114
|
+
only), `system_map`, `draw` (pictures of a process or a sequence of calls) and `checkpoint` (mark what you have
|
|
115
|
+
seen, so the next diff shows only what is new to you).
|
|
116
|
+
|
|
117
|
+
The pane and the hooks send nothing anywhere: the working tree is read as a snapshot (untracked files included)
|
|
118
|
+
without touching your index, HEAD or branches; the checkpoint and the start of each turn live under
|
|
119
|
+
`refs/worktree/system-diff/` (each worktree its own, for Claude sessions in parallel), and what the hooks note under
|
|
120
|
+
`.git/system-diff/`, never pushed. Only the optional lessons you ask an LLM for (`e` in the terminal view, `diff
|
|
121
|
+
--narrate`) go to your own LLM, and they carry the structure, never the code.
|
|
122
|
+
|
|
123
|
+
## Configuration
|
|
124
|
+
|
|
125
|
+
With no config, every folder of code is a part named by its path. A `system-diff.toml` at the repository root names the
|
|
126
|
+
parts and says what is what:
|
|
127
|
+
|
|
128
|
+
```toml
|
|
129
|
+
tests = ["tests/**"]
|
|
130
|
+
|
|
131
|
+
[code]
|
|
132
|
+
roots = ["app/", "web/src/"]
|
|
133
|
+
|
|
134
|
+
[[components]]
|
|
135
|
+
id = "api"
|
|
136
|
+
label = "API"
|
|
137
|
+
kind = "interface" # ui | interface | logic | data: the column it is drawn in
|
|
138
|
+
paths = ["app/api/**"]
|
|
139
|
+
|
|
140
|
+
[[externals]]
|
|
141
|
+
id = "postgres"
|
|
142
|
+
label = "PostgreSQL"
|
|
143
|
+
shape = "db"
|
|
144
|
+
env = ["DATABASE_URL"] # the settings that reach it
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Every key, and how the code is read: [the wiki](https://github.com/simplifiedmachine/system-diff/wiki).
|
|
148
|
+
|
|
149
|
+
## Add-ons
|
|
150
|
+
|
|
151
|
+
The same engine, outside the pane. Deterministic: the same code gives the same picture, byte for byte, and a part
|
|
152
|
+
that did not change keeps its place.
|
|
153
|
+
|
|
154
|
+
- **Pull requests:** every pull request gets its system diff as a comment, and CI fails when the README's map is out
|
|
155
|
+
of date (`.github/workflows/system-diff.yml`, which you can copy). This repository runs it on itself.
|
|
156
|
+
- **Command line:**
|
|
157
|
+
```sh
|
|
158
|
+
system-diff map --dir . --out docs/diagrams # the system as it is now: system.json, system.svg
|
|
159
|
+
system-diff diff --base origin/main --out out # what this branch does to it: headline, plan, diff.svg
|
|
160
|
+
system-diff diff --base HEAD --head . --out out # what your uncommitted work does to it
|
|
161
|
+
system-diff readme --json docs/diagrams/system.json # keep the map in README.md current
|
|
162
|
+
system-diff show API # one part zoomed in, and what it is, in any terminal
|
|
163
|
+
system-diff draw SPEC.json # hand-made pictures in the same look
|
|
164
|
+
```
|
|
165
|
+
`diff --narrate` adds a plain-words summary from your own LLM; `[png]` adds PNG output.
|
|
166
|
+
- **Terminal view** (`system-diff tui`): the pane's views as a full-screen terminal app, for a terminal beside any
|
|
167
|
+
agent. It opens by itself next to Claude Code in tmux, zellij, WezTerm, kitty and Windows Terminal; in VS Code,
|
|
168
|
+
setup adds a task that opens it with the folder.
|
|
169
|
+
- **Status line** (`system-diff setup claude` without `--no-status-line`): the pane's first lines under Claude Code's
|
|
170
|
+
prompt, for when the pane is not open.
|
|
171
|
+
- **Browser page** (`system-diff watch`): the same with the SVG pictures, at http://127.0.0.1:8765/.
|
|
172
|
+
|
|
173
|
+
## License
|
|
174
|
+
|
|
175
|
+
MIT
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# system-diff
|
|
2
|
+
|
|
3
|
+
**See what Claude Code is doing to your system while it works, and learn your system as it goes.**
|
|
4
|
+
|
|
5
|
+
Claude Code edits files; system-diff tells you what those edits do to the *system*: which part Claude is working on
|
|
6
|
+
and what that part is, the endpoints, connections, stored data and outside systems it adds, changes or removes, why
|
|
7
|
+
each of those matters, and when one needs you to look before Claude goes on. Right in Claude Code, beside the chat.
|
|
8
|
+
So you follow what is happening, learn the parts and the technology behind them, and steer Claude well when it asks.
|
|
9
|
+
|
|
10
|
+
<!-- system-map:begin -->
|
|
11
|
+

|
|
12
|
+
|
|
13
|
+
<details><summary>How this map is made</summary>
|
|
14
|
+
|
|
15
|
+
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`.
|
|
16
|
+
|
|
17
|
+
Read by the code but set by no deploy configuration, so not drawn: Headless Chromium (Docker or Playwright) (png).
|
|
18
|
+
|
|
19
|
+
</details>
|
|
20
|
+
<!-- system-map:end -->
|
|
21
|
+
|
|
22
|
+
## In Claude Code
|
|
23
|
+
|
|
24
|
+
```sh
|
|
25
|
+
pipx install "system-diff[mcp,tui]"
|
|
26
|
+
system-diff setup claude --no-status-line # the hooks, a skill and the MCP server (--scope project, --undo)
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Then, in Claude Code, the System diff pane:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
/plugin marketplace add simplifiedmachine/system-diff
|
|
33
|
+
/plugin install system-diff
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Python 3.11 or newer. Claude Code opens the pane by itself when the terminal is wide enough; `/system-diff` opens
|
|
37
|
+
it again after you close it. (Should another marketplace you added also have a plugin called system-diff,
|
|
38
|
+
`/plugin install system-diff@system-diff` names this one.) From a clone, `claude --plugin-dir mods/system-diff`
|
|
39
|
+
loads it for one launch. Upgrading from an earlier version: run `system-diff setup claude` again; it updates the
|
|
40
|
+
hooks it added before, and frees `/system-diff` for the pane.
|
|
41
|
+
|
|
42
|
+
### The System diff pane
|
|
43
|
+
|
|
44
|
+
A tab beside Claude Code's own file diff: the *system* diff, live, in four views.
|
|
45
|
+
|
|
46
|
+
- **Now** follows Claude, top to bottom in the order your attention needs it:
|
|
47
|
+
- **What Claude is doing** and what that part is: "● Claude is working ✎ Editing API · an entry point: where
|
|
48
|
+
people, other programs or AI tools reach the system", and what you asked.
|
|
49
|
+
- **▲ Needs your attention**, only when something does: an endpoint removed or added, stored data changed, a new
|
|
50
|
+
outside system, a part removed. Each with why it matters ("whatever called it now gets an error"). The moment to
|
|
51
|
+
ask Claude why, or steer it.
|
|
52
|
+
- **This turn**: every change to the system as a sentence ("API now uses Billing") with its reason in gray ("a
|
|
53
|
+
change in Billing can now break API").
|
|
54
|
+
- **The part, zoomed in on**: a diagram of what calls it and what it calls, its own endpoints and settings, what
|
|
55
|
+
changed marked. **Click it, then ← ↑ ↓ → pick a block and Enter zooms in on it**, as far as you want to walk the
|
|
56
|
+
system; `b` goes back, `f` follows Claude again, Esc hands the keys back.
|
|
57
|
+
- **About the part**: what it is and does, what is changing in it and why that matters.
|
|
58
|
+
- **What just happened**: › what you asked, ◎ what Claude read, ✎ what it edited, ▲ what each step did to the
|
|
59
|
+
system, ✓ when it finished.
|
|
60
|
+
- **Learn**: a topic behind the part, a new one every 20 seconds: the technologies its code imports (FastAPI,
|
|
61
|
+
SQLAlchemy, React, subprocesses, threads…) and the ideas behind its role (entry points, layers, migrations,
|
|
62
|
+
coupling…), in plain words.
|
|
63
|
+
- **Map**: the whole system, a row of blocks per column (what people use, entry points, logic, data access, stored
|
|
64
|
+
data, outside systems); the same keys pick and zoom in.
|
|
65
|
+
- **Changes**: exactly what changed since your checkpoint, and this turn. Once you have understood it, tell Claude
|
|
66
|
+
"mark it as seen" (or run `system-diff checkpoint`): from then on you see only what is new to you.
|
|
67
|
+
- **Topics**: everything the system is built with, and which parts use each.
|
|
68
|
+
|
|
69
|
+
One meaning per colour, so your eye goes where it should: **blue** is where Claude is and what you picked, **yellow**
|
|
70
|
+
what changed and what needs you, **green** what is new, done or to learn, **white** what to read, **gray** the
|
|
71
|
+
background (why, when, labels), **red** only what was taken away. Keys while the pane has the focus (ctrl+x tab, or a
|
|
72
|
+
click): `n` `m` `c` `t` switch views.
|
|
73
|
+
|
|
74
|
+
### In the conversation
|
|
75
|
+
|
|
76
|
+
- **After an edit that changes the system's structure**, one line under it: "System diff: API now answers GET
|
|
77
|
+
/health · a new way in: it needs the same checks as the others". Edits that change no structure stay quiet.
|
|
78
|
+
- **At the end of each turn**, one line on what the turn did to the system, or which parts it edited when the
|
|
79
|
+
structure stayed the same; nothing for a turn that only talked.
|
|
80
|
+
- **Ask Claude** "what is the API part?" or "what does this change do?": the MCP server gives it `explain` (the facts
|
|
81
|
+
to teach from, and a diagram to show you), `system_diff` (the exact list of changes; `base: turn` for this turn
|
|
82
|
+
only), `system_map`, `draw` (pictures of a process or a sequence of calls) and `checkpoint` (mark what you have
|
|
83
|
+
seen, so the next diff shows only what is new to you).
|
|
84
|
+
|
|
85
|
+
The pane and the hooks send nothing anywhere: the working tree is read as a snapshot (untracked files included)
|
|
86
|
+
without touching your index, HEAD or branches; the checkpoint and the start of each turn live under
|
|
87
|
+
`refs/worktree/system-diff/` (each worktree its own, for Claude sessions in parallel), and what the hooks note under
|
|
88
|
+
`.git/system-diff/`, never pushed. Only the optional lessons you ask an LLM for (`e` in the terminal view, `diff
|
|
89
|
+
--narrate`) go to your own LLM, and they carry the structure, never the code.
|
|
90
|
+
|
|
91
|
+
## Configuration
|
|
92
|
+
|
|
93
|
+
With no config, every folder of code is a part named by its path. A `system-diff.toml` at the repository root names the
|
|
94
|
+
parts and says what is what:
|
|
95
|
+
|
|
96
|
+
```toml
|
|
97
|
+
tests = ["tests/**"]
|
|
98
|
+
|
|
99
|
+
[code]
|
|
100
|
+
roots = ["app/", "web/src/"]
|
|
101
|
+
|
|
102
|
+
[[components]]
|
|
103
|
+
id = "api"
|
|
104
|
+
label = "API"
|
|
105
|
+
kind = "interface" # ui | interface | logic | data: the column it is drawn in
|
|
106
|
+
paths = ["app/api/**"]
|
|
107
|
+
|
|
108
|
+
[[externals]]
|
|
109
|
+
id = "postgres"
|
|
110
|
+
label = "PostgreSQL"
|
|
111
|
+
shape = "db"
|
|
112
|
+
env = ["DATABASE_URL"] # the settings that reach it
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Every key, and how the code is read: [the wiki](https://github.com/simplifiedmachine/system-diff/wiki).
|
|
116
|
+
|
|
117
|
+
## Add-ons
|
|
118
|
+
|
|
119
|
+
The same engine, outside the pane. Deterministic: the same code gives the same picture, byte for byte, and a part
|
|
120
|
+
that did not change keeps its place.
|
|
121
|
+
|
|
122
|
+
- **Pull requests:** every pull request gets its system diff as a comment, and CI fails when the README's map is out
|
|
123
|
+
of date (`.github/workflows/system-diff.yml`, which you can copy). This repository runs it on itself.
|
|
124
|
+
- **Command line:**
|
|
125
|
+
```sh
|
|
126
|
+
system-diff map --dir . --out docs/diagrams # the system as it is now: system.json, system.svg
|
|
127
|
+
system-diff diff --base origin/main --out out # what this branch does to it: headline, plan, diff.svg
|
|
128
|
+
system-diff diff --base HEAD --head . --out out # what your uncommitted work does to it
|
|
129
|
+
system-diff readme --json docs/diagrams/system.json # keep the map in README.md current
|
|
130
|
+
system-diff show API # one part zoomed in, and what it is, in any terminal
|
|
131
|
+
system-diff draw SPEC.json # hand-made pictures in the same look
|
|
132
|
+
```
|
|
133
|
+
`diff --narrate` adds a plain-words summary from your own LLM; `[png]` adds PNG output.
|
|
134
|
+
- **Terminal view** (`system-diff tui`): the pane's views as a full-screen terminal app, for a terminal beside any
|
|
135
|
+
agent. It opens by itself next to Claude Code in tmux, zellij, WezTerm, kitty and Windows Terminal; in VS Code,
|
|
136
|
+
setup adds a task that opens it with the folder.
|
|
137
|
+
- **Status line** (`system-diff setup claude` without `--no-status-line`): the pane's first lines under Claude Code's
|
|
138
|
+
prompt, for when the pane is not open.
|
|
139
|
+
- **Browser page** (`system-diff watch`): the same with the SVG pictures, at http://127.0.0.1:8765/.
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
MIT
|
|
@@ -9,7 +9,19 @@
|
|
|
9
9
|
"container": "",
|
|
10
10
|
"declared": true,
|
|
11
11
|
"files": 3,
|
|
12
|
-
"lines":
|
|
12
|
+
"lines": 302,
|
|
13
|
+
"hub": false,
|
|
14
|
+
"quiet": false
|
|
15
|
+
},
|
|
16
|
+
"activity": {
|
|
17
|
+
"label": "Agent activity",
|
|
18
|
+
"layer": "",
|
|
19
|
+
"kind": "data",
|
|
20
|
+
"order": 20,
|
|
21
|
+
"container": "",
|
|
22
|
+
"declared": true,
|
|
23
|
+
"files": 1,
|
|
24
|
+
"lines": 247,
|
|
13
25
|
"hub": false,
|
|
14
26
|
"quiet": false
|
|
15
27
|
},
|
|
@@ -21,7 +33,19 @@
|
|
|
21
33
|
"container": "",
|
|
22
34
|
"declared": true,
|
|
23
35
|
"files": 1,
|
|
24
|
-
"lines":
|
|
36
|
+
"lines": 417,
|
|
37
|
+
"hub": false,
|
|
38
|
+
"quiet": false
|
|
39
|
+
},
|
|
40
|
+
"companion": {
|
|
41
|
+
"label": "Panes beside the agent",
|
|
42
|
+
"layer": "",
|
|
43
|
+
"kind": "logic",
|
|
44
|
+
"order": 17,
|
|
45
|
+
"container": "",
|
|
46
|
+
"declared": true,
|
|
47
|
+
"files": 1,
|
|
48
|
+
"lines": 164,
|
|
25
49
|
"hub": false,
|
|
26
50
|
"quiet": false
|
|
27
51
|
},
|
|
@@ -29,11 +53,11 @@
|
|
|
29
53
|
"label": "Checkpoints and snapshots",
|
|
30
54
|
"layer": "",
|
|
31
55
|
"kind": "logic",
|
|
32
|
-
"order":
|
|
56
|
+
"order": 7,
|
|
33
57
|
"container": "",
|
|
34
58
|
"declared": true,
|
|
35
59
|
"files": 1,
|
|
36
|
-
"lines":
|
|
60
|
+
"lines": 183,
|
|
37
61
|
"hub": false,
|
|
38
62
|
"quiet": false
|
|
39
63
|
},
|
|
@@ -41,11 +65,11 @@
|
|
|
41
65
|
"label": "Config",
|
|
42
66
|
"layer": "",
|
|
43
67
|
"kind": "logic",
|
|
44
|
-
"order":
|
|
68
|
+
"order": 8,
|
|
45
69
|
"container": "",
|
|
46
70
|
"declared": true,
|
|
47
71
|
"files": 1,
|
|
48
|
-
"lines":
|
|
72
|
+
"lines": 115,
|
|
49
73
|
"hub": false,
|
|
50
74
|
"quiet": false
|
|
51
75
|
},
|
|
@@ -53,11 +77,11 @@
|
|
|
53
77
|
"label": "Typed diff",
|
|
54
78
|
"layer": "",
|
|
55
79
|
"kind": "logic",
|
|
56
|
-
"order":
|
|
80
|
+
"order": 10,
|
|
57
81
|
"container": "",
|
|
58
82
|
"declared": true,
|
|
59
83
|
"files": 1,
|
|
60
|
-
"lines":
|
|
84
|
+
"lines": 186,
|
|
61
85
|
"hub": false,
|
|
62
86
|
"quiet": false
|
|
63
87
|
},
|
|
@@ -65,11 +89,11 @@
|
|
|
65
89
|
"label": "Extraction",
|
|
66
90
|
"layer": "",
|
|
67
91
|
"kind": "logic",
|
|
68
|
-
"order":
|
|
92
|
+
"order": 9,
|
|
69
93
|
"container": "",
|
|
70
94
|
"declared": true,
|
|
71
95
|
"files": 1,
|
|
72
|
-
"lines":
|
|
96
|
+
"lines": 307,
|
|
73
97
|
"hub": false,
|
|
74
98
|
"quiet": false
|
|
75
99
|
},
|
|
@@ -77,11 +101,23 @@
|
|
|
77
101
|
"label": "Map layout",
|
|
78
102
|
"layer": "",
|
|
79
103
|
"kind": "logic",
|
|
80
|
-
"order":
|
|
104
|
+
"order": 11,
|
|
81
105
|
"container": "",
|
|
82
106
|
"declared": true,
|
|
83
107
|
"files": 1,
|
|
84
|
-
"lines":
|
|
108
|
+
"lines": 335,
|
|
109
|
+
"hub": false,
|
|
110
|
+
"quiet": false
|
|
111
|
+
},
|
|
112
|
+
"learn": {
|
|
113
|
+
"label": "Lessons and topics",
|
|
114
|
+
"layer": "",
|
|
115
|
+
"kind": "logic",
|
|
116
|
+
"order": 15,
|
|
117
|
+
"container": "",
|
|
118
|
+
"declared": true,
|
|
119
|
+
"files": 2,
|
|
120
|
+
"lines": 669,
|
|
85
121
|
"hub": false,
|
|
86
122
|
"quiet": false
|
|
87
123
|
},
|
|
@@ -93,7 +129,7 @@
|
|
|
93
129
|
"container": "",
|
|
94
130
|
"declared": true,
|
|
95
131
|
"files": 1,
|
|
96
|
-
"lines":
|
|
132
|
+
"lines": 240,
|
|
97
133
|
"hub": false,
|
|
98
134
|
"quiet": false
|
|
99
135
|
},
|
|
@@ -101,11 +137,23 @@
|
|
|
101
137
|
"label": "LLM summary",
|
|
102
138
|
"layer": "",
|
|
103
139
|
"kind": "logic",
|
|
104
|
-
"order":
|
|
140
|
+
"order": 14,
|
|
105
141
|
"container": "",
|
|
106
142
|
"declared": true,
|
|
107
143
|
"files": 1,
|
|
108
|
-
"lines":
|
|
144
|
+
"lines": 148,
|
|
145
|
+
"hub": false,
|
|
146
|
+
"quiet": false
|
|
147
|
+
},
|
|
148
|
+
"panel": {
|
|
149
|
+
"label": "Pane beside the chat",
|
|
150
|
+
"layer": "",
|
|
151
|
+
"kind": "interface",
|
|
152
|
+
"order": 5,
|
|
153
|
+
"container": "",
|
|
154
|
+
"declared": true,
|
|
155
|
+
"files": 1,
|
|
156
|
+
"lines": 247,
|
|
109
157
|
"hub": false,
|
|
110
158
|
"quiet": false
|
|
111
159
|
},
|
|
@@ -113,7 +161,7 @@
|
|
|
113
161
|
"label": "SVG pictures",
|
|
114
162
|
"layer": "",
|
|
115
163
|
"kind": "logic",
|
|
116
|
-
"order":
|
|
164
|
+
"order": 12,
|
|
117
165
|
"container": "",
|
|
118
166
|
"declared": true,
|
|
119
167
|
"files": 1,
|
|
@@ -125,7 +173,7 @@
|
|
|
125
173
|
"label": "PNG rendering",
|
|
126
174
|
"layer": "",
|
|
127
175
|
"kind": "logic",
|
|
128
|
-
"order":
|
|
176
|
+
"order": 18,
|
|
129
177
|
"container": "",
|
|
130
178
|
"declared": true,
|
|
131
179
|
"files": 1,
|
|
@@ -137,7 +185,7 @@
|
|
|
137
185
|
"label": "README section",
|
|
138
186
|
"layer": "",
|
|
139
187
|
"kind": "logic",
|
|
140
|
-
"order":
|
|
188
|
+
"order": 13,
|
|
141
189
|
"container": "",
|
|
142
190
|
"declared": true,
|
|
143
191
|
"files": 1,
|
|
@@ -149,11 +197,47 @@
|
|
|
149
197
|
"label": "Git and folder sources",
|
|
150
198
|
"layer": "",
|
|
151
199
|
"kind": "data",
|
|
152
|
-
"order":
|
|
200
|
+
"order": 19,
|
|
201
|
+
"container": "",
|
|
202
|
+
"declared": true,
|
|
203
|
+
"files": 1,
|
|
204
|
+
"lines": 84,
|
|
205
|
+
"hub": false,
|
|
206
|
+
"quiet": false
|
|
207
|
+
},
|
|
208
|
+
"statusline": {
|
|
209
|
+
"label": "Status line",
|
|
210
|
+
"layer": "",
|
|
211
|
+
"kind": "interface",
|
|
212
|
+
"order": 6,
|
|
213
|
+
"container": "",
|
|
214
|
+
"declared": true,
|
|
215
|
+
"files": 1,
|
|
216
|
+
"lines": 94,
|
|
217
|
+
"hub": false,
|
|
218
|
+
"quiet": false
|
|
219
|
+
},
|
|
220
|
+
"textmap": {
|
|
221
|
+
"label": "Terminal pictures",
|
|
222
|
+
"layer": "",
|
|
223
|
+
"kind": "logic",
|
|
224
|
+
"order": 16,
|
|
225
|
+
"container": "",
|
|
226
|
+
"declared": true,
|
|
227
|
+
"files": 1,
|
|
228
|
+
"lines": 313,
|
|
229
|
+
"hub": false,
|
|
230
|
+
"quiet": false
|
|
231
|
+
},
|
|
232
|
+
"tui": {
|
|
233
|
+
"label": "Terminal view",
|
|
234
|
+
"layer": "",
|
|
235
|
+
"kind": "interface",
|
|
236
|
+
"order": 4,
|
|
153
237
|
"container": "",
|
|
154
238
|
"declared": true,
|
|
155
239
|
"files": 1,
|
|
156
|
-
"lines":
|
|
240
|
+
"lines": 388,
|
|
157
241
|
"hub": false,
|
|
158
242
|
"quiet": false
|
|
159
243
|
},
|
|
@@ -165,27 +249,44 @@
|
|
|
165
249
|
"container": "",
|
|
166
250
|
"declared": true,
|
|
167
251
|
"files": 1,
|
|
168
|
-
"lines":
|
|
252
|
+
"lines": 341,
|
|
169
253
|
"hub": false,
|
|
170
254
|
"quiet": false
|
|
171
255
|
}
|
|
172
256
|
},
|
|
173
257
|
"flows": {
|
|
258
|
+
"activity>diff": 1,
|
|
259
|
+
"activity>extract": 1,
|
|
260
|
+
"activity>learn": 1,
|
|
261
|
+
"activity>sources": 1,
|
|
262
|
+
"agent>activity": 1,
|
|
263
|
+
"agent>companion": 1,
|
|
174
264
|
"agent>compare": 1,
|
|
265
|
+
"agent>config": 1,
|
|
266
|
+
"agent>extract": 1,
|
|
267
|
+
"agent>learn": 1,
|
|
175
268
|
"agent>sources": 1,
|
|
269
|
+
"cli>activity": 1,
|
|
176
270
|
"cli>agent": 2,
|
|
271
|
+
"cli>companion": 1,
|
|
177
272
|
"cli>compare": 1,
|
|
178
273
|
"cli>config": 2,
|
|
179
274
|
"cli>diff": 1,
|
|
180
275
|
"cli>extract": 2,
|
|
181
276
|
"cli>graph": 2,
|
|
277
|
+
"cli>learn": 1,
|
|
182
278
|
"cli>mcp": 1,
|
|
183
279
|
"cli>narrate": 1,
|
|
280
|
+
"cli>panel": 1,
|
|
184
281
|
"cli>pictures": 1,
|
|
185
282
|
"cli>png": 1,
|
|
186
283
|
"cli>readme": 1,
|
|
187
284
|
"cli>sources": 1,
|
|
285
|
+
"cli>statusline": 1,
|
|
286
|
+
"cli>textmap": 1,
|
|
287
|
+
"cli>tui": 1,
|
|
188
288
|
"cli>watch": 1,
|
|
289
|
+
"companion>sources": 1,
|
|
189
290
|
"compare>config": 1,
|
|
190
291
|
"compare>diff": 1,
|
|
191
292
|
"compare>extract": 1,
|
|
@@ -195,15 +296,52 @@
|
|
|
195
296
|
"extract>config": 1,
|
|
196
297
|
"graph>diff": 1,
|
|
197
298
|
"graph>pictures": 1,
|
|
299
|
+
"learn>activity": 1,
|
|
300
|
+
"learn>diff": 1,
|
|
301
|
+
"learn>extract": 1,
|
|
302
|
+
"learn>graph": 1,
|
|
303
|
+
"learn>narrate": 1,
|
|
304
|
+
"learn>sources": 1,
|
|
305
|
+
"mcp>activity": 1,
|
|
198
306
|
"mcp>compare": 1,
|
|
199
307
|
"mcp>config": 1,
|
|
200
|
-
"mcp>extract":
|
|
308
|
+
"mcp>extract": 2,
|
|
201
309
|
"mcp>graph": 1,
|
|
310
|
+
"mcp>learn": 1,
|
|
202
311
|
"mcp>pictures": 1,
|
|
203
312
|
"mcp>sources": 1,
|
|
313
|
+
"mcp>textmap": 1,
|
|
314
|
+
"panel>activity": 1,
|
|
315
|
+
"panel>compare": 1,
|
|
316
|
+
"panel>config": 1,
|
|
317
|
+
"panel>extract": 1,
|
|
318
|
+
"panel>graph": 1,
|
|
319
|
+
"panel>learn": 1,
|
|
320
|
+
"panel>sources": 1,
|
|
321
|
+
"panel>textmap": 1,
|
|
204
322
|
"readme>pictures": 1,
|
|
323
|
+
"statusline>activity": 1,
|
|
324
|
+
"statusline>config": 1,
|
|
325
|
+
"statusline>extract": 1,
|
|
326
|
+
"statusline>sources": 1,
|
|
327
|
+
"statusline>textmap": 1,
|
|
328
|
+
"textmap>pictures": 1,
|
|
329
|
+
"tui>activity": 1,
|
|
330
|
+
"tui>companion": 1,
|
|
331
|
+
"tui>graph": 1,
|
|
332
|
+
"tui>learn": 1,
|
|
333
|
+
"tui>pictures": 1,
|
|
334
|
+
"tui>sources": 1,
|
|
335
|
+
"tui>textmap": 1,
|
|
336
|
+
"tui>watch": 1,
|
|
337
|
+
"watch>activity": 1,
|
|
205
338
|
"watch>compare": 1,
|
|
206
|
-
"watch>
|
|
339
|
+
"watch>diff": 1,
|
|
340
|
+
"watch>extract": 1,
|
|
341
|
+
"watch>graph": 1,
|
|
342
|
+
"watch>learn": 1,
|
|
343
|
+
"watch>pictures": 1,
|
|
344
|
+
"watch>sources": 1
|
|
207
345
|
},
|
|
208
346
|
"api": {},
|
|
209
347
|
"routes": {},
|
|
@@ -219,6 +357,9 @@
|
|
|
219
357
|
},
|
|
220
358
|
"internal": {},
|
|
221
359
|
"env": {
|
|
360
|
+
"cli": [
|
|
361
|
+
"NO_COLOR"
|
|
362
|
+
],
|
|
222
363
|
"png": [
|
|
223
364
|
"SYSTEM_DIFF_RENDER_IMAGE"
|
|
224
365
|
]
|
|
@@ -231,6 +372,7 @@
|
|
|
231
372
|
"tests": {
|
|
232
373
|
"tests/conftest.py": 1,
|
|
233
374
|
"tests/test_checkpoint_watch_mcp.py": 1,
|
|
234
|
-
"tests/test_system_diff.py": 1
|
|
375
|
+
"tests/test_system_diff.py": 1,
|
|
376
|
+
"tests/test_terminal_and_learning.py": 1
|
|
235
377
|
}
|
|
236
378
|
}
|