> ## Documentation Index
> Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit

> Run a local Xerg audit, choose output formats, control snapshot persistence, and understand the core report.

## Run a local audit

```bash theme={null}
npx @xerg/cli@latest 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:

```bash theme={null}
npx @xerg/cli@latest audit --runtime openclaw --log-file /path/to/openclaw.log
npx @xerg/cli@latest audit --runtime openclaw --sessions-dir /path/to/sessions
npx @xerg/cli@latest audit --otlp-file /path/to/openclaw.capture.jsonl
npx @xerg/cli@latest audit --runtime hermes --state-db ~/.hermes/state.db
npx @xerg/cli@latest audit --runtime hermes --hermes-events-dir ~/.hermes/xerg/events
npx @xerg/cli@latest audit --runtime hermes --state-db ~/.hermes/state.db --otlp-file /path/to/hermes.capture.jsonl
```

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](/docs/hermes-traces).

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

```bash theme={null}
npx @xerg/cli@latest audit --runtime claude-code
```

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

```bash theme={null}
npx @xerg/cli@latest audit --cursor-usage-csv ~/Downloads/usage-events-2026-04-08.csv
```

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`](/docs/ingest) instead — the full findings engine runs on that path.

## Limit the audit window

```bash theme={null}
npx @xerg/cli@latest audit --since 24h
npx @xerg/cli@latest audit --since 7d
npx @xerg/cli@latest audit --since 30m
```

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

## Output modes

Default terminal report:

```bash theme={null}
npx @xerg/cli@latest audit
```

JSON summary plus recommendations:

```bash theme={null}
npx @xerg/cli@latest audit --json
```

Markdown report:

```bash theme={null}
npx @xerg/cli@latest audit --markdown > xerg-audit.md
```

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:

| Platform | Default path                                                |
| -------- | ----------------------------------------------------------- |
| macOS    | `~/Library/Application Support/xerg/xerg-snapshots.json`    |
| Linux    | `${XDG_DATA_HOME:-~/.local/share}/xerg/xerg-snapshots.json` |
| Windows  | `%LOCALAPPDATA%\xerg\Data\xerg-snapshots.json`              |

Use a custom snapshot path:

```bash theme={null}
npx @xerg/cli@latest audit --db /path/to/xerg-snapshots.json
```

Skip local persistence entirely:

```bash theme={null}
npx @xerg/cli@latest audit --no-db
```

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](/docs/findings-and-recommendations) for the exact taxonomy and recommendation fields.