mermaidiff

git diff for behavior. Type /mermaidiff on a PR or commit and get a sequence diagram of what it changes: ➕ new, ✏️ changed, ➖ removed. Read it in 30 seconds instead of the whole diff.

Works inside Claude Code, Codex and other agents that load skills · GitHub PRs and GitLab MRs · no server, no account

Quick start

git clone https://github.com/osmangoninahid/mermaidiff && cd mermaidiff && ./install.sh

Then, in any repo, inside your agent:

/mermaidiff                     # your staged or latest change
/mermaidiff <PR or MR link>     # someone else's change

The brief opens in your browser. Ask for changes in plain words ("drop the RunTLS step") and the open tab updates. Copy for MR gives you markdown that GitHub and GitLab render as is.

What you get

• One line saying what the code changes, taken from the diff, not the commit message
• A sequence diagram of only the changed steps, colored like a diff
• Proof for each step: file:line and an evidence tier, 🔵 seen in the code · 🟡 inferred · 🟢 seen running
• The payload diff when a request, response, model or config changes
• Breaks, only when the code proves them, and up to 2 open questions
• ⚠️ when the commit message or PR text claims something the diff doesn't do

The one rule: no false positives

A wrong warning is worse than a missing one. mermaidiff only shows what the diff or the code proves. It never guesses about systems outside your repo, it just lists them as Not checked.

Tested

10 real commits from FastAPI, gin and excalidraw, every claim checked against the code. Details in eval/.

All commands

/mermaidiff                     staged, else unstaged, else last commit
/mermaidiff staged
/mermaidiff wip                 unstaged changes
/mermaidiff a1b2c3d             one commit
/mermaidiff main..feature       a range
/mermaidiff <PR link> · #123    GitHub, needs gh
/mermaidiff <MR link> · !123    GitLab, needs glab
/mermaidiff ABC-123             a ticket (experimental, needs a Jira MCP)
/mermaidiff "move sync to a queue"   a plan, no code yet

Install options

Needs git and python3. Recommended: rg, and CodeGraph or Graphify for faster caller lookups (falls back to grep).

./install.sh            # for you: ~/.claude/skills and ~/.agents/skills
./install.sh --project  # for a repo, shared with your team
./install.sh --link     # symlink, if you work on mermaidiff itself

The installer downloads Mermaid once for offline use and adds .mermaidiff/ to your global git ignore.

Status

How it works

skill/SKILL.md          tells the agent how to gather facts (git, gh, glab, grep or a code graph)
skill/format.md         the output format and the rules, including "no false positives"
skill/scripts/view.py   renders the brief to html, recounts the stat line, opens the browser
eval/                   test cases, expected answers, run prompt, scores
examples/               briefs from public repos

Contributing

Found a wrong claim in a brief? That's the most useful bug report: open an issue with the brief and a link to the commit or PR. See CONTRIBUTING.md.

License

MIT. Not affiliated with the Mermaid project, it just draws with it.