Reference

Docs

Install

Installs to ~/.local/bin. The script verifies the release checksum first and refuses outright if it does not match.

$curl -fsSL https://raw.githubusercontent.com/dejo1307/augur/main/install.sh | sh

$go install github.com/dejo1307/augur/cmd/augur@latest

Override the destination with AUGUR_INSTALL_DIR, pin a version with AUGUR_VERSION. Linux and macOS on amd64 and arm64, Windows on amd64; releases has them all with checksums. Go 1.25.13 or newer for the second one.

Commands

augur — see what is hidden in a file

usage:
  augur                    open the interactive viewer
  augur FILE               open FILE in the interactive viewer
  augur scan FILE [--json] report findings and exit
  augur scan DIR           scan a whole tree: git's file list, coverage reported
  augur clean FILE -o OUT  write a cleaned copy without prompting
  augur agents             scan the instruction files your coding agents read
  augur upgrade [--check]  replace this binary with the newest release

exit codes:
  0  nothing found
  1  findings present
  2  could not read or parse the file

augur scan

Flags come before paths.

--json	Write findings as JSON.
--min-severity	notice, concern or alarm. Default: notice for a file, concern for a directory.
--max-files	How many flagged files the report details. 0 for all. Default 20.
--max-size	Walking a directory, skip files larger than this. Default 10485760.
--no-git	Walk the filesystem instead of asking git for the file list.

augur clean

A single-file verb. Cleaning a tree at once would be a lot of irreversible decisions taken on files you have not looked at.

-o	Destination. Default: beside the original, with .clean before the extension.
--categories	Only remove these categories, comma-separated.
--force	Overwrite the destination if it exists.

augur agents

--list	List the files found and exit, without scanning.
--json	Write the result as JSON.
--min-severity	notice, concern or alarm. Default concern.
--project	Project root to search for repository-local instructions. Default "."

augur upgrade

Verifies the release checksum before writing, and swaps by rename, so an interrupted download leaves the working binary where it was.

--check	Report whether a newer release exists and exit. Exits 1 if one does.
--force	Re-install even when already on the latest release.

Severities

[alarm]	Only there on purpose. A decoded instruction, a payload past the end of a file, a direction override.
[concern]	Worth a look. A lookalike word, a location in a photo, the account that last saved a document.
[notice]	Usually an artefact of a copy and paste. Shown so you can decide.

A * means the finding is reported and never removed automatically. The reason is printed with it.

Viewer keys

↑ ↓ → ←	Move, open, up a level
~ /	Home, root
.	Toggle hidden files
space	Toggle one finding
a / n	Select all removable, select none
s	Save a clean copy
?	Show the blind spots
esc / q	Close the file, leave

What it looks for

Text	Zero-width characters, tag characters, variation selectors, private-use codepoints, bidi controls, mixed-script and whole-word homoglyphs, styled Latin alphabets, exotic spaces, BOMs, invalid UTF-8.
Terminal	ANSI escape sequences, with what each does spelled out, and carriage returns mid-line that repaint what was already printed.
Documents	Text styled to zero size or to the page colour, hidden attributes, HTML and markdown comments.
Distribution	A character repeated in a pattern across a document, which is a mark rather than an artefact.
Images	EXIF with GPS decoded to coordinates, XMP, IPTC, ICC, JPEG comments, PNG text chunks, bytes past the logical end. JPEG, PNG, WebP.
Provenance	C2PA Content Credentials read out — what made the file, what it says the source was, who signed it — and the hard binding recomputed, so a file changed after signing is reported as changed. In JPEG, PNG, WebP, SVG, PDF, zip-based documents, and in text.
PDF	Render-mode-3 text, white-filled text, the info dictionary and XMP, embedded JavaScript, attachments, incremental saves, bytes past the last %%EOF.
Office	Hidden runs, runs coloured to the page, tracked changes carrying deleted wording, comments, authorship, bytes past the end of the archive.

The text detectors run over the text inside an image and inside a document too, so a payload in a photo’s XMP packet is found by the code that reads a note. There is a page for each of these.

In CI

Every command exits 1 on findings and 2 when a file could not be read, so no wrapper script is needed to turn a scan into a gate.

- name: augur
  run: |
    curl -fsSL https://raw.githubusercontent.com/dejo1307/augur/main/install.sh | sh
    ~/.local/bin/augur agents
    ~/.local/bin/augur scan .

Something it missed?

Two reports are worth more than any feature request: a run it cannot decode, and a file it does not look at. False positives too. Open an issue.