Skip to main content

​
Run a local audit

This is an agent-runtime audit. Costs can be observed in runtime records, estimated locally from usage and Xerg’s pricing catalog, or unpriced. They are not provider-invoice reconciliation, and opportunities are not counted as identified waste. By default, Xerg looks at:
  • OpenClaw: /tmp/openclaw/openclaw-*.log
  • OpenClaw: ~/.openclaw/agents/*/sessions/*.jsonl
  • Hermes: ~/.hermes/state.db (preferred, opened read-only)
  • Hermes observer: ~/.hermes/xerg/events/ when the optional plugin is enabled
  • Legacy Hermes logs/transcripts only when no database exists
Override either input explicitly:

​
OpenClaw source authority

OpenClaw can record the same underlying activity in both a gateway log and a session transcript. When both source kinds produce model calls in the requested audit window, Xerg uses session transcripts as the sole authority for totals, findings, signals, lineage, and local activity analysis. Gateway runs are excluded rather than joined heuristically, because the two formats do not provide a shared request or charge identifier that supports exact reconciliation. Transcript authority preserves agent identity, lineage, and per-tool evidence. The tradeoff is that gateway logs can contain observed retry and iteration structure: transcripts infer retries and provide no iteration evidence. A mixed-source report therefore warns that gateway-only activity may be omitted, activity and spend may be understated, and findings may differ from a fully reconciled view. The warning and pushed note contain counts and source kinds only, never local paths. Gateway-only and transcript-only audits are unchanged. To select one local source kind explicitly, provide only one of these commands:
Source authority is resolved after applying --since. A detected file with no included calls remains an extraction-coverage case, not an authority exclusion. Independent OpenClaw trace captures are unchanged and are never combined with logs or transcripts. Monetary thresholds and --require-detection-coverage evaluate only the selected transcript evidence. Passing either gate does not certify omitted gateway-only activity. For Hermes, --state-db cannot be combined with legacy --log-file or --sessions-dir. The observer directory is optional. Exactly reconciled observer evidence may split a state aggregate into request calls, but it never adds tokens, requests, or spend. Without an explicit runtime, --otlp-file remains an independent OpenClaw source and cannot be combined with transcripts, logs, another runtime, or remote inputs. The certified Hermes exception requires --runtime hermes and an auditable --state-db; see Hermes trace collection. Install the optional content-free observer with hermes plugins install xergai/hermes-observer --enable. It writes only to the local ledger and never exports telemetry to Xerg Cloud. Before starting any new Xerg-directed Hermes workload, run xerg doctor --runtime hermes --require-observer-live. A failed sequence-dependent test or observer-backed workload must stop. Existing aggregate-economics audits remain available, but incomplete reports lead with a coverage warning: aggregate economics remain available where priced, sequence-dependent analysis is unavailable for unassessed activity, zero identified findings are not conclusive, and repairing instrumentation covers only future activity. Hermes state.db compatibility targets schemas 25–26 (v0.20.1–v0.21.0); exact target-runtime acceptance remains pending. Older formats and schema 27+ remain best-effort, uncertified readers. Xerg subtracts main-task rows from main-session residuals, retains auxiliary rows once, collapses compression continuations, and keeps branches and delegated sessions separate. A session overlapping --since is included in full because aggregate usage cannot be apportioned across the boundary. If only one auto-detectable local runtime is present, Xerg auto-selects it. If OpenClaw and Hermes are both present, pass --runtime explicitly. Claude Code is never auto-selected — opt in with --runtime claude-code (next section).

​
Hermes profiles

Use --runtime hermes --hermes-profile <name> for an explicit profile, or --all-hermes-profiles for a local-only rollup. The database, observer directory, and health share one resolved home. Explicit database/profile, HERMES_HOME, sticky active profile, then platform default determine single-profile selection. Invalid selections fail. Named profiles exclude explicit database/log/session paths; all-profile mode excludes single-profile/path overrides and OTLP captures. Rollups cannot be uploaded through direct, cached, file, connect, activation, or wire dry-run paths. Local JSON preserves its scope marker. A new single source must be registered explicitly before upload; unresolved identity remains locally auditable. See Hermes analysis for identity recovery, known-zero accounting, and comparison-policy limits.

​
Audit QM

QM is an explicit database-backed source and is never auto-probed by init or bare audit. After an administrator completes secure setup, choose one mutually exclusive mode:
Direct and Fly audits create an ephemeral, owner-only qm-snapshot/v1, validate it, audit it, then remove it. xerg collect qm keeps the artifact. Strict direct mode uses a dedicated view-only reader; Fly uses a disclosed one-shot process boundary inside QM core. Both query only reviewed xerg_export/v1 views, HMAC raw identifiers before persistence, and never export prompts, responses, tool arguments, commands, or result text. QM pricing is deliberately fail-closed. Positive recorded cost is observed, an explicit deterministic model may be catalog-estimated, and openrouter/auto or negative placeholder cost is unpriced. Unpriced patterns can be reported, but their monetary impact is unavailable and they never add false $0 spend or savings. See QM analysis, pricing coverage, and limitations.

​
Audit Claude Code sessions locally

This reads Claude Code session transcripts from ~/.claude/projects/ — no hooks, no daemon, pure read. Subagent (sidechain) usage is included and grouped into the parent session.
  • costs are estimated from token usage and local model pricing, including cache read/write tokens (subscription plans do not bill per token)
  • progressive transcript records are reconstructed by (sessionId, messageId): usage buckets merge by component maximum and tool calls/results are united by tool-use ID
  • repeated tool-name chains are argument-aware neutral diagnostics; Claude Code does not expose a defensible state/progress fingerprint, so these chains cannot create monetary tool-loop findings
  • Opus 5 uses Xerg’s reviewed first-party global standard rate card; five-minute and one-hour cache writes are priced separately when the transcript preserves their TTL buckets
  • aggregate cache writes use the documented five-minute default and disclose possible one-hour underestimation; billing mode, inference geography, and partner-platform modifiers remain limited-estimate dimensions because transcripts do not expose them
  • models without a local pricing entry stay visible as unpriced instead of being silently zeroed
  • pass --claude-code-dir /path/to/projects if your transcripts live outside the default location

​
Audit a Cursor usage CSV locally

This local-only path analyzes Cursor’s exported usage rows instead of agent session logs. It is the best practical path for Cursor data today, with limits worth knowing up front:
  • usage CSV rows carry no retry, loop, or runtime structure and no true workflow traces
  • all three monetary findings are unavailable for this source because its rows cannot prove correlated retry attempts, exact no-progress tool calls, or cache-entry lifecycles; Cursor may still emit neutral signals such as cache-read-concentration and max-mode-concentration
  • Xerg estimates spend only for Cursor aliases that have an explicit local pricing map
  • unmapped aliases stay visible in token and model breakdowns as unpriced
If your framework can export richer per-event data (calls, retries, tool executions), use xerg ingest --file payload.json instead — the full findings engine runs on that path.

​
Limit the audit window

The CLI help and transport code support minute (m), hour (h), day (d), and week (w) suffixes.

​
Output modes

Compact terminal report (the default):
The compact report puts truth-critical warnings before totals, then shows headline economics, the prioritized action queue, comparison state, and the top findings, signals, workflows, models, and agents. It ends with omitted counts and an exact command for the full report. Detailed terminal report:
The detailed report is a strict information superset of compact output and retains every finding, signal, coverage section, local analysis block, trend, comparison, note, and conclusion. --verbose is separate: it adds operational progress on stderr and never changes report density. Use --details --verbose when you need both. JSON summary plus recommendations:
Markdown report:
--details is for human output only and cannot be combined with --json, --markdown, or --push --dry-run. Use --json for automation; human terminal and Markdown wording can evolve between releases.

​
Local snapshot storage

Unless you pass --no-db, Xerg stores each audit locally in a JSON snapshot store so later runs can use --compare and xerg push. Default snapshot path: Use a custom snapshot path:
Skip local persistence entirely:
If you skip persistence, --compare and later xerg explain lookup will not work. The current report still contains inline IDs and evidence.

​
What the report contains

  • total spend, observed spend, and estimated spend
  • daily spend and identified-waste series in UTC
  • structural waste and structural waste rate
  • seven neutral informational signals, separate from monetary totals
  • top workflows and top models by spend
  • evidence-strict monetary findings with affected and avoidable spend
  • eight-character item IDs with package-runner-safe xerg explain <prefix> --audit <audit-id>:<generated-at> hints for persisted findings, signals, and repeated tool chains; the persisted observation key keeps saved reports connected to their exact originating snapshot even when a later observation shares the same deterministic audit ID, and persisted reports append an absolute, shell-quoted --db path so custom stores resolve correctly from any working directory. --no-db reports replace the executable hint with an explicit lookup-unavailable message
  • local repeated tool-chain rows with argument diversity and non-additive associated spend labeled “not classified as waste”
  • an Action queue derived only from detector-owned avoidable spend
  • compare-aware validation guidance via xerg audit --compare --push
  • a separate local Mechanical efficiency section for Hermes observer metrics and conservative findings; it has no dollar impact and never affects recommendations or CI gates
  • separate local Tool activity and Workload economics sections for OpenClaw evidence; these neutral blocks never affect findings, recommendations, waste, or CI gates
  • a prominent source-authority warning when OpenClaw transcripts replace non-empty gateway evidence; all totals, detector coverage, findings, recommendations, and CI thresholds use only the authoritative transcript calls
  • current-window QM tool activity with unassociated call/result pairs; it stays local, has no monetary tool-loop attribution, and plainly reports the one-hour retention boundary
  • a count-only extraction note when some detected source files produced no included calls in the audit window (for example, files whose records all fall outside --since, or files with no usage-bearing records). The note reports counts only — file paths never appear in the report or on the push wire. Run xerg doctor --runtime <runtime> --verbose locally to see which files.
Use explain local evidence to drill into an item and findings and recommendations for the exact taxonomy and recommendation fields.