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 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, resolving any source-authority rule before summary construction.
  3. Use observed cost where available and estimate missing cost from the pricing catalog when possible.
  4. Build evidence-strict findings and neutral signals, applying only the rules the source’s declared capabilities support (a CSV export without runtime structure never produces retry or loop findings, for example).
  5. Analyze ordered tool executions for repeated local chains and argument diversity without turning name repetition into waste.
  6. Build digest-only local explanation packets and render the chosen output format.
  7. 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 provider/model/task groups may split an aggregate only when request count and input/output/cache buckets match exactly; cost is allocated without changing the authoritative total. Auxiliary tasks not exposed through Hermes’s public request hooks remain separately attributed aggregates, so their economics stay included without invalidating exact evidence for observable agent requests. Optional observer events and certified Hermes traces add local fidelity but never add economics. OpenClaw gateway logs and session transcripts are alternate representations, not additive sources. If both kinds produce calls inside the requested window, the adapter uses transcript runs only and records the gateway files as excluded by source authority. Transcripts preserve agent identity, lineage, and per-tool evidence; they infer retries and provide no iteration evidence, while gateway logs can preserve both structures directly. Because there is no supported exact join key, Xerg does not attempt record-level reconciliation. Mixed reports disclose that activity and spend may be understated and findings may differ from a fully reconciled view. 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 authoritative source roots and normalized time window, not just “latest run wins.” A corrected local mixed OpenClaw audit uses transcript identity. When mixed authority is engaged remotely, SSH and Railway keys also include a source-authority version so pre-0.28 mixed baselines cannot appear as savings after gateway exclusion; single-kind keys are unchanged.

​
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 omits toolChains, localDiagnostics, local pricing limitation details, and per-TTL cache-write buckets; only bounded registered signal metrics such as toolInputDistinctRatio may cross
  • 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 activate, audit --push, or push commands
For the exact local summary and wire payload shapes, see json output.