Skip to main content

​
Run a local audit

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:
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. Hermes state.db support covers schema 16 (Hermes v0.17), schema 20 model-usage rows, and schema 22 task-dimension rows (Hermes v0.19), plus future compatible schemas. Xerg mirrors Hermes’s positive-residual usage reconciliation, 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).

​
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)
  • 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
  • agent-runtime findings like retry waste and loop waste are therefore intentionally disabled for this source; Cursor audits surface Cursor-specific findings (such as cache-carryover and max-mode-concentration) only
  • 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

Default terminal report:
JSON summary plus recommendations:
Markdown report:
You can use either --json or --markdown, but not both in the same command.

​
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 will not work.

​
What the report contains

  • total spend, observed spend, and estimated spend
  • daily spend and confirmed waste series in UTC
  • structural waste and structural waste rate
  • savings opportunities
  • top workflows and top models by spend
  • high-confidence waste findings
  • an Action queue with top fix_now, test_next, and watch items
  • 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 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 findings and recommendations for the exact taxonomy and recommendation fields.