I built diffx, a structure-aware, AI-first diff tool in Rust. Let’s end the comma-induced suffering.

This content originally appeared on DEV Community and was authored by kako-jun

— Let’s stop wasting our energy on trailing commas —

Ever felt that twinge of frustration when you git diff a config file like JSON or YAML?
You know, when a simple key reordering floods your screen with a sea of “changes.”
Or that one-character indent change! That trailing comma!

Traditional diff tools compare text line by line, which means they have no clue about the structure of your data.
It’s a small stress, sure. But it adds up, day after day.

“I need a smarter diff tool, one that gets the structure!”
…and by the time I thought that, I had already built it. Rage-driven development!

https://github.com/kako-jun/diffx

What is `diffx`?: A Diff Tool for Structured Data

diffx is a CLI tool built in Rust, specializing in structured data formats like JSON, YAML, TOML, XML, INI, and CSV.

Its killer feature is understanding the structural meaning of your data and displaying differences accordingly.
For example, let’s look at a common config file change.

Before: config_v1.json

{
  "version": "1.0.0",
  "server": {
    "port": 8080
  },
  "features": ["auth", "logging"]
}

After: config_v2.json

{
  "version": "1.0.1",
  "server": {
    "port": 8081,
    "host": "localhost"
  },
  "features": ["auth", "logging", "cache"]
}

If you view this with git diff, it’s a mess of changes that makes it hard to see what’s going on. Your eyes just glaze over.

But with diffx, the output looks like this:

$ diffx config_v1.json config_v2.json
~ version: "1.0.0" -> "1.0.1"
~ server.port: 8080 -> 8081
+ server.host: "localhost"
+ features[2]: "cache"

~ means a value changed, and + means something was added.
It also uses universal design colors, so it’s intuitive even for those with color vision deficiency!

This way, you can intuitively understand “which key changed and how?” or “what was added to which array?” in a clear path format.
I’m calling it the diffx format! Right now!

Tool	Type	Formats	Semantic Aware	Array Tracking	Best For
diffx	Semantic	JSON/YAML/TOML/XML/INI/CSV			Structured data comparison
diff	Text-based	Any text			General text files
jq	JSON processor	JSON	Partial		JSON manipulation
yq	YAML processor	YAML/JSON	Partial		YAML manipulation
daff	Tabular	CSV			CSV/spreadsheet data
jsondiff	JSON diff	JSON		Partial	JSON-only comparison
deep-diff	JavaScript	JSON/Objects			JavaScript applications

A Design for the Future?

I poured endless possibilities into this so it wouldn’t just be another diff tool.

1. `AI`-First Design

The output format of diffx is designed not only to be human-readable but also easy for AI to parse.

An AI agent using diffx could handle instructions like, “Summarize the key points of this configuration change.”
My goal is a future where AI agents ask humans, “Could you please install diffx for me?”

Even more interesting is the meta-concept of “self-chaining,” where you can output the diffx result in JSON or YAML format and then diff that output with diffx again.
This allows you to get a “diff of diffs,” which opens up huge possibilities for tracking the history of configuration changes or managing multiple prototypes of config files.
I hope this sparks-joy-and-ideas for you.

I’ve also built another Rust CLI called lawkit, which outputs in YAML. diffx has already proven itself useful there, creating powerful chains in my shell scripts.
https://github.com/kako-jun/lawkit

lawkit is a tool that uses natural laws like Benford’s Law to detect falsification in accounting documents and experimental evidence.

And though it’s not released yet, I’m also working on diffai, a Rust CLI for comparing AI-related static files (think tensor shape comparisons, weight statistics…).
https://github.com/kako-jun/diffai

Its output will also be in YAML format, adding even more fuel to the chaining fire.
It’s like a never-ending combo chain from a video game!

2. Simple, Unified Diff Format

No matter what formats you’re comparing, the output is always the unified diffx format.
It’s simple, so the learning curve should be low.

3. Handy Options for Programming

I’ve implemented every useful feature I could think of for daily programming, so it should stand up to some pretty niche use cases.

--ignore-keys-regex: Exclude keys you want to ignore, like timestamps, using regular expressions.
diffx ./dir1 ./dir2: Recursively compare two directories.
--array-id-key: Identify objects within an array by a key like id to accurately track changes.
There’s also a high-speed mode for comparing huge files.

It might even happen to meet the professional needs of a corporate environment.
If not, please file an issue on GitHub.

Making it More Accessible

I wanted as many people as possible to use it, so it’s built in Rust (cross-platform).
You can easily install it with cargo.

$ cargo install diffx

Executables for each OS are also available for download from GitHub Releases.
https://github.com/kako-jun/diffx/releases

Furthermore, I’ve created wrapper packages for pip and npm so you can use it in your Python and Node.js projects.
https://pypi.org/project/diffx-python/
https://www.npmjs.com/package/diffx-js

You can summon the power of diffx (which is super fast) seamlessly from these languages.

Smothering You With Documentation!

Even though it’s a personal project, I went all-in on the documentation from the start.
Installation instructions, a comprehensive explanation of all options, and a wealth of examples for various use cases. I’ve included everything I could think of, so it should be safe enough for a grade-schooler to use!

Documentation: https://github.com/kako-jun/diffx/blob/main/docs/index.md

I used Claude Code‘s Pro plan for development and translation.
Even someone like me, whose Japanese is imperfect, could build this!
I thought it was $20/month and regenerated the code over and over, only to get a bill for $20 + $220. I was shocked. So, the more you read this, the more I recoup my investment!

In Conclusion

diffx is a very simple tool. If you’ve ever had the same frustrations with diffing, please give it a try.

I’m gradually realizing just how convenient this tool is and the potential it holds.
I’m not sure how seasoned developers will feel, but I’d be thrilled if it turns out to be a hidden gem that makes you think, “This is exactly what I’ve been looking for!”

My cat was on my lap the entire time I was developing this.
If you could star it on GitHub, you’ll probably startle my cat (because I’ll be doing a victory pump).