# Xerg - Complete Reference for LLMs

Xerg audits AI agent runtime spend in dollars. Runtime audits separate three evidence-strict monetary findings from seven neutral signals and report eligibility for every detector; aggregate-only data is not presented as a conclusive zero. Costs may be observed, locally estimated, or unpriced; they are not authoritative provider invoices. Local CLI audits are free and local-first. A Free hosted workspace (up to 2 members) saves the last 30 days of pushed audit history, with source trends, coverage-compatible compare, Optimizations, and workspace API keys, up to 100 stored audit snapshots per UTC month. Pro workspaces add full pushed audit history, unlimited members, Ask Xerg, hosted MCP, Slack, and policy drafts.

## AI Agent Spend Scenario Modeler

The public [AI Agent Spend Scenario Modeler](https://xerg.ai/agent-spend-modeler) applies adjustable illustrative rates for exactly the three active finding kinds: retry waste at 5%, tool-loop waste at 2%, and cache churn at 0.5%. The 7.5% default is not a benchmark, audit finding, maximum, or savings promise. Platform, operating-mode, and spend-attribution selections are descriptive context and do not alter the rates in 0.20.0. The page keeps calculator inputs in browser memory and explains that a Xerg runtime audit replaces the assumptions with measured avoidable spend and detector coverage.

## Installation

```bash
npm install -g @xerg/cli
# or run directly
npx @xerg/cli@latest init
```

The CLI package is publicly installable from npm, but it is not open source. The public machine-readable contract package is `@xerg/schemas`, which is MIT-licensed.

## Core Commands

### First run and local audits
```bash
xerg init                         # Detect local runtimes, run a first audit, offer optional hosted follow-up
xerg doctor                       # Verify local or remote readiness
xerg audit                        # Audit auto-detected local OpenClaw or Hermes data
xerg audit --runtime hermes --state-db ~/.hermes/state.db  # Read-only Hermes v0.17+ database audit
xerg audit --runtime claude-code  # Audit local Claude Code session transcripts
xerg collect openclaw             # Collect sanitized OpenClaw traces on loopback until Ctrl-C
xerg audit --otlp-file ./openclaw.capture.jsonl  # Audit an independent sanitized trace capture
xerg collect hermes --state-db ~/.hermes/state.db  # Collect certified sanitized Hermes trace enrichment
xerg audit --runtime hermes --state-db ~/.hermes/state.db --otlp-file ./hermes.capture.jsonl
xerg connect qm --fly-app <app>  # Verify a contained QM Fly core exporter
xerg doctor --runtime qm         # Verify QM contract, indexes, role, key continuity
xerg collect qm --since 7d       # Persist one bounded owner-only QM snapshot and audit it
xerg audit --runtime qm --fly-app <app> --since 7d  # Ephemeral one-shot Fly audit
xerg audit --runtime qm --qm-snapshot ./qm.jsonl    # Audit an existing strict snapshot
xerg audit --since 24h            # Last 24 hours only
xerg audit --json                 # Machine-readable JSON output
xerg audit --compare              # Compare against previous audit
xerg audit --cursor-usage-csv ./usage-events.csv  # Audit a Cursor usage CSV export
xerg ingest --file payload.json   # Audit a Xerg event payload from any framework
```

### Remote audit
```bash
xerg audit --remote user@host     # Audit a remote VPS over SSH
xerg audit --remote-config ~/.xerg/remotes.json  # Multi-source audit
```

SSH, Railway, and remote-config transports are OpenClaw-only. QM currently supports bounded one-shot collection through a host-independent `qm-snapshot/v1` adapter plus strict direct-reader and certified Fly-contained collection. Fly Managed Postgres uses a disclosed process boundary inside QM core rather than its broad managed reader, so database least privilege is false in that mode. QM is never auto-detected. Raw IDs are HMACed before persistence; prompts, responses, tool arguments, commands, and result text are never exported. A QM Slack agent can audit an authorized pre-created snapshot but cannot initiate live collection. Continuous follow capture, durable tool-history capture beyond QM's retention window, and live Slack-triggered collection are not currently supported. Current Fly Sprites require an explicitly approved, version-verified CLI bootstrap inside the private persistent Sprite because they do not apply the configured sandbox OCI image.

QM cost is observed only when positive. An explicit deterministic model may be catalog-estimated. Negative placeholders and unresolved `openrouter/auto` remain unpriced and make monetary gates exit 5 instead of inventing zero spend. Current tool activity is limited to QM's one-hour retention and is not associated with model spend.

### Push to dashboard
```bash
xerg audit --push                 # Push results to xerg.ai/dashboard (free workspace account)
xerg audit --push --dry-run       # Inspect payload without sending
xerg push                         # Push the newest cached local snapshot
```

### CI gating
```bash
xerg audit --fail-above-waste-rate 0.30   # Exit 3 if waste > 30%
xerg audit --fail-above-waste-usd 50      # Exit 3 if waste > $50
```

## Exit Codes

- 0: Success
- 1: Runtime error
- 2: No data found
- 3: Threshold exceeded (CI gating)

## API Endpoints

Base URL: `https://api.xerg.ai`

### POST /v1/audits
Push an audit payload. Requires `Authorization: Bearer <api_key>`.

Request body: `AuditPushPayload` (see Wire Schema below).

### GET /v1/audits
List audits for your workspace. Query params: `?since=24h`, `?source=production`, `?limit=50`.

### GET /v1/audits/:id
Single audit detail.

### GET /v1/trends
Time-series metrics. Query params: `?since=30d`, `?source=production`, `?metric=wasteRate`.
Supported metrics: totalSpend, wasteSpend, wasteRate, runCount, callCount.

Additional hosted API route groups support sources, action center items, optimizations, policies, legacy audit-recommendation compatibility, raw ingestions, and workspace API keys. These are used by the dashboard and hosted MCP.

## Hosted Dashboard

Dashboard URL: `https://xerg.ai/dashboard`

The hosted dashboard includes:

- Overview and onboarding
- pushed audit history and audit detail pages
- sources and source detail trends
- compare views for pushed audits
- Optimizations backlog
- Policies (Alpha)
- workspace settings, members and billing, API keys, and hosted MCP snippets

Local CLI audits do not require an account. Dashboard pages require a signed-in workspace; Free workspaces see the last 30 days of pushed audits, while Ask Xerg, hosted MCP, Slack, and Policies require Pro or Enterprise.

## Hosted MCP

MCP endpoint: `https://mcp.xerg.ai/mcp` (Pro and Enterprise workspaces)

Use a workspace API key as a Bearer token:

```text
Authorization: Bearer <XERG_API_KEY>
```

Read tools:

- `xerg_latest_audit`
- `xerg_history`
- `xerg_trends`
- `xerg_sources`
- `xerg_recommendations`
- `xerg_list_policies`

Write tools:

- `xerg_push_audit`
- `xerg_ingest_raw_openclaw`
- `xerg_upsert_policy`
- `xerg_delete_policy`
- `xerg_create_policy_from_recommendation`

Write tools use preview and commit semantics for guarded changes.

## Wire Schema (AuditPushPayload)

The push payload is a versioned, privacy-safe wire schema. Types are published as the MIT-licensed `@xerg/schemas` contract package on npm.

```typescript
type AuditPushPayload =
  | {
      version: 6;
      summary: {
        auditKind: "runtime";
        auditId: string;
        economicAuditId: string;
        generatedAt: string;
        comparisonKey: string;
        runCount: number;
        callCount: number;
        totalSpendUsd: number;
        wasteSpendUsd: number;
        structuralWasteRate: number;
        findings: WireFinding[];
        signals: WireSignal[];
        spendByWorkflow: SpendBreakdown[];
        spendByModel: SpendBreakdown[];
        spendByDay: DailySpendBreakdown[];
        wasteByDay: DailyWasteBreakdown[];
        recommendations: XergRecommendation[];
        comparison?: WireComparison | null;
        wasteBySignalSource?: WireWasteBySignalSource;
        pricingCoverage?: WirePricingCoverage;
        tokenEconomics?: WireTokenEconomics;
        outcomes?: WireOutcomeRollup;
        detectionCoverage: RuntimeDetectionCoverage;
        sourceStability: SourceStability;
      };
      meta: PushMeta;
    };

interface WireFinding {
  id: string;
  classification: "waste";
  confidence: "high" | "medium" | "low";
  kind: "retry-waste" | "tool-loop" | "cache-thrash";
  title: string;
  summary: string;
  scope: string;
  scopeId: string;
  affectedSpendUsd: number;
  avoidableSpendUsd: number;
  evidenceBasis: "observed" | "declared";
  impactBasis: "observed-charge" | "catalog-estimate" | "mixed";
  detectorVersion: string;
}

interface WireSignal {
  id: string;
  kind: "deep-loop-activity" | "context-outlier" | "context-growth" | "fixed-cadence-activity" | "premium-model-routine-label" | "cache-read-concentration" | "max-mode-concentration";
  title: string;
  summary: string;
  metrics: Record<string, number | string | boolean | null>;
  associatedSpendUsd?: number;
  associatedSpendBasis?: "observed-charge" | "catalog-estimate" | "mixed";
}
```

Version 6 separates evidence-strict monetary findings from neutral signals, gives findings affected and avoidable amounts, and reports coverage for all current detectors. Version 5 remains readable unchanged with a legacy-method marker and upgrade advisory, but new v5 pushes cannot create or recur current optimization records. Use the exported `AUDIT_PUSH_PAYLOAD_VERSION` constant from `@xerg/schemas` instead of hard-coding a version in consumers.

## Authentication

- Dashboard: Clerk session via web sign-in
- CLI: `xerg activate` opens short-lived browser approval, shows the exact organization/plan/environment, then stores an environment-bound workspace credential under `~/.config/xerg/credentials.json`; `--organization-id org_...` requires one exact workspace and `--connect-only` exits without auditing or pushing
- Advanced recovery: `xerg login --replace` uses a masked paste prompt
- CI: `XERG_API_KEY` from the CI provider's secret manager; legacy `~/.xerg/config.json` remains supported
- Workspace API keys are created or rotated in the hosted dashboard

## Pricing

- Free ($0/month): Unlimited local runtime audits with no account, plus a hosted workspace for up to 2 members with 30 days of pushed audit history, up to 100 stored audit snapshots per month, and workspace API keys
- Pro ($29 per seat/month): Everything in Free plus full pushed audit history, unlimited pushes and members, Ask Xerg, hosted MCP, Slack, and optimization policy drafts
- Enterprise: Everything in Pro plus custom pricing for SSO/SAML, self-hosted deployment, custom retention, contracts, guided onboarding, and SLAs

## Links

- Website: https://xerg.ai
- For Agents: https://xerg.ai/agents
- Dashboard: https://xerg.ai/dashboard
- MCP: https://xerg.ai/mcp
- SKILL.md: https://xerg.ai/skill.md
- Docs: https://xerg.ai/docs
- Status: https://status.xerg.ai
- npm CLI: https://www.npmjs.com/package/@xerg/cli
- npm schemas: https://www.npmjs.com/package/@xerg/schemas
- Pricing: https://xerg.ai/pricing