Skip to main content

​
Local-first design

Xerg runs its audit analysis locally. Every supported source goes through the same adapter registry: an adapter detects source files, normalizes activity into runs and calls when the source supports it, and declares what it can structurally observe. The audit engine then computes spend, generates findings gated on those declared capabilities, and renders the report on your machine. Supported sources:
  • OpenClaw gateway logs and session transcripts, plus optional independent sanitized trace captures
  • Hermes v0.17+ state.db, plus optional content-free observer telemetry and certified local trace enrichment; legacy files are fallback inputs
  • Claude Code session transcripts (~/.claude/projects/ or --claude-code-dir)
  • Cursor usage CSV exports (--cursor-usage-csv)
  • Event payloads from any framework (xerg ingest --file)

​
Local audit flow

At a high level, Xerg does this:
  1. Resolve the source adapter and detect source files from defaults or explicit paths.
  2. Normalize raw data into runs and model calls.
  3. Use observed cost where available and estimate missing cost from the pricing catalog when possible.
  4. Build findings and recommendation candidates, applying only the finding rules the source’s declared capabilities support (a CSV export without runtime structure never produces retry or loop findings, for example).
  5. Render the chosen output format.
  6. Persist a local snapshot unless --no-db was used.
Hermes database rows can aggregate multiple API requests. Xerg records their requestCount for call-count rollups without multiplying aggregate tokens or cost, and aggregate rows are excluded from sequence-dependent monetary detectors. Complete observer request groups may split an aggregate only when request count and input/output/cache buckets match exactly; cost is allocated without changing the authoritative total. Optional observer events and certified Hermes traces add local fidelity but never add economics. OpenClaw trace captures are independent audits. Xerg never combines their economic calls with transcript or log calls. The loopback collector decodes each OTLP/HTTP protobuf request in memory, hashes identifiers, persists only allowlisted typed fields, and rejects content-bearing attributes. See OpenClaw trace collection.

​
Compare flow

When you run --compare, Xerg computes a comparison key for the current audit and looks up the newest compatible local snapshot. Compatibility is based on the effective source roots and normalized time window, not just “latest run wins.”

​
Remote audit flow

Remote audits still analyze locally. Xerg first pulls telemetry files from the target, then runs the same local audit engine on the pulled files. Supported transports:
  • SSH for OpenClaw
  • Railway for OpenClaw
  • multi-source config via --remote-config for OpenClaw sources
For SSH, Xerg prefers rsync and falls back to tar over SSH if needed. For Railway, it uses the railway CLI and handles PTY-safe transfer internally.

​
Push flow

When you use --push, the CLI maps the local summary into a versioned wire payload and sends it to the Xerg API.
This wire payload is intentionally narrower than the local summary:
  • it includes daily spend and waste rollups for hosted dashboards
  • it omits local file paths
  • it omits local snapshot store path details
  • it omits internal finding details
  • it omits the complete local mechanicalEfficiency block, observer identifiers, fingerprints, and orchestration events
  • it omits analysisCoverage, toolActivity, workloadEconomics, request evidence, hashed trace/tool identifiers, lineage, prompt sizes, and per-call byte evidence for both runtimes
  • it includes ranked recommendations without raw prompt or response content

​
Hosted dashboard flow

After a push succeeds, the hosted API stores the audit summary for the authenticated workspace. The dashboard uses that hosted data for audit history, source views, daily trends, compare views, Optimizations, policies, and workspace API key setup.
The hosted dashboard never reads local files directly. It only sees the pushed wire payload.

​
Privacy boundaries

Xerg is designed to work on economic metadata rather than prompt content. The docs and codebase currently support these claims:
  • Xerg stores local economic metadata and audit summaries
  • the push payload excludes local file paths and internal debug-style fields
  • prompt and response content are not part of the push wire schema
  • hosted sync only happens through explicit connect, audit --push, or push commands
For the exact local summary and wire payload shapes, see json output.