Quickstart

Get augur running on your project in under a minute. augur needs no API key, no LLM, and no configuration to start, just Swift 6 and git on PATH. It is Runs on macOS and Linux.

1. Install

augur is a Swift package. Build the release binary and drop it on your PATH:

swift build -c release
install -m 0755 .build/release/augur /usr/local/bin/augur
# or, with fledge:
fledge run install

Verify it:

augur check --help

Try it instantly (no setup)

Every script in examples/ builds the binary and runs it against a throwaway /tmp repo, so you get a real verdict in seconds:

bash examples/01-check.sh

2. Get a verdict

augur is range-first. With no scope flag it assesses the working tree (staged + unstaged) against HEAD:

augur check                         # working-tree changes
augur check --range main..HEAD      # an explicit git range
augur check --staged                # staged changes only (pre-commit)
augur check -v                      # show every contributing signal

A typical assessment:

$ augur check --range main..HEAD

augur · main..HEAD

  verdict     [!] REVIEW
  risk        [##########          ]  50/100
  confidence  50/100
  calibration history-backed (156 incidents / 500 commits)

  files (1), riskiest first:
    !    50  src/auth/token.swift
          · sensitivity: matches sensitive category 'auth'

  → an agent should request human review before merging

On a real terminal this is colored: the verdict is tinted by level (green proceed · amber review · red block), the risk meter renders as a █░ gauge tinted by the same scale, file paths are cyan, and secondary detail is dimmed. Color is TTY-aware: augur emits plain text (exactly as shown above) whenever stdout is not a terminal, so piped, redirected, --json, and --sarif output stays clean and scriptable. Control it with --color auto|always|never (default auto), and augur honors the NO_COLOR convention.

check always exits 0: it reports, it does not gate.

3. Gate in CI or an agent loop

augur gate exits non-zero when the verdict meets or exceeds a threshold, so a pipeline fails or an agent escalates instead of merging blind:

augur gate --threshold review        # exit 1 if verdict >= review
augur gate --range origin/main..HEAD --threshold block

Exit code	Meaning
`0`	Verdict below the threshold (or no changes).
`1`	Verdict met or exceeded the threshold.
`2`	Usage / validation error.

For agents

verdict=$(augur check --range main..HEAD --json | jq -r .verdict)
[ "$verdict" = "proceed" ] || echo "escalating to a human"

4. Sharpen it (optional)

Everything past here is additive; augur works without any of it.

Want	Do this	Guide
Per-line test-gap precision	`augur check --coverage lcov.info`	Coverage
Tune thresholds / weights / rules	Drop an `.augur.toml` at the repo root	Configuration
Faster repeat runs	`augur calibrate` then `augur check --cached`	CLI reference
Inline PR annotations	`augur check --sarif-out augur.sarif`	CI integration
Durable trust records	`augur check --json \| attest sign --from-augur -`	CI integration

What’s next?

CLI reference: every command, flag, exit code, and the JSON shape.
Signals: what each of the eight signals catches and how to tune it.
Architecture: how the deterministic, zero-dependency engine works.