Codiff: a local diff viewer with LLM walkthroughs and inline review comments

What Codiff solves, and who it is built for

Most diff tools answer one question: what changed. Codiff is aimed at the step after that, which is deciding whether to commit it. The README frames the project as a diff viewer for reviewing Git changes and committing them, and the feature list separates two audiences that usually get different tools. The first is anyone who wants a fast local review of a working tree, a specific commit, or a branch compared against another branch. The second is reviewers who need to leave comments on a GitHub pull request or GitLab merge request without leaving the diff.

The repository layout backs that up. There are separate top-level directories for `core`, `electron`, `web`, `service`, `claude`, `codex`, `opencode` and `pi`. The agent directories are not incidental: walkthroughs and inline review assistance are routed through a local agent CLI, and each of those four names is a supported backend. That is a deliberate bet that the reviewer already runs a coding agent locally. If you do not, the walkthrough half of the product is unavailable to you and you are left with the diff viewer.

How the Electron app, agent backends and forge clients fit together

The package name is `codiff`, the version in `package.json` is 1.14.0, and the entry point is `./electron/main.cjs`, so the shipped artifact is an Electron application rather than a terminal program that happens to have a window. The `bin` field maps the `codiff` command to `./bin/codiff.js`, which is why running the command can open a native window. The README notes that launching Codiff in multiple repositories opens a separate native window for each repository, so the process model is one window per repository rather than a tabbed single instance.

Walkthrough generation is delegated. On first launch without a config file, Codiff checks for an installed agent CLI in a fixed order: Codex, Claude Code, OpenCode, then Pi. The README is explicit that this "checks executable presence only and persists the selection", and that if none are installed Codiff keeps Codex as the default. That default is a stored preference, not a working backend, so a machine with no agent CLI will still record `codex` and walkthroughs will not run until something is installed. After the first launch, the backend comes from `settings.agentBackend` in the config file or from the `--agent` flag for a single launch.

Forge integration is split by host. Branch lookup for GitHub uses `gh` and selects an open pull request, with `owner:` required for pull requests from forks. GitLab review URLs and merge requests are authenticated through `glab`. The README states that GitLab hosts and nested project paths are derived from the URL or the local Git remote, and that Codiff does not require instance-specific configuration. That is a real simplification for self-hosted GitLab, where per-instance setup is a common friction point.

Installing Codiff and running a first review

The README gives Homebrew as the install path, using a cask from the project's own tap:

brew install --cask nkzw-tech/tap/codiff

After the app is installed, the README says to run `Codiff > Install Terminal Helper` from the application menu to make the `codiff` command available in your shell. The README also points to GitHub Releases for downloading the latest app directly, which is the route to take if you are not on a machine with Homebrew.

Once the helper is installed, running the command with no arguments inside a repository opens the viewer for that repository, and a path can be passed instead:

codiff
codiff /path/to/repository

Targets are positional. A commit hash reviews that commit, and a branch name reviews the current branch against that target:

codiff a1b2c3d
codiff main

To start with a generated narrative walkthrough rather than the raw diff, use the `-w` flag. The README states that when no explicit target is given, Codiff uses local changes when present and falls back to `HEAD` when the working tree is clean:

codiff -w
codiff -w a1b2c3d

If you want to know what else the binary accepts before committing to a workflow, the README points at `codiff --help`. It also documents that Codiff prints its own shell completions for bash, fish and zsh, covering every flag, the values those flags accept, and Git refs for the ref argument. Completions are the cheapest way to find out whether a flag you expect actually exists.

Configuration lives in one watched JSONC file

Settings are read from `~/.codiff/codiff.jsonc`. The README says to use `Codiff > Open Config File...` to create the file with defaults and open it in your editor. The file supports JSONC comments and trailing commas, carries a `$schema` reference for editor completion, and is watched while Codiff is running, so edits apply to open windows without a restart. That last property is the one worth knowing about, because it means you can tune the view while looking at the diff you are trying to read.

The default file shows the shape of the settings. `settings.diffStyle` takes `split` or `unified`, `settings.wordWrap` toggles line wrapping, `settings.codeFontSize` is a number, and `settings.sidebarPosition` takes `left` or `right`. The `keymap` block maps actions such as `commandBar`, `fileFilter` and `submitComment` to strings like `Mod+k`, where `Mod` means Cmd on macOS and Ctrl elsewhere.

One setting has behaviour that is easy to misread. The README says to set `settings.showWhitespace` to `true` to show whitespace-only changes in diffs and file line counts, and that when it is `false` Codiff hides those changes from the working-tree review state. So this is not purely cosmetic: with the default `false`, whitespace-only edits are excluded from the review state, which is convenient for noisy reformatting and risky if a whitespace change is the change you meant to inspect.

File opening is configurable through `settings.editorCommand`, with `{file}`, `{line}` and `{repo}` placeholders. The README's example is `"subl \"{repo}\" \"{file}\""`. The command bar, opened with Cmd+Shift+P on macOS or Ctrl+Shift+P elsewhere, exposes the same actions as the menus, including Copy Review Comments and Copy Review Comments and Close.

Where Codiff is the wrong tool

The walkthrough feature has a hard dependency on a local agent CLI, and the README does not describe a fallback that generates walkthroughs without one. If your environment forbids running coding agents, or if the four supported backends are not the ones your organisation permits, the walkthrough and inline review assistance features are effectively closed to you. The first-launch detection order is also fixed, so a machine with several CLIs installed will pick Codex unless you change `settings.agentBackend`.

The GitHub and GitLab integrations shell out to `gh` and `glab` respectively. That means Codiff inherits whatever authentication and host configuration those tools already have, and it means a review workflow that does not use those CLIs has no documented path here. The README says nothing about other forges, and it does not document rollback or undo for a posted review comment. If you need to retract a comment after it lands on a pull request, the README is silent on how, so treat posting as the point of no return until you have verified otherwise.

Finally, this is a desktop application distributed as a Homebrew cask and through GitHub Releases. The README documents that install path and the terminal helper, but it does not describe a headless or server-side mode. Teams that review exclusively in a browser, or that need a diff viewer running inside CI, are outside what the documentation covers.

Codiff against Difftastic and terminal diff viewers

Difftastic is the natural comparison, and the difference is in what each tool considers its output. Difftastic is a structural diff: it parses source files and compares syntax trees, so it can report that a function moved rather than that a block of lines was deleted and re-added. Codiff's README makes no structural-diff claim. Its stated differentiators are review ergonomics: a native window per repository, a command bar, split or unified layouts, viewed-file toggling, and review comments that can be posted to GitHub or GitLab or copied as Markdown.

That places them on different axes. If your problem is that line-based diffs misrepresent refactors, a syntax-aware differ addresses the misrepresentation directly, and Codiff does not. If your problem is that reading a diff, deciding what to say about it, and then typing that comment into a browser tab is three separate contexts, Codiff collapses them into one window. The lightweight definition navigation in Codiff, where Mod/Ctrl-click on an identifier finds likely local definitions without starting a language server, sits closer to the structural camp but is described as heuristic rather than parse-based.

The terminal viewers occupy a third position. They are faster to start, scriptable, and work over SSH, and Codiff's README does not claim a terminal UI. The trade is that a terminal viewer cannot render the comment workflow or the walkthrough pane, because both need a window and a local agent.

Licence, maintenance and upgrade cost

Codiff is MIT licensed, per both the repository metadata and the `license` field in `package.json`. MIT is permissive: it allows use, modification and redistribution provided the copyright notice and permission notice are retained. That is the general shape of the licence, not advice about your situation; if you are embedding Codiff or its source in a product, read the LICENSE file in the repository and get your own answer.

On maintenance, the last push to the default branch was on 2026-09-16, and the most recent release, v1.14.0, is dated 2026-09-16. The two releases before it are v1.13.0 on 2026-09-08 and v1.12.1 on 2026-09-04. The repository is not archived. That cadence matters for upgrade cost in one specific way: the app is distributed as a Homebrew cask, so upgrades follow the usual `brew` flow for casks rather than a self-updating channel. The config file is the thing to watch across upgrades, since it carries a `$schema` URL pointing at `core/config/codiff-config.schema.json` on the main branch, and the README lists settings such as `agentBackend`, `openAIModel` and `opencodeModel` whose accepted values are tied to the agent backends Codiff supports at that version. If a backend is added or renamed, that file is where you will notice.

Editorial conclusion

Adopt Codiff if you review and commit changes inside local Git repositories and already have Codex, Claude Code, OpenCode or Pi installed, since walkthroughs depend on one of those CLIs being present. Skip it if you want a browser-based or hosted review tool, or if you only ever review through a forge's web UI. Before relying on it, confirm the Homebrew cask installs on your platform and that `codiff --help` lists the flags you need, and check which agent backend the first launch persisted into `~/.codiff/codiff.jsonc`.

Frequently asked questions

Official sources

1. License: MIT
2. nkzw-tech/codiff on GitHub
3. Project website
4. README
5. Releases