Skip to main content

​
Basic usage

Xerg compares the current audit against the newest compatible prior snapshot stored in the local JSON snapshot store. For Hermes, local snapshots also compare mechanical metric values and report newly observed or resolved mechanical finding kinds. These deltas remain separate from monetary comparison, recommendations, and failure thresholds, and never cross the push wire.

​
What makes a snapshot compatible?

For local audits, Xerg matches on:
  • the same source roots for gateway logs and session files
  • the same normalized --since window
For SSH and Railway audits, Xerg uses a stable comparison key derived from the target plus the effective remote log and session paths. That means these usually compare cleanly:
  • rerunning the same local audit
  • rerunning the same SSH target with the same remote paths
  • rerunning the same Railway service with the same remote paths
These usually do not compare cleanly:
  • changing from default paths to different explicit paths
  • changing the --since window from 24h to 7d
  • switching to a different SSH host or Railway service

​
First run behavior

If you use --compare before a compatible baseline exists, Xerg still completes the audit. It adds this note to the summary:
Versions before 0.5.3 stored local snapshots in a native SQLite database. The current CLI uses a JSON snapshot store, so older xerg.db baselines do not participate in new comparisons. Run one current audit to create the new baseline.

​
Database requirements

--compare needs local snapshot history. This works:
This does not:
That combination fails because there is no local snapshot store to compare against.
  1. Run an initial audit.
  2. Make one workflow or model change.
  3. Re-run the same audit with the same effective inputs and --compare.
  4. Use the delta section to confirm whether total spend, structural waste, and high-confidence waste improved.