DEV Community: unitstack

Shorten JSON Diff Time in AI Agents

unitstack — Wed, 07 Oct 2026 07:29:46 +0000

Ask an AI coding agent "what changed between these two JSON files?" and watch what it does. With small files you usually get a decent answer. With large ones — a minified API response, a 5,000-line fixture, a generated config — you typically get one of two failure modes: a wrong answer delivered with confidence, or a long, expensive hunt for the difference. The Compare JSON Skills and Compare JSON MCP integrations exist to fix both.

Failure mode 1: the git diff trap

The first tool an agent reaches for is usually git diff --no-index (or plain diff). That's a line-based text diff, and JSON is not line-based data.

The worst case is minified JSON — one line, tens of thousands of characters, extremely common in real API responses and snapshots:

$ git diff --no-index base.json contrast.json
-{"users":[{"id":1,"name":"Alice","email":"alice@example.com"}, ... 40,000 more characters
+{"users":[{"id":1,"name":"Alice","email":"alice@example.com"}, ... 40,000 more characters

One field changed somewhere in the middle, and the diff reports "the line changed". The agent still has to locate the actual difference itself — inside a single 40 KB line. Some agents give up and guess, which is where confidently wrong answers come from.

Even with pretty-printed files, text diff produces misleading hunks: reordered keys, whitespace changes, or one element inserted into an array can cascade into dozens of "changed" lines that don't correspond to any real data change. A smarter agent will pretty-print both sides with jq first — better, but key order and array misalignment still generate noise. The agent faithfully summarizes that noise, and one change gets reported as a dozen.

Failure mode 2: the eyeball marathon

The other default strategy is to read both files into the context window and look for the difference. On a large file this turns into a marathon: the file gets truncated, the agent re-reads it in chunks, runs a few greps, scrolls back and forth — and several minutes and tens of thousands of tokens later, it announces that meta.buildNumber went from 841 to 842.

Correct, but slow, expensive, and fragile. Every extra tool call is another chance to truncate, misalign, or miss a second difference hiding elsewhere in the file.

The fix: let a diff engine do the diffing

JSON diffing is a solved problem — just not by text tools. Parse both documents into trees, align objects by key and arrays by a chosen strategy, and report changes as exact paths. Deterministic, immune to formatting, and fast:

$ npx @compare-json/cli base.json contrast.json
valueChanged  meta.buildNumber

One line of output, no matter how large the inputs. The agent's job shrinks from finding the difference to explaining it — which is the part it's actually good at. That's the entire reason the skill and the MCP server exist: they put this engine one tool call away, so the comparison takes seconds instead of minutes, and the answer stops depending on how the files happened to be formatted.

Two ways to plug the engine in

Same engine, two delivery mechanisms:

The skill is a single SKILL.md that teaches your agent when and how to invoke @compare-json/cli. Install it once and any Agent Skills-compatible assistant — Claude Code, Codex CLI, OpenCode, Cursor — will run the CLI locally whenever you ask it to compare JSON:

npx skills add unitstack/compare-json

The MCP server exposes the same comparison as a structured compare_json tool. The CLI doubles as an MCP server (--mcp), so any MCP-capable client can call it with two file paths or strings and get machine-readable differences back:

{
  "differences": [
    {
      "pathSegments": ["meta", "buildNumber"],
      "pathString": "meta.buildNumber",
      "pathBelongsTo": "both",
      "diffType": "valueChanged"
    }
  ]
}

Which one should you pick? If your assistant supports Agent Skills, the skill is the lighter touch — no server config, invoked on demand. If your client speaks MCP and you want a permanent, typed tool with structured output, use the MCP server. Both wrap the same engine, so they report identical differences — including the array comparison strategy and the case-insensitive options.

The bottom line

LLMs are good at reasoning about differences and bad at locating them in raw text. The skill and the MCP server exist to split that work properly: the engine finds every difference in seconds, deterministically, and your agent spends its time — and your tokens — on the part that needs judgment.

A Live Mermaid Theme Playground: mermaid.design

unitstack — Sun, 04 Oct 2026 18:32:50 +0000

I use Mermaid a lot — flowcharts in design docs, sequence diagrams in READMEs, the odd ER diagram. Diagrams-as-code is a great deal: versionable, diffable, no dragging boxes around a canvas. What was never great is how the result looks.

The built-in themes are functional, but the colors feel dated. Mermaid does have a real theming system — set theme: 'base' and override whatever you like in themeVariables. The problem is the workflow: edit a frontmatter block, re-render, squint at the output, guess which of the 70-odd variables actually paints the thing you dislike, repeat.

My breaking point was a sequence diagram. I changed primaryColor and the actor boxes changed color along with it — turns out those belong to actorBkg. Ten minutes per color, most of it guessing, because a variable's name tells you almost nothing about what it paints.

What I wanted was simple: tweak a variable, see what it does. Immediately.

So I built mermaid.design — Mermaid code on the left, a live preview in the middle, and the whole theme system editable on the right. Every change re-renders the diagram in place. The feedback loop went from minutes to seconds.

That's the pitch. Here are the parts that actually save time.

The gallery: every diagram type at a glance

The annoying thing about theme variables is that the same variable behaves differently across diagram types. The gallery page renders all 84 templates — flowcharts, sequence, class, state, ER and more — live with your current theme. Change a variable, scroll the gallery, and the effect on every diagram type is right there. No more switching diagram types back and forth to check. That's the time it saves.

Theme variables: defaults and inheritance on the surface

Every one of the 73 variables shows its default from the mermaid base theme. Variables you haven't set get an AUTO badge showing the value mermaid derives at render time — and where that value comes from:

mainBkg follows primaryColor
primaryBorderColor is a border color computed from primaryColor
secondaryTextColor is the inverse of secondaryColor (for contrast)
actorBkg follows mainBkg — which explains the trap from earlier: changing primaryColor moved my actor boxes because there's an inheritance chain primaryColor → mainBkg → actorBkg

Once you see the chain, recoloring stops being guesswork.

Presets: official, designer, and more to come

21 presets, one click to apply: the 11 official mermaid themes (default, neutral, dark, forest, base, plus the v12 redux and neo families) and 10 designer presets I tuned by hand. Each shows a live mini preview — and the collection keeps growing.

Generate: one primary color, a whole palette

Pick a single primary seed color and the generator ramps lightness in HSL space around its hue — an 8-step scale — to derive a complete palette, dark-mode variant included. The fastest way to make a diagram match your brand.

Render config: beyond colors

Colors are only half of it. Mermaid has 438 render-affecting config fields, grouped by diagram type into 34 groups. A few examples:

Global: fontFamily, fontSize, wrap (auto text wrapping), look (classic or handDrawn)
Flowchart: flowchart.curve (edge curve style), flowchart.nodeSpacing / flowchart.rankSpacing (node/rank spacing), flowchart.diagramPadding
Sequence: sequence.actorMargin, sequence.messageMargin, sequence.showSequenceNumbers (message numbering), sequence.mirrorActors
Pie: pie.textPosition, pie.donutHole, pie.legendPosition

The group matching your current diagram type opens automatically.

ASCII mode: diagrams as text

The same diagram can render as ASCII art — one click to copy, ready for code comments, commit messages, or plain-text docs. It currently supports five diagram types: flowchart, sequence, class, state, and ER. The charset can be Unicode box-drawing or plain ASCII.

Wrapping up

The motivation behind mermaid.design was simple: the official theme colors are hard to love, hand-tuning themeVariables is slow, and I wanted a place where every change shows its effect immediately. Today it has live-editable theme variables with visible defaults and inheritance, a gallery that shows every diagram type at once, official and designer presets, a generator that turns one primary color into a full palette, 438 render-config fields, and an ASCII mode that turns diagrams into text.