Scripting and AI Assistants

Everything Diffoniq shows on screen it can also deliver headless. Two commands cover the two halves of unattended work: /report answers “what is different?” as a file, /sync acts on the answer. Both report through an exit code, an output file and a log file — which is exactly what batch files, CI jobs, the Windows Task Scheduler and AI assistants can work with. Started through the console launcher DiffoniqC.exe, they also print their log lines and the shell waits for them like for any console tool.

CommandWhat it doesFull page
/report Compare two files, folders or archives and write the result as HTML, text or JSON. Read-only. Comparison Reports
/sync Synchronize two folders — dry run by default, applied with --execute. Folder Synchronization

The compare switches of a normal start work with both — the same engine runs underneath, including the hash cache and rename detection. Spell the command switch as /report or /sync, as shown on their pages.

The contract: exit code and JSON

Both commands follow the same scheme — a script can branch on the exit code alone:

ExitMeaning
0No differences
1Differences — report written · sync planned or applied
2Trouble with the outcome — report file not writable · sync finished with errors
3Invalid arguments, or the run failed before doing anything

When something has to act on the differences rather than glance at the count, ask for --format json. The document lists every compared item with a status, both sides with real numbers and ISO timestamps, and a summary block — JSON for scripts describes each key. Two rules matter for any consumer: a side that does not exist is null, and unverified and notCompared are states of their own — never treat them as identical (add --content when the decision must be final).

Connecting an AI assistant (MCP)

AI assistants such as Claude Code, Claude Desktop, Cursor and GitHub Copilot in VS Code can use Diffoniq directly as a tool. They speak the Model Context Protocol (MCP), and DiffoniqC.exe /mcp is a Diffoniq MCP server: the assistant starts it, asks it to compare, and gets the answer as structured data instead of having to read a screen or a file. It offers three tools, all of them read-only — none of them changes a file:

compare_treeCompares two folders or archives — also a folder against a ZIP or 7z, and archives inside archives — and lists what is different, only on one side, or not verified. It first names the folders with the most differences; with path the assistant then looks into one of them. A folder that exists on one side only is one line with the number of files in it. With content it decides by file content and uses the hash cache, so asking again is quick. Files that a cloud service keeps online only are not read and not downloaded: they count as unverified, and the answer says how many. Only with include_online_only are they read — and downloaded. Diffoniq recognizes such a file by the attributes of the Windows cloud files API, which OneDrive, Dropbox and other providers set. Google Drive in streaming mode sets none of them, so a drive labelled Google Drive counts as kept online only as a whole: nothing is read from it, the answer names the drive, and the assistant can ask you. A renamed drive is not recognized; its files are then downloaded when the content is compared. With exclude the assistant leaves out patterns such as backup files, and only with renamed lists the moved and renamed files. The gitignore option applies the .gitignore rules of both trees.
compare_fileCompares two text files and lists the lines that differ, with their line numbers on both sides. Case, spaces and trailing blanks can be ignored. Very long lines are shortened; a binary file shows its size, checksum and the first differing position instead of lines. A file kept online only is refused unless include_online_only is set.
sync_previewShows what a synchronization would do — which folders it would create and which files it would copy, rename or (in mirror mode) delete — without doing any of it. It is the dry-run plan of /sync. With content, a file kept online only is skipped instead of downloaded, unless include_online_only is set.

Every answer starts with a summary of the whole comparison and then lists the entries, kept short enough for the assistant to read in one go (about 20,000 characters). When more is there, the answer says how many entries are missing and how to see them: look into a folder, ask only for certain states (for example only what exists on one side), or page on with offset. When all differences lie in one chain of single folders, the overview goes straight down to its end. The tools are also available during the trial period.

Setting it up

Tell the assistant where DiffoniqC.exe is and to start it with /mcp. The examples use the installation folder of the installer; with the portable package, use the folder you extracted.

AssistantConfiguration
Claude Code In a terminal:
claude mcp add diffoniq -- "C:\Program Files\Diffoniq\DiffoniqC.exe" --mcp
Claude Desktop In claude_desktop_config.json (Settings > Developer > Edit Config):
{
  "mcpServers": {
    "diffoniq": {
      "command": "C:\\Program Files\\Diffoniq\\DiffoniqC.exe",
      "args": ["/mcp"]
    }
  }
}
Cursor The same mcpServers block in .cursor\mcp.json of the project, or in %USERPROFILE%\.cursor\mcp.json for all projects.
VS Code (Copilot) In .vscode\mcp.json of the project:
{
  "servers": {
    "diffoniq": {
      "type": "stdio",
      "command": "C:\\Program Files\\Diffoniq\\DiffoniqC.exe",
      "args": ["/mcp"]
    }
  }
}

Then ask in plain words, for example: “Compare D:\releases\v1 with D:\releases\v2 and tell me which files changed” or “What would a mirror of D:\work onto \\nas\backup\work delete?”. Most assistants ask before they use a tool for the first time.

Working with an AI assistant without MCP

An AI coding assistant that can run commands — in a terminal, an IDE or a CI pipeline — can also use the two commands above directly. The reliable pattern is always the same: have the assistant write a JSON report, read the file, then act on it. For example:

Run
  "C:\Program Files\Diffoniq\DiffoniqC.exe" /report "D:\releases\v1" "D:\releases\v2" --out r.json --format json --content -s
then read r.json and summarize what changed. Treat "unverified"
entries as unresolved, not as identical.

The assistant gets the summary counts to decide whether anything happened, the entries to name it, and the exit code to branch on — instead of guessing from screenshots or parsing text layouts. A file comparison works the same way and yields a lines array. The pages linked above spell out every key and exit code; hand them to the assistant when it needs the details.

The console launcher DiffoniqC.exe

Diffoniq.exe is a windowed program, so a shell does not wait for it, does not see its exit code and shows none of its output. Next to it sits DiffoniqC.exe, a small console program for exactly this case: it starts the Diffoniq.exe in its own folder with the same arguments, waits for it, prints the log lines of /report and /sync, and ends with Diffoniq's exit code. Use it wherever a script calls Diffoniq:

"C:\Program Files\Diffoniq\DiffoniqC.exe" /report "D:\Backup" "\\nas\Backup" --out r.json --format json --reverify
echo %errorlevel%
ShellCall
cmd, batch files "C:\Program Files\Diffoniq\DiffoniqC.exe" /report … — then %errorlevel%
PowerShell & "C:\Program Files\Diffoniq\DiffoniqC.exe" /report … — then $LASTEXITCODE
Git Bash / MSYS The shell rewrites /report into a path, so write it as //report: "/c/Program Files/Diffoniq/DiffoniqC.exe" //report … — then $?

Without the launcher

Calling Diffoniq.exe itself still works; the shell just has to be told to wait, or the exit code arrives as 0 before the report exists:

The output file is the safety net: the report and the log are written to a temporary name and renamed on completion — if the file named by --out or --log exists, it is complete. A consumer can never pick up a half-written report, and “wait until the file exists” is a correct pattern when the exit code is out of reach.

ShellRecipe
cmd, batch files start "" /wait "C:\Program Files\Diffoniq\Diffoniq.exe" /report … — then %errorlevel% is real.
PowerShell $p = Start-Process Diffoniq.exe -ArgumentList '/report','…' -Wait -PassThru; $p.ExitCode
Git Bash / MSYS Two traps at once: the shell rewrites /report into a path, and it does not wait. Write the switch as //report and force the wait through a pipe: Diffoniq.exe //report … | cat — the exit code is then ${PIPESTATUS[0]}.

The Task Scheduler and CI runners wait on their own — the nightly sync and nightly report examples show complete schtasks lines.