M

Building dffy, a Terminal Diff Viewer for Code Review

Reading Time: 9 min read
Date: November 22, 2026
Author: Alexandre Guimarães Malucelli

Building dffy: a Terminal Diff Viewer for Code Review

Claude Code is my daily driver these days, and at work we have loops that open their own pull requests, so I end up writing a lot less code than I read. Most of my day is diffs: what the agent changed in the last turn, what a loop opened overnight, what a teammate pushed.

GitHub’s diff view or plain git diff stops being enough once the diff is fifty files. I tried a lot of tools recently, and none of them fully fit how I work these days:

  • lumen has a nice review flow, but it builds in its own AI features, with its own model keys and providers. I already have an agent, and I want the viewer to work with that one.
  • hunk has the review UX I wanted, but it’s TypeScript on a JavaScript runtime, and it struggles on large repositories.
  • diffs.com renders diffs better than anything else I’ve used, but it runs in the browser, and I review from a laptop and over SSH from my phone.

So I built dffy. It’s a single Rust binary, focused on performance, and this post goes through the parts I care about most.

dffy showing a split diff with the file tree on the left


How it’s built

The decision everything else follows from is that the diff is a library, not a screen. There are three main components here. dffy-core owns the model (which lines changed, whether a line was edited, moved or only reformatted, the rows of the split and unified layouts, positions, navigation, search, and where comments land). It has no terminal code and doesn’t know what a code host is. Everything you can run is a thin layer on top of it:

dffy-core        the model: git access, diff engine, syntax diff,
                 highlighting, rows, positions, search, annotations

dffy             viewer · printed output · git's pager · --json
                 MCP server · control API for a running viewer

plugins          separate programs: Markdown and Mermaid renderers,
                 GitHub reviews, coding agents

It’s inspired by some of the decisions Ghostty made with libghostty, and the reason is practical. When the viewer, --json and the MCP server read the same model, an agent asking for a diff over MCP gets exactly what I see on screen, and a fix in the core fixes all of them. The rule I hold myself to is that if a feature only works by teaching the viewer a special case, the model is missing a concept, and the concept goes in the core.

The second one is that nothing waits for the whole diff. When I open the kernel range, dffy draws the first files as soon as it finds them and keeps listing the rest in the background. A file only gets diffed when it’s about to show up on screen, and only what’s on screen gets highlighted, so most of the 13,168 files never get diffed unless I scroll to them.

For that to work I ended up writing most of the pieces that decide what comes first and how much it costs. It uses gix to read git’s objects, but the tree diff, the status scan and the line diff itself are dffy’s own, so they can stream results and stop early. Same with the renderer: there’s no TUI framework, just a grid of cells where only the ones that changed get written to the terminal.

The last one is about who owns what. Every piece of state has one owner, and everything else has to ask it. Plugins are separate processes that talk to dffy over a small protocol and never touch its state, and dffy itself never touches the network (that’s the plugins’ job). That’s also what keeps GitHub out of the core.


It has to be fast on any repository

I wanted one rule for performance: the size of the repository or of the change shouldn’t change how the viewer feels. The baseline is the Linux kernel, v6.0 to v6.1, which is 13,168 changed files and a 48MB patch. Time until the first changed line is on screen:

dffylumen 2.32.0hunk 0.25.0dffy vs the next best
The v6.0..v6.1 range8.1ms12.5s18.1s99.9% faster
The working tree (5 files changed)77ms1.11s733ms89.5% faster
As a pager, git diff v6.0 v6.1 | …210msn/a15.2s98.6% faster
Memory, opening the range99MB676MB4.39GB85.4% less

A full frame takes about 150µs. As git’s pager it streams the whole 48MB patch in 3.1MB of its own memory, about as fast as git diff writes it.

Keeping it that way is hard, because every feature is a chance to make a frame slower. I was so obsessed with that, I built a whole pipeline that times frames, scrolling, search and startup against main, so every change gets measured before it ships. A change that makes scrolling a few percent slower doesn’t merge until I find out why.


Review comments live next to the code

Reading a diff is only half of a review, the other half is writing down what’s wrong, and I wanted both in the same place.

I select some lines, press c, and a thread opens right under them, where I can reply, resolve it or suggest a change. Comments are saved in a plain JSON file inside the repository’s git directory, per branch, and they’re anchored to the text they were written on instead of a line number, so when the code above moves, the comment moves with it.

And since it’s just a file, the same comments are available from the CLI too:

dffy comments --open              # the open threads, with their ids
dffy comments prompt 9f3c2a71b04e5d18   # one thread as a prompt for an agent
dffy comments apply --as claude < ops.json   # an agent adds its own

Only dffy writes to that file. The viewer, the CLI and the MCP server all send it a list of operations and it applies them under a lock, which is what lets an agent reply in one thread while I’m typing in another without one of us losing a comment.


The agent you already use

This is another reason I built dffy instead of picking one of the others. I don’t want another AI inside my diff viewer, I want the one I already pay for, with all my setup, to be part of my review.

Ask. I press a on a thread, write my question, and Claude Code, Codex or Pi answers right there as a reply, with a suggested change if it has one. It runs read-only (for Claude Code that means only Read, Grep and Glob, no MCP servers and no saved session), and it gets the thread, the lines, the changes around them and the function they’re in. The answer stays private, and nothing goes to GitHub until I press A and make it mine.

Fix. When I want the agent to actually change the code, I press f and dffy opens a new tab in the terminal I’m using (tmux, Ghostty, WezTerm, kitty, herdr and a few others) with my own agent running there: Claude Code, Codex, Pi or Amp, in its normal mode, with my settings, my CLAUDE.md and my MCP servers. It’s the exact same session I’d start by hand, nothing special about it.

And instead of pasting the whole thread, it only gets one line:

Address dffy review thread <id>: run dffy comments prompt <id> (or the thread_prompt MCP tool), change only what the thread asks, then reply in the thread with what you changed.

The agent reads the thread through dffy itself, so it always sees the latest version of it. When it’s done it replies in the thread with its own name, and I see the reply in my viewer while I’m still there. Its edits are just unstaged changes, so with --watch on I can see them landing while it works, and stage or discard them like anything else.

If there’s no thread yet, I can select some lines and use space then &, which asks me what should change there first. And space then ^ sends all my open threads at once.

Apply. When a thread already has a suggested change, s applies it to the working tree (as an unstaged change), and refuses if those lines changed in the meantime. Pressing s again puts the old lines back.

Claude Code answering a review thread inline in dffy

Before the agent starts, dffy also takes a checkpoint, which is a snapshot of the working tree saved under a git ref only that worktree sees. So when the agent is done, I can look at only what it changed:

dffy checkpoint             # save the working tree
dffy --since-checkpoint     # what changed since, which is the agent's turn

Without that, its changes get mixed with everything else I had uncommitted, and I end up reading the whole diff again just to review one turn.

Agents read diffs through dffy too

By default an agent reads changes with git diff, which dumps every file into its context at once, formatting noise included, and that’s not a good way to spend tokens. dffy gives it two better options.

For agents with a shell, dffy agents setup installs a skill for Claude Code, Codex, Pi and Amp. It tells them to look at the list of changed files first, read only the ones that matter, and reply in my threads with dffy comments apply --as <name> instead of touching the comments file.

For agents without a shell, or in a sandbox that blocks .git, there’s dffy mcp with the same tools:

claude mcp add dffy -- dffy mcp

When the viewer is open, the MCP server can also talk to it, so I can select lines in dffy, ask Claude “what’s wrong with these lines?”, and it reads the selection without me copying anything.

My CLAUDE.md has one line for it:

To see what changed in the current git repository, use dffy tools instead of git diff or git show

GitHub is a plugin

Part of my work is still review pull requests (who knows how the industry will look like in a year), so dffy needed GitHub. But I didn’t want GitHub inside the viewer, because I don’t want to tie it to it, and maybe in some near feature I want to support GitLab, and maybe others.

So the core doesn’t know anything about code hosts. A review integration is a separate program called dffy-review-<name>, which dffy starts and talks to over JSON-RPC (stdin and stdout). It sends back operations on the comments file, and dffy applies them like any other change. The GitHub one uses gh for the API and git fetch for the code:

dffy pr 123     # a pull request, with its threads and a Conversation page
dffy            # on a branch with an open PR, its comments join your changes

My comments become drafts, and P posts all of them as one review. Each one keeps the id GitHub gave it after it’s posted, so if something crashes halfway through, a retry doesn’t post the same comment twice.

The agent integration works the same way. dffy-agent is its own program and it’s the only thing that knows how to run each CLI read-only, so when Claude Code changes a flag, I can fix the plugin and everything else, like the viewer doesn’t need to change.


Try it

brew install --cask amalucelli/tap/dffy
brew install --cask amalucelli/tap/dffy-agent            # ask and fix with your agent
brew install --cask amalucelli/tap/dffy-review-github    # GitHub pull requests

Then run dffy in any repository. It also works as git’s pager, as the git add -p filter and as a difftool, and if you are still interested in, the README has the rest.

If you think this might be useful for you, give it a try and let me know what you think.

Subscribe to RSS feed