Compare Files Viewer is a native Mac app for reviewing file-comparison results produced by a Shortcut or another tool.
A folder full of “final”, “final-2”, and “final-revised” files creates two questions: how are they related, and which version should you open first? A readable comparison report can help, especially when its conclusion is accompanied by paths, dates, hashes, or text differences.
Compare Files Viewer provides that presentation layer. It does not compare files itself. Another producer must inspect the files and send a result payload.
Build the viewer
The project requires macOS 14 or later and Xcode Command Line Tools. There is currently no packaged GitHub Release.
Download the source and build from its root:
|
|
The release executable is available under .build/release/. To inspect the repository’s example report:
|
|
Example paths may not exist on your Mac. The sample demonstrates the report format rather than comparing your own documents.
On your first look, start with the proposed main version and version order, then open Details to see the evidence behind that suggestion. This lets you understand the window before deciding whether to connect your own comparison workflow. The sample does not read any “final” files in your folder.
What a report can show
The payload contains files, analysis, and optional local_evidence. Depending on the producer, the viewer can display:
- The overall relationship and confidence.
- A recommended main version and proposed version order.
- Finder icons, paths, file sizes, and modification times.
- Local SHA-256 metadata, text differences, or image-comparison evidence.
A Details sheet and Reveal in Finder actions make it easier to investigate the reasoning. English and Simplified Chinese interfaces are supported.
The usefulness of those fields depends on the upstream comparison. A missing hash is not proof of difference; an AI-generated grouping is not the same as byte-for-byte equality.
Imagine two reports that differ by one number. The newer modification date tells you which one to open first, but the actual difference and the files’ origins decide which to keep. If the producer supplied only dates, the viewer cannot invent a text diff or hash as missing evidence.
Connect your own producer
The app accepts a JSON file through --file, JSON text through --json, or a payload on stdin. Use ExamplePayload.json as the schema reference when writing a Shortcut or script.
The repository includes the viewer source and ExamplePayload.json, but no importable Compare Files.shortcut file. To compare your own files, you first need a Shortcut or script that produces this JSON report. Opening the viewer alone will not run a comparison.
This is therefore most useful if you already have a comparison workflow and want a clearer native result window.
Read the sample as a worked example
The repository groups report.pdf, report-v2.pdf, and report-final.pdf. It proposes a main version and an order, with explanations such as an added chapter and changed page count. Start by checking whether the files belong to the same subject, then examine what changed. The word “final” is a useful label, not evidence on its own.
Open Details and compare paths, sizes, and modification times. A “final” copy in Downloads may be an older attachment resent by a colleague. A cloud-folder copy may contain comments that never reached the main draft. Paths explain where material came from; differences explain what it contains. Both matter when deciding what to keep.
The example uses demonstration paths and abbreviated hash values. It helps you understand the interface; it cannot establish anything about files on your Mac. Replacing a sample filename only edits the report. It does not ask the viewer to analyze the newly named document.
Understand the different kinds of evidence
A complete file hash can establish byte equality. A text hash concerns extracted text, which is a narrower question. Two PDFs can contain the same text while differing in layout, annotations, or embedded images. Decide whether your task concerns the words or the whole document before treating a text match as sufficient.
Text differences may also be excerpts. The sample records added and removed line counts, a few example lines, and a flag showing that samples were truncated. Use those excerpts to locate changes, then inspect the original context. A changed number means little until you know whether it is a price, date, reference, or page number.
The main-version recommendation helps set a reading order. It need not collapse every useful file into one survivor. An editable source, an annotated review copy, and a PDF prepared for sending can serve different purposes. Keeping those roles clear can be more useful than naming one universal “best” version.
Connect a producer through a saved report first
For your first integration, let the producer save a JSON file and open it with --file. This separates the analysis from display: if something looks wrong, you can inspect the input without debugging both stages at once. Move to a stdin pipeline only after the saved-file workflow works reliably.
Follow ExamplePayload.json: files describes the items, analysis holds relationships and recommendations, and local_evidence carries evidence actually collected. Leave unavailable evidence absent rather than inventing plausible explanations. Use real source paths so Reveal in Finder can take you to the documents.
If the viewer reports a loading or parsing error, check that the report file exists, contains valid JSON, and follows the expected structure. Distinguish the path supplied to --file from the document paths inside that file. One opens the report; the others locate the compared material. Both layers must be correct for the handoff to be useful.
Decide what “main version” really means
Modification time alone does not establish the best version. Copying and exporting can change dates, while two documents can differ in small but important edits. Treat the recommendation as a place to start reviewing.
Open the proposed main file, verify the differences that matter, and retain originals until you have confirmed the relationship. The viewer does not merge documents or provide a reason to delete alternatives automatically.
The app itself makes no network requests and does not upload selected files. Privacy and AI policies belong to the producer that generated the payload.
For first understanding an unfamiliar format, see What File Is This. For consistent names after the review, Auto Filename Helper is a separate workflow. The README and example payload are the starting point for integration.