> ## 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.

# Xerg

> Start with local OpenClaw, Hermes, Claude Code, or Cursor audits, compare fixes, and add hosted follow-up only if you want it.

Xerg audits AI usage in dollars rather than tokens. It reads OpenClaw logs/transcripts or an independent sanitized trace capture, Hermes v0.17+ `state.db`, Claude Code transcripts, and Cursor usage CSV exports — or event payloads from any framework via `xerg ingest` — normalizes activity locally, and surfaces where spend is leaking.

> Local audits and `--compare` are free with no account. A Free hosted workspace (up to 2 members) saves the last 30 days of pushed audits with up to 100 stored snapshots per month. Ask Xerg, hosted MCP, Slack, and policies require a Pro or Enterprise workspace.

Working inside a coding agent? Install the Xerg skill with `npx skills add xergai/skills` and ask your agent to audit your spend. See [skill bundle](/docs/skill-bundle).

## What Xerg does

* Guides first-time local setup with `xerg init`.
* Audits local OpenClaw or Hermes activity from default paths or explicit files.
* Optionally collects runtime-specific OpenClaw or certified Hermes traces over loopback, sanitizing before local persistence and never pushing automatically.
* Audits local Claude Code session transcripts from `~/.claude/projects/`.
* Audits local Cursor usage CSV exports.
* Audits any other framework through a versioned JSON event payload with [`xerg ingest`](/docs/ingest).
* Compares the current audit with the newest compatible cached snapshot.
* Audits OpenClaw SSH and Railway targets from your local machine.
* Exports human-readable, Markdown, and machine-readable JSON output.
* Connects to a hosted workspace with `xerg connect`, pushes summaries when you choose, and can fail CI when confirmed waste is above a threshold.
* Tracks pushed audits, sources, trends, Optimizations, policies, and workspace API keys in the hosted dashboard.
* Exposes hosted audit history, recommendations, sources, policies, and guarded write actions through hosted MCP.

## What Xerg surfaces

Xerg splits findings into two buckets:

* Confirmed waste: `retry-waste`, `loop-waste`, and Cursor `cache-carryover` when its billed pattern clears the waste bar
* Savings opportunities: `context-outlier`, `idle-spend`, `candidate-downgrade`, and Cursor `max-mode-concentration`

The opportunity classes are directional. They are worth testing, but they are not proven waste.

## Default data sources

By default, Xerg looks for:

* OpenClaw gateway logs at `/tmp/openclaw/openclaw-*.log`
* OpenClaw session transcripts at `~/.openclaw/agents/*/sessions/*.jsonl`
* Hermes state database at `~/.hermes/state.db` (preferred and read-only)
* optional Hermes observer ledger at `~/.hermes/xerg/events/`; legacy logs/transcripts remain fallback inputs where present
* Claude Code session transcripts at `~/.claude/projects/`
* Cursor usage CSV exports through `--cursor-usage-csv`
* Event payloads from any framework through `xerg ingest --file`

If your data lives elsewhere, use `--state-db` for Hermes, `--log-file` / `--sessions-dir` for legacy sources, or `--claude-code-dir` for Claude Code.

For optional traces, see [OpenClaw trace collection](/docs/openclaw-traces) and [Hermes trace collection](/docs/hermes-traces). OpenClaw captures remain independent from transcript/log audits; Hermes captures only enrich an authoritative `state.db`.

## Start here

1. [Install Xerg](/docs/installation).
2. Start with [`xerg init`](/docs/init) or [run the quickstart](/docs/quickstart).
3. Keep the most useful commands nearby with the [CLI cheat sheet](/docs/cli-cheat-sheet).
4. If the data lives elsewhere, start with [doctor](/docs/doctor). Use [remote audits](/docs/remote-audits) for OpenClaw SSH and Railway targets.
5. Learn the core model in [waste taxonomy](/docs/waste-taxonomy), [metrics](/docs/metrics), and [how it works](/docs/how-it-works).
6. When you want hosted features, use [hosted dashboard](/docs/hosted-dashboard), [connect and push](/docs/auth-and-push), [hosted MCP](/docs/hosted-mcp), and [optimizations and policies](/docs/optimizations-and-policies).
7. When you want local automation, use [CI gates](/docs/ci-gates).

## Hosted workspace features

With a free Xerg workspace, you can:

* connect and push audit summaries into a hosted workspace with [authentication and push](/docs/auth-and-push)
* review the last 30 days of audit history, sources, trends, Optimizations, workspace API keys, members, and billing in the [hosted dashboard](/docs/hosted-dashboard)
* track recommendation-backed work in [optimizations and policies](/docs/optimizations-and-policies)

Pro and Enterprise workspaces additionally get full pushed audit history, unlimited members, Ask Xerg, [hosted MCP](/docs/hosted-mcp) for Cursor, Claude Code, Codex, or another MCP client, Slack notifications, and policy drafts.

## Current limits

* Cost per outcome requires outcome signals (declared with `xerg outcome`, carried on ingest events, or derived from terminal call states); runs without a signal stay untracked. See [metrics](/docs/metrics) for details.
* Opportunity findings are recommendations to test, not proven waste.
* Xerg stores economic metadata and audit summaries locally. It does not store prompt or response content.