diffthing

diffthing-image
diffthing

Inspiration

The catalyst for diffthing was a simple payment checkout page. Out of curiosity, I tasked two leading coding models with building the interface. Both models returned syntactically flawless, working code on their first attempt. Yet both made the same architectural assumption: The agent implemented the entire checkout flow as a client-side Single Page Application.

For an interactive, data-dense dashboard, client-heavy rendering is justified. For a transactional checkout sequence, it is a poor engineering trade-off. Server-side rendering drastically reduces the initial JavaScript payload, lowers time-to-interactive, and improves resilience on degraded mobile networks. The models did not fail technically; they defaulted to commodity patterns because network boundaries and performance budgets were never specified in the prompt.

This highlighted a foundational rule of the agent era: an AI cannot optimize for constraints it has not been given, and a developer cannot supply guidance on trade-offs they have not personally reasoned through. This realization forced an inversion of my daily workflow. I now establish system architecture and technical invariants before writing a single line of prompt text. The agent handles execution; my responsibility is auditing the resulting diff to verify that it adheres to those decisions.

What it does

diffthing is a local-first code review engine designed around a single operational boundary: the AI organizes; the developer reviews.

When executed via npx diffthing inside a repository, the tool evaluates the current working tree against a Git baseline. Instead of presenting a raw alphabetical file dump, it asks an available coding agent to propose a structured narrative walkthrough. The walkthrough groups related changes into scopes, sequences review steps, and describes each step concisely.

The proposal is not trusted by default. A deterministic validator verifies that it references real hunks, covers every hunk exactly once, and follows required ordering rules. If validation fails, diffthing retries and then falls back to deterministic file order.

Crucially, the model does not assign risk, approve code, or resolve review comments. Deterministic code calculates impact signals; technical judgment, architectural verification, and final approval remain entirely with the developer.

How we built it

We structured the platform around a local-first architecture inspired by the ergonomics of Drizzle Studio. The system is split into two execution environments that communicate over a local bridge: a Rust CLI daemon running on the host machine, and a React frontend served by that same local daemon.

By default, the interface is served over HTTPS at local.diffthing.dev, whose public DNS resolves to 127.0.0.1. The browser then establishes a token-gated, same-origin WebSocket connection back to the local daemon. An offline mode serves directly from loopback when DNS or the certificate is unavailable.

Under the hood, we implemented four core mechanics:

The Deterministic Validator Gate: A strict verification layer between the language-model walkthrough proposal and the UI. It verifies schema validity, hunk references, complete coverage, and ordering before accepting an AI-generated walkthrough.
Content-Hashed Hunk Identity: A tracking mechanism that identifies changed code by hashing its path and normalized hunk content rather than UI position or line numbers, preventing structural drift during active review sessions.
Incremental Reconciliation: A state engine that reconciles filesystem changes against the active review state. Viewed hunks changed underneath the reviewer return as changed since viewed; removed flagged hunks preserve their comment history.
The Review State Engine: A local persistence layer for viewed state, open review threads, agent responses, and agent change claims. Human resolution remains explicit and never occurs automatically.

diffthing can also send a hunk-anchored question or explicit change request to the developer’s chosen coding-agent CLI. Questions receive answers without edits; explicit change requests may modify the scoped files. Agent claims are recorded in the review thread, but never count as approval.

Challenges we ran into

Our primary technical hurdle was behavioral: language models are strongly optimized to act as helpful chat assistants. They naturally try to critique code, explain syntax, or make recommendations beyond their assigned role. We needed a clear product boundary: the walkthrough model proposes organization, while deterministic code verifies structural correctness and the human retains every judgment call.

On the systems side, maintaining diff stability during an active review session proved complex. In a standard Git workflow, worktree edits and staging can alter line numbers or remove hunks entirely. We abandoned UI-position tracking in favor of content-hashed hunk identity, then built reconciliation rules that preserve review honesty when code changes underneath the reviewer.

We also had to make a local HTTPS interface communicate safely with a local daemon. That required loopback-only binding, fragment-held session tokens, origin validation, and a versioned WebSocket handshake.

Accomplishments that we're proud of

We are most proud of building a review workflow that preserves developer ownership in an agent-heavy coding environment. The AI can organize a large diff and execute an explicitly requested change, but it cannot approve code, resolve a thread, or silently preserve stale review state.

We are also proud of the local-first delivery model. The daemon, Git operations, review state, and browser connection stay on the developer’s machine. Source context leaves the machine only when the developer explicitly chooses a coding-agent CLI that sends work to an external provider, under that provider’s own terms.

Beyond the infrastructure, we challenged the prevailing industry narrative that AI should act as an autonomous code reviewer. diffthing treats the model as a structural assistant and gives the human reviewer the final word.

What we learned

Building diffthing reinforced that software engineering is not being replaced by automation; rather, the mechanical implementation layers are being commoditized. The rote work of generating boilerplate components or state wiring has been absorbed, leaving behind the harder engineering problems: system architecture, network performance budgets, design-system consistency, and domain-specific trade-offs.

We also learned that you cannot prompt your way out of missing context. If an engineer does not actively own the foundational architecture before engaging an agent, the resulting software will drift toward generic, unoptimized patterns. AI accelerates execution, but it amplifies both good and bad judgment equally.

What's next for diffthing

We are expanding the tool from a reactive viewer into a proactive verification engine. The immediate roadmap includes:

Review Against Intent: A mechanism to declare architectural invariants and structural rules upfront, allowing the walkthrough to highlight where agent-generated code may diverge from stated specifications.
Pull Request Mode: Extending the walkthrough engine to GitHub and GitLab pull requests, bringing structured AI-organized navigation to collaborative team reviews.