Codiff picks its agent CLI by checking whether four executables exist

The agent backend is chosen by checking whether four executables exist

Walkthroughs and inline review assistance run through a local agent command line program, and the first launch picks one for you. With no existing config file, Codiff looks for Codex, then Claude Code, then OpenCode, then Pi, and takes the first one it finds. The selection is then written to the config and reused.

The check is described in one clause that matters: it tests executable presence only. It does not authenticate, does not check the version, and does not confirm that the CLI is configured for the model you intend to use. So a stale binary earlier on the path, a tool installed but never logged in, or a shim that exists and fails on first call will all pass the test and become the persisted backend. If none of the four are installed, the choice is Codex anyway, which means the default is a program that is not present.

After the first launch the selection is yours to change, through the agentBackend config value, an --agent flag for a single run, or the application menu. The four values are codex, claude, opencode and pi, and each maps to its own model setting.

The command line tool and the desktop app are installed by two different routes

There are two distributions here and they are documented separately. The app comes as a download from the releases page, and the command line tool is added afterwards from inside the application, with an Install Terminal Helper item in the Codiff menu. Only after that does `codiff` exist in your shell.

There is also a Homebrew cask, and the install line is short:

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

The repository ships a third path that is not in the page at all. Its package manifest is private, declares a bin entry mapping the codiff command to a script in the bin directory, and lists what goes into the tarball: bin, the four agent vendor directories named after the CLIs it can drive, config, core, dist and electron. So an npm consumer gets the command line side without the packaged desktop app, while the Homebrew and releases routes give you the application and a helper that is installed by the application itself.

What the CLI accepts is mostly targets: no argument for the current repository, a path, a commit, a branch to compare against, or a pull request and merge request number. Shell completions are printed by the program itself for bash, fish and zsh, completing flags, their accepted values and Git refs.

The config file is watched live, and the published example is not valid JSON

Configuration lives in one file, ~/.codiff/codiff.jsonc, and the application can create it with defaults from the menu. It accepts comments and trailing commas, carries a schema reference for editor completion, and is watched while Codiff runs, so a change applies to open windows without a restart.

The example published for that file is deliberately not strict JSON, which is worth knowing before you paste it into a script or a diff tool:

{
  "$schema": "https://raw.githubusercontent.com/nkzw-tech/codiff/main/core/config/codiff-config.schema.json",
  "settings": {
    "agentBackend": "codex",
    "claudeModel": "claude-sonnet-4-6",
    "codeFontFamily": "",
    "codeFontSize": 13,
    "copyCommentsOnClose": false,
    "diffStyle": "split",
    "editorCommand": "",
    "lastRepositoryPath": "",
    "openAIModel": "gpt-5.6-terra",
    "opencodeModel": "opencode-default",
    "sidebarPosition": "left",
    "showWhitespace": false,
    "theme": "system",
    "walkthroughPrompt": "",
    "wordWrap": false,
  },
  "keymap":

The block stops at the keymap key, so the shortcut section is named but not shown, and the trailing comma after wordWrap is legal here and nowhere else. Two settings carry more weight than their names suggest. showWhitespace, off by default, hides whitespace-only changes from the working tree review state entirely, so turning it on changes what the review considers a change. And lastRepositoryPath is application state living in a file you are invited to edit by hand.

GitHub lookups shell out to gh and GitLab to glab

Reviewing a pull request from the command line is three forms:

codiff pr 75
codiff pr owner:my-feature-branch
codiff mr 23

The mechanism behind them is delegation. Branch lookup uses the GitHub command line tool and selects an open pull request, and the owner prefix exists because pull requests from forks are not found by branch name alone. Full review URLs are also accepted, so a copied link from a browser works without translating it.

GitLab goes through its own tool. Hosts and nested project paths are derived from the URL or from the local Git remote, and authentication is handled by that tool rather than by a token in Codiff's config. The file makes a point of this: no instance-specific configuration is required, which is the right answer for teams spread across self-managed instances, and it also means the feature is unavailable if the tool is not installed or not authenticated.

That is the general shape of the integrations here. Comments go back to GitHub pull requests and GitLab merge requests, or can be copied as Markdown for follow-ups when neither is available. Nothing in the review path needs an account with Codiff itself.

Walkthrough sharing uploads the walkthrough and prints a URL

Two flags cover the same output. The plain one opens the application with a generated narrative walkthrough, and the sharing one does the same work without opening the window, uploading the result and printing the final link:

codiff --share
codiff --share HEAD

The condition attached to that is the interesting part. Sharing is available when it is available for your Git identity, which places the decision on a server rather than in your config, and it means a machine with no sharing entitlement will silently fall back to the non-sharing path. There is no local flag that turns the upload off.

Target resolution is documented and worth knowing, because the same default applies to both forms. With no explicit target, a walkthrough uses local changes when there are any, and falls back to HEAD when the working tree is clean. So `codiff -w` on a dirty tree describes your uncommitted work, and the same command on a clean tree describes the last commit. Passing an explicit ref removes the ambiguity.

The application also opens a separate native window per repository when it is launched against several at once, which is the behaviour you want when comparing a change against a branch in another checkout.

Walkthrough models are pinned by config, and the file ends mid-word

Each backend has its own model setting, and the defaults are written into the config file rather than hidden in code. The Codex path uses settings.openAIModel with a default of gpt-5.6-terra, Claude Code uses settings.claudeModel with claude-sonnet-4-6, OpenCode uses settings.opencodeModel with opencode-default, and the Pi CLI uses whatever model it is already configured with.

Reasoning effort is part of the model choice rather than a separate control. Codex walkthroughs default to Terra with low reasoning, and the application menu also offers Sol and Luna at medium reasoning. A further set of models, named as Astra, Sol and Luna, can be set by model id in the same setting, and the sentence explaining their defaults is the last one on the page, breaking off inside the word for default.

That last fragment is worth flagging for anyone writing documentation about this tool, because it is the only statement about those three models and it is incomplete. What is clear is that model selection is a config value, that a single flag can override the backend for one launch, and that walkthrough generation is evaluated by a script in the repository, so the output quality has an evaluation harness rather than being left to inspection.

The build has five surfaces and a build script per platform

The repository is a workspace with an application, a service, a web bundle and shared core, and the root scripts name each of them by filter rather than by directory. The main build compiles the core, service and web packages in that order and then builds the app. Test runs exist for unit level work and, separately, for integration tests behind their own filter.

Packaging goes through Electron Forge and is scripted per platform: a macOS build for arm64, a Linux package for x64, a Windows make, and a continuous integration target that chains a general build with a Linux x64 package and a Windows make in one command. The native dependency list explains two of those choices, with a Windows installer startup helper and a native keymap library, the latter matching the Mod key convention the documentation uses for shortcuts.

Two other directories are worth a look. An evals directory with a walkthrough runner means generated narratives are tested rather than eyeballed, and an examples directory contains a definition navigation example with its own runner, matching the feature described as finding likely local definitions with a modifier click and no language server. A .env file sits at the repository root next to the configuration schema, and the agent instructions file is at the top level rather than in the contributor documentation.

Editorial conclusion

Codiff is a review tool first and an agent client second, and that ordering is the right way to evaluate it. The diff surface is conventional and complete, the review comments go back to GitHub and GitLab through their own command line tools rather than through a bespoke integration, and the configuration is a single JSONC file that is watched while the app runs. Two things to check before you rely on it. The agent backend is chosen by executable presence only, so if you have several CLIs installed the wrong one wins and stays chosen until you change a setting. And walkthrough sharing is an upload that returns a URL, gated on something being available for your Git identity, so treat a shared walkthrough as leaving your machine and read the sharing terms before using it on unreleased code.

Frequently asked questions

Official sources

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