Commands

Commands

system-diff [--repo PATH] [--config FILE] COMMAND … (also sysdiff, or python -m system_diff).

• --repo: the repository (default: the one holding the current directory).
• --config: a TOML or JSON config, instead of system-diff.toml or pyproject.toml's [tool.system-diff].

map

system-diff map [--ref REF | --dir DIR] [--out DIR] [--check]

The system at a commit (--ref, default HEAD), read from git's object store, or in a folder (--dir . is the working tree). Writes system.json and system.svg into --out (default .). --check writes nothing and exits 1 when the files there are out of date; that is the CI check.

diff

system-diff diff --base A [--head B | --head .] [--out DIR] [--narrate]

What changes from A to B (default HEAD). --head . is the working tree, uncommitted and untracked files included; --base checkpoint is what you last marked as seen (HEAD until you mark something). Both sides are read with the head's config, so a part keeps one name. Writes diff.json, plan.txt, headline.txt, diff.svg (only when something structural changed) and narrative.md.

--narrate asks an LLM for a plain-words summary. It sends the headline, the exact plan and the commit messages, never the code. It uses the first of:

1. the gateway your Claude Code uses: the env blocks of ~/.claude/settings.json, ~/.claude/settings.local.json, .claude/settings.json and .claude/settings.local.json, then any files [narrate] settings adds, with ANTHROPIC_* in the environment over all of them;
2. an OpenAI-compatible gateway you exported: SYSTEM_DIFF_LLM_BASE_URL, SYSTEM_DIFF_LLM_API_KEY and SYSTEM_DIFF_LLM_MODEL (or LLM_*).

When nothing answers there is no summary, and nothing else depends on it.

readme

system-diff readme [--json system.json] [--readme FILE] [--stale A,B] [--check]

Rewrites the section between the README's markers: the picture, how it is made, and the outside systems that are read but not drawn (from --json). --stale names pictures that could not be redrawn this time, so the README says they are older than the code. --check exits 1 when the section is out of date.

draw

system-diff draw SPEC.json …

Draws hand-made pictures, each SPEC.svg beside its spec. See Pictures.

png

system-diff png [--host HOST] FILE.svg …

Writes FILE.png beside each SVG, at twice the size, for places that do not show SVG. It uses headless Chromium: Docker here first, then Playwright (pip install "system-diff[png]", then playwright install chromium), else Docker on --host over SSH.

summarize

system-diff summarize --diff diff.json

The --narrate summary alone, for a diff already made.

checkpoint

system-diff checkpoint [--ref REF]

Marks the working tree (or REF) as what you have seen. --base checkpoint in diff and watch then starts there. See With AI coding agents.

watch

system-diff watch [--base checkpoint] [--port 8765] [--interval 2]

A live page at http://127.0.0.1:8765/ with the diff from --base to the working tree. It redraws when a file changes and has a Mark as seen button. Ctrl-C stops it.

setup claude

system-diff setup claude [--scope user|project|local] [--undo]

Adds the Stop hook, the skill and the MCP server to Claude Code, and prints each change. --undo removes them.

hook

system-diff hook

What the Stop hook runs: one line on what changed since the checkpoint, as {"systemMessage": …}, or nothing. It always exits 0, so it never gets in the agent's way.

mcp

system-diff mcp

The MCP server over stdio (needs the mcp extra): system_map, system_diff, draw, checkpoint.