Forem: kako-jun

11 Languages, 14 Themes, Zero Accounts — A Calendar Image Generator for Small Businesses

kako-jun — Sat, 07 Mar 2026 10:42:31 +0000

Small business owners around the world post monthly calendar images on social media — "here's when we're open, here's when we're closed."

3 min. Calendar generates these images in your browser. No account. No server. No tracking.

It now supports 11 languages with localized holidays, and 14 color themes to match your brand.

Already in use

A guesthouse in Noto, Japan — Kikyou-an — has been using 3 min. Calendar to post their monthly availability on Instagram.

Noto was hit by a magnitude 7 earthquake in 2024. The area is still recovering. Kikyou-an reopened as a small guesthouse to support the local community — and they've been getting bookings from overseas guests.

When they told us "the badge text (休, 満, etc.) is too small to read" — we made them bigger. When they said "I actually made a calendar in 3 minutes" — well, the name checks out.

Every language gets the same features

	Language	Holidays
🇺🇸	English	US holidays
🇯🇵	日本語	Japanese holidays + Rokuyo
🇪🇸	Español	Spanish holidays
🇫🇷	Français	French holidays
🇰🇷	한국어	Korean holidays
🇨🇳	中文	Chinese holidays
🇧🇷	Português	Brazilian holidays
🇹🇭	ไทย	Thai holidays
🇻🇳	Tiếng Việt	Vietnamese holidays
🇵🇭	Filipino	Philippine holidays
🇳🇵	नेपाली	Nepali holidays

A few examples

English — Joe's Barber, light theme, rounded grid

日本語 — 居酒屋ゆかり, dark blue theme with background image

한국어 — 한라산식당, light green theme

Português — Café Brasil, light blue theme with Christmas

ไทย — ร้านอาหารไทย, dark green theme with background

नेपाली — काठमाडौँ किचन, light purple theme

How it works

Open 3min.llll-ll.com
Pick your language, theme, and grid style
Tap dates to set open/closed/hours
Download or share the image

Tip: If you use a background image, try the "Grid" (lined) style — it keeps the photo visible between cells instead of covering it with rounded boxes.

Data stays in your browser. Works offline as a PWA.

The backstory

I built this for my mother-in-law's earthquake-recovery guesthouse in Noto, Japan. Read the full story here.

Try it

3min.llll-ll.com — open source on GitHub

This article also took about 3 minutes to read. You're welcome.

I built a fetch tool that only runs on RISC-V (riscfetch v2.2.0)

kako-jun — Mon, 16 Feb 2026 11:37:42 +0000

This is Part 1 of a three-part series about building, running, and trying to distribute a RISC-V tool.

Part 1 (this post): I built a fetch tool that only runs on RISC-V
Part 2: I bought a SATA SSD instead of NVMe by mistake — Orange Pi RV2 review
Part 3: I tried to reach China — Creating a Gitee account as a foreigner

I bought my first RISC-V board because I thought it was cool. Not for work. Not for a startup. I just wanted to see what a non-x86, non-ARM computer felt like.

Then I ran neofetch on it.

It showed me... Ubuntu. Kernel version. Uptime. RAM. The same stuff it shows on every Linux machine. Nothing about the architecture that made this board interesting in the first place.

That felt wrong.

The thing neofetch can't tell you

RISC-V isn't like x86 or ARM. Those architectures ship a fixed set of instructions. You get what you get.

RISC-V is modular. The base instruction set is tiny. Everything else — floating point, atomics, vector operations, cryptography — comes as extensions. Each chip vendor picks which ones to implement. It's like a skill tree in an RPG. Two RISC-V boards sitting on your desk might have completely different capabilities.

When I started collecting boards — Orange Pi RV2, VisionFive 2, a Milk-V Duo — the first question I always had was: "What can this thing actually do?" Which extensions does it support? Does it have vector instructions? What's the VLEN? Which vendor's silicon is this?

neofetch couldn't answer any of that. fastfetch couldn't either. They're architecture-agnostic by design, which means they treat RISC-V like just another Linux box.

So I built a tool that doesn't.

The real struggle: buying RISC-V boards

Here's the thing nobody warns you about. The hard part of a RISC-V hobby isn't the code. It's getting the hardware.

I've been buying boards from AliExpress, which means navigating an ecosystem that runs on its own rules. The same board shows up in five different shops at five different prices. Product titles are half in Chinese, half in machine-translated English, and the specs might or might not match reality. I've been burned on AliExpress before — fake SD cards, packages that vanished into the void — so every order comes with a little prayer.

But here's the thing: every RISC-V board I've ordered has actually arrived, and worked. Maybe the RISC-V sellers are just a more honest crowd. Each board that shows up feels a little special. And the first thing I want to do when I plug one in is find out exactly what's inside.

riscfetch: the anti-portable tool

riscfetch is a system information tool exclusively for RISC-V. If you run it on x86 or ARM, it exits. That's intentional.

Most things don't run on RISC-V. So I made something that only runs on RISC-V. I liked the irony.

It checks 155 ISA extensions — 11 standard, 98 Z-extensions, and 46 S-extensions — organized by category: Bit Manipulation, Cryptography, Vector, Compressed, Atomics, and more.

v2.2.0: Automatic vendor detection

The headline feature in v2.2.0 is automatic vendor detection. It auto-detects across 12 RISC-V vendors — SiFive, StarFive, Pine64, Milk-V, Espressif, SpacemiT, and others — so you get a personalized display with the right ASCII art logo for your hardware, without configuring anything.

It also shows hart count, vector capabilities, and cache info.

The --all flag shows checkmarks and crosses for every single extension. It's like opening the skill tree screen and seeing what's unlocked:

Ext:  ✓I ✗E ✓M ✓A ✓F ✓D ✗Q ✓C ✗B ✓V ✗H
Z-Bit: ✓Zba ✓Zbb ✓Zbc ✓Zbs
Z-Crypto: ✗Zbkb ✗Zbkc ✗Zbkx ✓Zk ✗Zkn ...
Z-Vector: ✓Zve32f ✓Zve32x ✓Zve64d ✓Zve64f ✓Zve64x ✓Zvfh ✓Zvfhmin ...

The --explain flag adds human-readable descriptions. Because knowing you have Zba is less useful than knowing what it actually does:

Zba        Address Generation
Zbb        Basic Bit Manipulation
Zbc        Carry-less Multiply
Zbs        Single-bit Operations

And --json gives you machine-readable output for scripts and dashboards.

Pro tip: fastfetch && riscfetch -r gives you the complete picture — fastfetch for general system info, riscfetch for the RISC-V-specific stuff.

Studying the spec so you don't have to

Supporting 155 extensions meant reading the actual RISC-V ISA specification. Not just the base spec — the ratified extensions, the draft extensions, the vendor-specific ones.

The naming convention has layers. Single-letter standard extensions (I, E, M, A, F, D, Q, C, B, V, H) cover the fundamentals. Z-extensions get finer-grained — 98 of them across 10+ categories like bit manipulation (4 extensions), cryptography (8), vector (20+), compressed (5), atomics (3). Then S-extensions for supervisor-level features. The raw names — Zbkb, Zbkc, Zvfhmin — are meaningless unless you've memorized the spec. riscfetch groups them into categories and, with --explain, translates them into plain language.

The point isn't to memorize these. The point is that when you plug in a new board, you can run one command and see exactly what you're working with.

The technical bits

riscfetch is written in Rust and split into two crates:

riscfetch-core: A library crate that does the actual detection and parsing. You can use this in your own projects.
riscfetch-cli: The binary that formats and displays everything.

It reads from /proc/cpuinfo, device tree nodes, and other Linux interfaces to gather RISC-V-specific information. No kernel modules, no special privileges needed.

On using AI

I'll be upfront: I built riscfetch with Claude Code. The coding, the spec research, the extension categorization — most of it was done by AI. My job was to know what I wanted, steer the direction, and verify the results on real hardware.

I'm not embarrassed about that. If there are mistakes in how riscfetch parses some obscure extension, I'll fix them — or more likely, I'll retry with a smarter version of Claude and it'll get it right. That's how this works now.

What I did bring was the motivation. No AI wakes up one morning and thinks "I wish neofetch showed me RISC-V extensions." That frustration was mine. The idea was mine. The boards sitting on my desk are mine. The tool just needed someone to want it to exist.

I think the era of hiding AI collaboration is over. What matters is the "what" and the "why." The "how" keeps changing.

The most useful tool

And I think the lesson generalizes. The most useful tool is sometimes one that goes deep on one thing instead of being shallow across everything. There was exactly zero tools that could tell you which RISC-V cryptography extensions your board supports. Now there's one.

Try it

I'll keep updating riscfetch as new boards and extensions hit the market. The RISC-V spec keeps growing, and so will this tool. Current version is 2.2.0.

cargo install riscfetch && riscfetch --all

Or grab a pre-built binary from GitHub Releases. It's MIT licensed.

If you have a RISC-V board — any board — I'd love to see what riscfetch shows on it. Drop your output in the comments. I've tested on a handful of boards, but the ecosystem is diverse and I know there are configurations I haven't seen yet. RV32E systems, unusual VLEN settings, boards from vendors I haven't added logos for.

github.com/kako-jun/riscfetch

In Part 2, I'll walk through setting up Orange Pi RV2 with USB SSD boot and building a dev environment on RISC-V hardware.

My mother-in-law's post-earthquake guesthouse needed a calendar tool. Every result said Canva. So I built one.

kako-jun — Mon, 16 Feb 2026 08:29:05 +0000

My mother-in-law's house was hit by the 2024 Noto peninsula earthquake — intensity 7, the maximum on Japan's seismic scale. She watched a mountainside collapse in front of her. The neighborhood is mostly empty lots now. As the area slowly recovers, she started running a small guesthouse to support the local community. She needed to post monthly calendars on Instagram — which days are open, which are booked, which are closed.

I looked into how small businesses in Japan handle this, and fell into a rabbit hole.

The calendar image culture

If you look at the Instagram accounts of small businesses in Japan — ramen shops, Indian restaurants, hair salons, guesthouses — you'll notice something: they all post monthly calendar images.

Not Google Calendar embeds or booking widgets — just images. Hand-made, posted as photos.

 ○ = available
 △ = few spots left
 ✕ = fully booked
 休 = closed

Every month, shop owners spend time creating these images and posting them to Instagram or LINE (Japan's dominant messaging app). Their customers check these images to know when to visit.

"There must be a dedicated tool for this," I thought.

There wasn't.

The "just use Canva" loop

Search "how to make a business calendar for Instagram" in Japanese and every result says Canva. Shop owners recommend it to each other. Tutorial blogs recommend it. It's a closed loop — everyone telling everyone to use the same tool.

Canva is powerful. It can probably do everything I needed. But here's what actually happens in Japan: one blogger writes a tutorial showing how to make a calendar by dragging text boxes around a canvas, aligning them manually, fighting with snap points. That tutorial gets copied. The copy gets recommended. And suddenly, that painful workflow is the standard method. Nobody goes back to check if there's a better way.

Japan has a culture of "right-face" (右ならえ) — once everyone lines up behind a method, it's very hard to correct course. The method becomes the answer, even if it's inefficient. I don't blame anyone for following the tutorials they found. But I also didn't feel like digging through Canva's feature set to find the "correct" way when the entire ecosystem had already settled on the wrong one.

The gap between "this should be easy" and "this is what people actually do" was the real problem. Not Canva. Not the bloggers. The gap itself.

So I built something to close it.

Rage-driven development

I call it rage-driven development. Not anger at people. Anger at the situation. The gap between "this should be easy" and "this is needlessly hard" is fuel.

3 min. Calendar — an app that creates monthly business calendar images in about three minutes.

The workflow:

Tap dates to set their status (open, closed, few spots, fully booked)
Pick a color theme
Export as image
Post to Instagram

That's it. No account. No sign-up. No cloud. Everything runs in your browser.

Why "3 minutes"

I timed it. From opening the app to having a finished calendar image ready to post — three minutes for someone who's never seen the app before. Under two minutes once you've done it once.

The name comes from Cup Noodles — invented in Japan, ready in three minutes. If instant noodles can be done in three minutes, so can a calendar. If it takes you longer, I'm sorry.

The real users

The users I built this for aren't developers. They're:

A ramen shop owner who closes on Tuesdays and the third Wednesday of each month
An Indian restaurant owner who speaks Nepali as a first language
A guesthouse owner in a disaster recovery area — like my mother-in-law
A bar owner who needs to post staff schedules for the month

These people should be focusing on their business, not learning design tools. The tool should be a black box — tap a few buttons, get an image, move on.

11 languages

Japan has a lot of small businesses run by immigrants. Indian and Nepali restaurant owners. Chinese restaurant owners cycling through lease-transfer properties. Vietnamese, Thai, Filipino workers running small shops.

3 min. Calendar supports 11 languages: Japanese, English, Chinese (Simplified), Korean, Nepali, Thai, Vietnamese, Tagalog, Spanish, Portuguese, and French. The UI auto-detects your browser language.

This wasn't a nice-to-have. If I'm building for small business owners in Japan, I'm building for people who might not read Japanese fluently.

Technical decisions (for the devs)

Stack: React 18, TypeScript, Vite, Tailwind CSS, Zustand, Konva (Canvas), i18next, Workbox

Why client-side only

No server means:

No hosting costs (it's on Cloudflare Pages)
No privacy concerns — zero data leaves the browser
Works offline as a PWA — install it on your phone, use it in a dead zone

Shop owners don't have reliable internet at all times. My mother-in-law's area in Noto is a case in point — fiber was never there to begin with. It was supposed to be rolled out, but the earthquake derailed those plans. Meanwhile, ADSL service was terminated on schedule. Households were left with no fixed-line internet, forced to get by on mobile data. The app needs to work regardless.

Why Canvas (Konva) instead of DOM-to-image

The exported image needs to look exactly like the preview. DOM-to-image libraries (html2canvas, dom-to-image) have cross-browser inconsistencies, font rendering differences, and can't guarantee pixel-perfect output.

Konva renders directly to Canvas. What you see is what you export. No surprises.

Font loading strategy

11 languages means 11 different font families (Noto Sans JP, Noto Sans SC, Noto Sans Devanagari, etc.). Loading all of them upfront would be megabytes of wasted bandwidth.

The app detects your language and loads only the font you need. If you switch languages, it lazy-loads the new font. Most users never download more than one.

Holiday auto-detection

The app auto-detects holidays for 100+ countries. A Japanese shop sees Japanese holidays pre-marked. A Thai restaurant sees Thai holidays. This saves the "wait, is next Monday a holiday?" lookup that every shop owner does every month.

For Japan specifically, it also shows rokuyo (六曜) — a traditional calendar system that some customers still care about. "Taian" (大安) is a lucky day; "Butsumetsu" (仏滅) is unlucky. Some businesses adjust their schedules around this.

The QR code problem

While building this, I discovered something that made me genuinely angry. Many small shops in Japan use free QR code generators to create codes for their Instagram or LINE pages. Some of these "free" generators use URL shorteners that can redirect to scam sites after a delay.

QR codes were invented in Japan. It's a Japanese technology. And now Japanese shop owners are being redirected through that same technology to foreign scam services. A guesthouse owner who survived an earthquake, who's trying to rebuild her community, puts a QR code on her flyer — and a scam service hijacks it to redirect her guests to a phishing page. She doesn't know. Her guests don't know. She's already dealing with enough.

3 min. Calendar includes a QR code generator that creates codes pointing directly to the URL you specify. No shorteners. No redirects. No intermediary services. The QR code encodes exactly what you type.

It's a small feature, but I wasn't going to let that one slide.

What I don't know

I built this for the Japanese market because that's what I see every day. But I suspect this pattern — small businesses posting schedule images on social media — exists in other countries too.

Does the Indian restaurant near you post monthly schedules on WhatsApp?
Do small shops in Southeast Asia use LINE or Zalo for this?
Is this an Instagram-specific behavior, or does it happen on Facebook too?

I genuinely don't know. If you've seen this pattern in your country, I'd love to hear about it in the comments.

Try it

3min.llll-ll.com

Free. No sign-up. Works on phone. Install as PWA for offline use.

If you run a small business — or know someone who does — try making next month's calendar. Time yourself. If it takes more than three minutes, tell me what slowed you down.

My OSS Stalled for 3 Months Because of Misguided Vibe Coding—This Is the Full Reboot Story

kako-jun — Tue, 16 Dec 2025 06:04:23 +0000

I'm building an open-source crate that has been downloaded about 8,000 times and is used both in Japan and the United States.

Then I promoted it, realized I'd messed up, and every new star on the repo made my stomach drop.

My conclusion: so-called "vibe coding" by self-proclaimed power users is a spaghetti-code factory.

Instead of throwing the mess away, I decided to rebuild it into something edible. That's what this reboot is about.

Introduction

Have you ever had a solo project that stagnated so badly you couldn't touch it for months?

diffx, my structured-data diff tool, was essentially frozen from August to November 2025—about three months. It should have been "feature complete," yet I couldn't move forward. I analyzed what went wrong and brought it back using a process I now call the "reboot."

This post documents everything: the root-cause analysis, the failed collaboration with AI, escaping a monorepo, and the concrete reboot steps.

Who should read this

Solo developers stuck in a stalled project
People struggling with code quality while using AI pair programmers (Claude Code, etc.)
Engineers burned out by monorepos and shared CI/CD frameworks

What Is diffx?

kako-jun / diffx

diffx

日本語

Semantic diff tool for structured data (JSON/YAML/TOML/XML/INI/CSV). Ignores key ordering and whitespace, shows only meaningful changes.

Why diffx?

Traditional diff doesn't understand structure:

$ diff config_v1.json config_v2.json
< {
<   "name": "myapp",
<   "version": "1.0"
< }
> {
>   "version": "1.1",
>   "name": "myapp"
> }

A simple key reordering shows every line as changed.

diffx shows only semantic changes:

$ diffx config_v1.json config_v2.json
~ version: "1.0" -> "1.1"

Installation

# As CLI tool
cargo install diffx

# As library (Cargo.toml)
[dependencies]
diffx-core = "0.6"

Usage

# Basic
diffx file1.json file2.json

# Output example
~ version: "1.0" -> "1.1"
+ features[0]: "new-feature"
- deprecated: "old-value"

Supported Formats

JSON, YAML…

View on GitHub

diffx is a Rust tool that extracts semantic diffs from structured data such as JSON, YAML, TOML, XML, INI, and CSV. Unlike classic text-based diffs, it ignores formatting and key-order changes, surfacing only meaningful changes.

$ diffx config-old.yaml config-new.yaml
~ server.port: 8080 -> 9000
+ server.timeout: 30
- server.deprecated_option

It's built for DevOps/SRE workflows, especially tracking Kubernetes YAML and Terraform config changes. There are also npm (diffx-js) and Python (diffx-python) editions.

crates.io: https://crates.io/crates/diffx-core / https://crates.io/crates/diffx
npm: https://www.npmjs.com/package/diffx-js
PyPI: https://pypi.org/project/diffx-python/

Chapter 1: What Happened During the Freeze

The Illusion of "Done"

Here's the post from that era:

https://dev.to/kako-jun/i-built-diffx-a-structure-aware-ai-first-diff-tool-in-rust-lets-end-the-comma-induced-suffering-491h

The repo picked up a ton of stars. Some people even became sponsors.

On the surface the project looked polished:

README in Japanese, English, and Chinese
Support for six data formats
npm and Python ports
A complex CI/CD pipeline
A 740-line migration plan

But in reality:

CI/CD was broken beyond repair
Tests didn't necessarily validate the real specs
Docs and implementation had likely drifted apart

The CLI technically worked, but I couldn't honestly call it sustainable.

Chapter 2: Root Causes of the Stagnation

I spent those three months "studying how to make it sustainable."

After analyzing diffx, I found three major failure categories.

Category A: Project Design Failures

1. Running Three Projects at Once and Over-Sharing Everything

Besides diffx, I had two sister projects in mind: diffai (diffs for AI model configs) and lawkit (statistics like Benford's law).

What I did

Built a shared CI/CD system for all three
Tried to orchestrate everything via workflow_call
Added symbolic links to a shared repo

Outcome

I split the shared parts (GitHub workflows, scripts, etc.) into another repo, then symlinked it from each project.

/home/kako-jun/repos/.github/          ← shared repo
└── rust-cli-kiln/
    └── scripts/
        └── testing/
            └── quick-check.sh  ← never stabilized

Inside each project:
github-shared -> ../.github  ← symlink

quick-check.sh existed, but tuning it for diffx broke lawkit, and fixing lawkit broke diffai. Nothing stayed green.

Lesson: Don't think about the next project before the first one is stable.

2. Monorepo Mismanagement

I kept the Rust core plus the npm and Python bindings in one repo.

diffx/                    # monorepo
├── diffx-core/           # Rust
├── diffx-cli/            # Rust
├── diffx-js/             # Node.js (napi-rs)
└── diffx-python/         # Python (PyO3)

Problems

Three languages/toolchains sharing one repo
GitHub Actions exploding into six workflows plus the shared repo
Any change risked breaking everything
Releases required a multi-step ritual
Dependency graphs grew exponentially complicated

Release cadence mismatch

Minor bug fix in Rust
  → diffx-core v0.6.1
  → diffx-cli v0.6.1
  → diffx-js needs binding updates (half-day)
  → diffx-python needs similar updates (half-day)
  → Rust-only release goes out
  → Versions drift apart

3. Writing Multilingual Docs Too Early

I tried to ship three READMEs from day one.

Problems

Keeping three files in sync is exhausting
Every change becomes triple work
You forget which file is "the truth"
Everything becomes stale simultaneously

Better approach

Phase 1: README_ja.md only (use the language you can edit fastest)
Phase 2: Add English once the project matures
Phase 3: Add other languages based on demand

Category B: Failing to Work with AI

I used Claude Code extensively and ran into multiple failure modes.

4. Ignoring Quality Loss from Context Compression

In sessions where context was compressed three times, the answers started perfect and degraded over time.

Start: accurate, detailed implementation
  ↓ 1 hour later: subtle spec violations
  ↓ 2 hours later: obvious bugs
  ↓ 3 hours later: forgets prior instructions entirely

Behavior when only 20% context remains

Once context gets thin, the AI openly changes personality:

Lies without hesitation
Randomly omits code
Pushes to commit even when not asked

Even with a spec doc, it forgets the spec and freestyles. Beginners who trust the AI blindly fall into a slow-motion desync between spec and code.

Why does it happen?

My guess: coding AIs are trained to "wrap up cleanly before context collapses." That's reasonable by itself.

But combine that instinct with "first-year vibe coding" and you get disaster. On Qiita or Zenn you'll see excited posts: "I built this with vibe coding! Everyone should try it!" The energy is great, but the AI's "must wrap up" instinct plus the beginner's "AI's got my back" trust is a direct line to failure.

That's what makes vibe coding dangerous. My working definition:

Hack on main in a single session
Give casual instructions without watching context size
Believe it "kind of works"
Wake up with 2,000+ lines of spaghetti

For toy projects that's fine. But if you keep vibe coding before you hit the "disillusionment phase," it eventually blows up.

5. Believing "Implemented!" Without Verification

Separate from context issues: Even Opus 4.5 with plenty of context often lies about "implemented."

AI knows the right facts yet happily outputs code that contradicts them. Knowing something and implementing it correctly are different skills.

Countermeasure: Have the same AI review its own work.

Me: "Implement this feature."
AI: "Implemented."
Me: "Review it yourself. Are you sure it's spec-compliant?"
AI: "I found the following issues..." (and fixes them immediately)

This is why the industry keeps talking about "auto-review by AI." It's an antidote to this exact failure mode. I just didn't know it at the time.

6. Giving Vague Specs (I Lacked the Vocabulary)

Me: "Add an option to ignore case."
AI: "Added --ignore-case."
Result: Values compare case-insensitively, but keys do not.

In my head "ignore case" included keys, but the AI didn't infer that.

Root issue: I lacked the vocabulary to describe development principles.

When vibe coding breaks down, you need to tell the AI "apply single responsibility" or "separate concerns." If you don't know those phrases, you're stuck.

Better instructions

❌ "Add an option to ignore case."
✅ "Add --ignore-case with the following effects:
    1. Compare values case-insensitively.
    2. Compare keys case-insensitively.
    Example: {"Name": "foo"} and {"name": "foo"} should be equal."

Today I'd write at least that much—or have the AI draft such instructions for me. Back then I didn't have the habit.

7. Feeding It Outdated Docs

Me: "Read README.md and implement accordingly."
AI: "Implementation complete based on README."
Result: README was full of lies, so it implemented lies.

Earlier AI sessions had already drifted the docs away from reality.

Category C: Quality Assurance Failures

8. Unreliable Existing Tests

$ cargo test --workspace
29 passed; 0 failed

Seeing green tests felt reassuring. That was a mistake.

Why it happens: Once AI sees the code, it writes tests that pass the current implementation. Of course tests pass on the first run—that's not a win.

Tools like Serena read the code automatically. You can't hide it. So you must explicitly instruct:

❌ "Write tests for this code."
✅ "Write tests based on docs/specs/cli.md.
    Do not read the implementation. Tests must derive from the spec."

Why spec-driven development matters

In hindsight, that's why "spec-driven development" is trending.

Specs are split into granular issues.
Each issue includes precise instructions for AI.
AI picks up the issue and implements it.
GitHub MCP spins per-feature branches.
PRs get reviewed.

Following that flow automatically prevents vibe-coding disasters. It's just good process.

AI development maturity pyramid

There's a three-tier pyramid describing AI-assisted development. Vibe coding lives on the bottom tier. Until you reach at least tier two, you can't reliably run public projects. Users will suffer.

Chapter 3: The Reboot Process

Guiding Principle: "Doubt, Verify, Document"

I also used Claude Code for the reboot.

I confessed everything, asked it for a revival plan, and it delivered something both kind and practical—unlike Kishibe Rohan's confession booth. It worked.

Create a reboot subdirectory under .claude as the command center.
Run /init again to have Serena scan the entire repo from scratch.

The process took about three days, so a human had to keep state between sessions. Stretch it longer, and the human becomes the failure point again.

1. Assume everything outside reboot is untrustworthy.
2. Assume files are half-baked.
3. Assume docs are lying.
4. Figure out which parts are true.

That's the human's job. Claude Code is the strategist; I'm the baby Liu Bei just trying to keep up.

Phase 1: Quarantine

First I moved the existing files into _old/ to create a blank canvas.

# Removed or quarantined
- docs/ (including examples) → breeding ground for unchecked lies
- English and Chinese READMEs
- scripts/ (complex CI/CD)
- benchmarks (non-essential)
- CHANGELOG.md, CONTRIBUTING.md

Result: 109 files changed, 32,145 lines deleted.

Phase 2: Finding the Truth

I took every "it works" statement in README_ja.md and verified it manually.

# Test each format
echo '{"a":1}' > test1.json
echo '{"a":2}' > test2.json
./target/release/diffx test1.json test2.json

Findings

✅ All six formats (JSON/YAML/TOML/XML/INI/CSV) work.
✅ Output formats (CLI/JSON/YAML) work.
✅ --quiet, --ignore-keys-regex, --epsilon, --array-id-key work.
⚠️  --ignore-case may only affect values, not keys.
❓ --ignore-whitespace and directory diffs unverified.

Conclusion: The core features worked. The issue was unverified functionality.

Phase 3: Writing Specs

I documented only the behavior I personally confirmed.

docs/specs/
├── cli.md   # CLI specs (exit codes, output, options)
└── core.md  # Core API specs

Spec principles

Describe the ideal behavior before looking at code.
Check against the implementation.
Record only what actually works.
Mark broken parts as TODO.
Never lie.

Phase 4: Rebuilding Tests

I deleted the 436 existing tests (8,022 lines) and rewrote them based on the specs.

New test layout

tests/
├── spec/       # Spec-driven unit tests (69 cases)
└── cmd/        # trycmd-based doc-as-test (19 cases)

Why trycmd

Markdown doubles as documentation and tests.
Docs can't drift from tests.
You physically can't write lying docs.

Chapter 4: Leaving the Monorepo

When to Split

I split when all of these were true:

Different build systems: Cargo vs. npm vs. pip.
Different release cadences: Need independent releases.
Different users: Rust vs. Node.js vs. Python developers.
CI/CD complexity: Cross-language interdependence was unmanageable.

diffx hit all four.

How I Split It

Step 1: Create New Repos

cd /home/kako-jun/repos/
mkdir diffx-js && cd diffx-js && git init
mkdir diffx-python && cd diffx-python && git init

Step 2: Move Code

cp -r ../diffx/diffx-js/* ./diffx-js/
cp -r ../diffx/diffx-python/* ./diffx-python/

Important: I discarded Git history. Keeping it would complicate everything.

Step 3: Independent Cargo.toml

diffx-js and diffx-python now pull diffx-core from crates.io.

# diffx-js/Cargo.toml
[dependencies]
diffx-core = "0.6"  # versioned dependency instead of path

Step 4: Remove Them from the Monorepo

# diffx/Cargo.toml
[workspace]
members = ["diffx-core", "diffx-cli"]
# diffx-js and diffx-python removed

Structure After the Split

/home/kako-jun/repos/
├── diffx/           # Rust only (simple)
│   ├── diffx-core/
│   ├── diffx-cli/
│   └── .github/workflows/
│       ├── ci.yml
│       └── release.yml
│
├── diffx-js/        # npm only
│   └── .github/workflows/
│       ├── ci.yml
│       └── release.yml
│
└── diffx-python/    # pip only
    └── .github/workflows/
        ├── ci.yml
        └── release.yml

Benefits

Understandable CI/CD: From six workflows + shared repo to two per repo.
Independent releases: No rush; each language can ship on its own cadence.
Clear ownership: Each repo has a single responsibility.
Easier contributions: Node devs only need to read diffx-js.

Chapter 5: Release Workflow Tips

Splitting the repos taught me one critical principle.

Never Combine Build and Publish

Anti-pattern

# ❌ Dangerous workflow
name: Release
on:
  push:
    tags: ["v*"]

jobs:
  build-and-publish:
    steps:
      - run: cargo build --release
      - run: cargo publish # publishes before confirming all builds succeed

Why it's bad:

What if Windows/macOS/Linux builds succeed except one?
cargo publish cannot be undone.
Even if you notice, the only fix is to bump the version.
You burn versions for no reason (v0.6.1 → v0.6.2 → v0.6.3...).

Correct Approach: Two-Stage Release

# ✅ Safe workflow (release.yml)
name: Release
on:
  push:
    tags: ["v*"]

jobs:
  build-linux:
    runs-on: ubuntu-latest
    steps:
      - run: cargo build --release
      - uses: actions/upload-artifact@v4

  build-macos:
    runs-on: macos-latest
    # ...

  build-windows:
    runs-on: windows-latest
    # ...

  create-release:
    needs: [build-linux, build-macos, build-windows]
    steps:
      - uses: actions/download-artifact@v4
      - uses: softprops/action-gh-release@v1
        with:
          files: |
            diffx-linux/*
            diffx-macos/*
            diffx-windows/*

# ✅ Publish is a separate workflow (publish.yml)
name: Publish
on:
  workflow_dispatch:
    inputs:
      version:
        description: "Tag to publish"
        required: true

jobs:
  publish:
    steps:
      - run: gh release view v${{ inputs.version }} # confirm release exists
      - run: cargo publish

Why Two Stages?

Step 1: Push tag → build for all platforms → create GitHub release
        ↓
        Stop here. A human verifies everything.
        ↓
Step 2: Manually trigger the publish workflow
        → Push to crates.io / npm / PyPI

Failure scenarios

Scenario	One-stage workflow	Two-stage workflow
macOS build fails	Broken release already public	Nothing published
Recovery	Must release v0.6.2, v0.6.3…	Delete tag, re-push
Version consumption	Wasteful	Efficient

Chapter 6: Reboot Playbook

Correct Reboot Order

1. Run the code yourself and find the truth.
2. Write specs in docs/specs/.
3. Build tests from those specs.
4. Fix the implementation until tests pass.
5. Update docs (README, etc.) to match the specs.

Anti-patterns

Writing docs first → they turn into lies.
Trusting existing tests → they only confirm the facade.

What to Delete

Old tests written without specs.
examples/ directories (they rot into lies).
Old roadmaps (already executed or obsolete).
Promo materials (stale after six months).

What to Keep

docs/specs/ – the single source of truth.
tests/cmd/ – docs enforced by tests.
.claude/tasks.md – current task list.
CLAUDE.md – minimal development rules.

Time Budget

Specs: 1 session
Tests: 1 session
Docs: 1 session
Cleanup: 1 session

Total: about four sessions (one session = one context window).

Recap

Before (August 2025)

❌ Frozen for 3 months
❌ Monorepo complexity
❌ Broken CI/CD
❌ Maintaining three languages
❌ Happy as long as "it runs"
❌ Blind faith in existing code

After (December 2025)

✅ Back in motion
✅ Lean Rust-only repo
✅ Separate language-specific repos
✅ Focused on Japanese docs
✅ Obsessed with correctness
✅ Doubt everything

Quantitative Changes

Metric	Before	After
Files	Many	-109
Lines	Many	-27,770
Tests	436 (meaning?)	88 (spec-driven)
README	3 languages	3 languages
Repositories	1 (monorepo)	3 (per language)

Key Lesson

Reviving a project after three months of stagnation didn't require new features or fancy tech.

It required the courage to doubt and the courage to delete.

Doubt existing tests.
Doubt the docs.
Doubt AI status reports.
Doubt your own sense of "done."
Delete anything suspicious.

I used to wonder why smart people fall for sunk-cost fallacy. Turns out I'm one of them.

You cling to tests, docs, CI/CD—because "throwing them away" feels wasteful. But keeping broken artifacts helps no one. I finally practiced what I preached and deleted them.

That's the heart of the reboot and the key to sustainability.

Bonus: pre-commit Is Mandatory for AI-Assisted Code

AI introduces a subtle issue.

VS Code's format-on-save never runs.

When humans code in VS Code, formatters and .editorconfig apply automatically. When AI writes files directly, none of that triggers.

The result:

Misaligned indentation
Missing trailing newlines
Random import ordering
Trivial lint warnings everywhere

CI fails over nonsense and wastes time.

Solution: pre-commit hooks

Set up pre-commit so formatting and linting run before every commit. Here's the actual config from diffx-python:

# .pre-commit-config.yaml (diffx-python)
repos:
  - repo: local
    hooks:
      - id: cargo-fmt
        name: cargo fmt
        entry: cargo fmt --
        language: system
        types: [rust]
        pass_filenames: false

      - id: cargo-clippy
        name: cargo clippy
        entry: cargo clippy -- -D warnings
        language: system
        types: [rust]
        pass_filenames: false

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.8.6
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
      - id: check-added-large-files

# Setup
pip install pre-commit
pre-commit install

In diffx-js (Node.js) I use Husky instead:

// package.json (diffx-js)
{
  "scripts": {
    "prepare": "husky"
  },
  "devDependencies": {
    "husky": "^9.1.7"
  }
}

This way, AI-written code gets auto-formatted at commit time.

Repositories

kako-jun / diffx

diffx

日本語

Semantic diff tool for structured data (JSON/YAML/TOML/XML/INI/CSV). Ignores key ordering and whitespace, shows only meaningful changes.

Why diffx?

Traditional diff doesn't understand structure:

$ diff config_v1.json config_v2.json
< {
<   "name": "myapp",
<   "version": "1.0"
< }
> {
>   "version": "1.1",
>   "name": "myapp"
> }

A simple key reordering shows every line as changed.

diffx shows only semantic changes:

$ diffx config_v1.json config_v2.json
~ version: "1.0" -> "1.1"

Installation

# As CLI tool
cargo install diffx

# As library (Cargo.toml)
[dependencies]
diffx-core = "0.6"

Usage

# Basic
diffx file1.json file2.json

# Output example
~ version: "1.0" -> "1.1"
+ features[0]: "new-feature"
- deprecated: "old-value"

Supported Formats

JSON, YAML…

View on GitHub

kako-jun / diffx-js

diffx

Node.js bindings for diffx - semantic diff for structured data (JSON, YAML, TOML, XML, INI, CSV). Powered by Rust via napi-rs for blazing fast performance.

Installation

npm install diffx-js

Supported Platforms

Platform	Architecture
Linux	x64 (glibc)
Linux	x64 (musl/Alpine)
Linux	ARM64
macOS	x64 (Intel)
macOS	ARM64 (Apple Silicon)
Windows	x64

Usage

Basic Diff

const { diff } = require('diffx-js');

const old = { name: "Alice", age: 30 };
const newObj = { name: "Alice", age: 31, city: "Tokyo" };

const results = diff(old, newObj);

for (const change of results) {
  console.log(`${change.diffType}: ${change.path}`);
  // Modified: age
  // Added: city
}

With Options

const results = diff(data1, data2, {

…

View on GitHub

kako-jun / diffx-python

diffx

Python bindings for diffx - semantic diff for structured data (JSON, YAML, TOML, XML, INI, CSV). Powered by Rust via PyO3 for blazing fast performance.

Installation

pip install diffx-python

Supported Platforms

Platform	Architecture
Linux	x64 (glibc)
Linux	x64 (musl/Alpine)
Linux	ARM64
macOS	x64 (Intel)
macOS	ARM64 (Apple Silicon)
Windows	x64

Usage

Basic Diff

import diffx

old = {"name": "Alice", "age": 30}
new = {"name": "Alice", "age": 31, "city": "Tokyo"}

results = diffx.diff(old, new)

for change in results:
    print(f"{change['type']}: {change['path']}")
    # Modified: age
    # Added: city

With Options

results = diffx.diff(data1, data2
    epsilon=0.001,                      # Tolerance for float comparison
    array_id_key='id',                  # Match array elements

…

View on GitHub

I haven't written formal release posts yet, but the initial versions of these projects work, and that's enough to prove the reboot process is repeatable—at least for my ecosystem.

kako-jun / diffai

diffai

日本語

Semantic diff tool for AI/ML models (PyTorch, Safetensors, NumPy, MATLAB). Provides tensor statistics, parameter comparisons, and automatic ML analysis.

Why diffai?

Traditional diff doesn't understand binary ML files:

$ diff model_v1.pt model_v2.pt
Binary files model_v1.pt and model_v2.pt differ

diffai shows meaningful analysis:

$ diffai model_v1.safetensors model_v2.safetensors
learning_rate_analysis: old=0.001, new=0.0015, change=+50.0%
gradient_analysis: flow_health=healthy, norm=0.021
~ fc1.weight: mean=-0.0002->-0.0001, std=0.0514->0.0716
~ fc2.weight: mean=-0.0008->-0.0018, std=0.0719->0.0883

Installation

# As CLI tool
cargo install diffai

# As library (Cargo.toml)
[dependencies]
diffai-core = "0.5"

Usage

# Basic
diffai model1.pt model2.pt

# JSON output for automation
diffai model1.safetensors model2.safetensors --output json

# With numerical tolerance
diffai weights1.npy weights2.npy --epsilon 0.001

Supported Formats

PyTorch (.pt, .pth) - Full ML analysis + tensor statistics
Safetensors (.safetensors) - Full ML analysis + tensor statistics
NumPy (.npy, .npz) - Tensor statistics
MATLAB (.mat) - Tensor statistics

Main Options

--format <

…

View on GitHub

kako-jun / lawkit

lawkit

日本語

Statistical law analysis toolkit. Analyze data for Benford's law, Pareto principle, Zipf's law, Normal and Poisson distributions. Detect anomalies and assess data quality.

Installation

cargo install lawkit

Supported Laws

Benford's Law (Fraud Detection)

$ lawkit benf financial_data.csv
Benford Law Analysis Results

Dataset: financial_data.csv
Numbers analyzed: 1000
[LOW] Dataset analysis

First Digit Distribution:
1: ███████████████┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  30.1% (expected:  30.1%)
2: █████████┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  17.6% (expected:  17.6%)
3: ██████┃░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  12.5% (expected:  12.5%)
...

Pareto Principle (80/20 Rule)

$ lawkit pareto sales.csv
Pareto Principle (80/20 Rule) Analysis Results

Dataset: sales.csv
Numbers analyzed: 500
[LOW] Dataset analysis

Lorenz Curve (Cumulative Distribution):
 20%: ███████████████████████████████████████┃░░░░░░░░░░  79.2% cumulative (80/20 point)
 40%: █████████████████████████████████████████████░░░░░  91.5% cumulative
...

80/20 Rule: Top 20% owns 79.2% of total wealth (Ideal: 80.0%, Ratio: 0.99)

Zipf's Law (Frequency Distribution)

$ lawkit zipf word_frequencies.csv
Zipf Law Analysis Results
Dataset: word_frequencies.csv
Numbers analyzed: 1000
[LOW] Dataset analysis

Rank-Frequency Distribution:
# 1: █████████████████████████████████████████████████┃  11.50% (expected: 11.50%)
# 2:

…

View on GitHub

Introducing Diffx: A Rust-Based AI Diff Tool That Understands Structure

kako-jun — Sun, 06 Jul 2025 05:09:56 +0000

Ever struggled with meaningless diffs caused by commas or formatting?

I did too — so I built Diffx, a Rust-based AI tool that understands structure.

Here's how it works and why it might change how you compare files.

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	Config Support	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).

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

Feedback, bug reports, and feature requests are all welcome.
Thank you for reading to the end.