Xerg

Use xerg if it is already installed. If not, use npx @xerg/cli with the same arguments.

Xerg audits OpenClaw and Hermes workflows in dollars, not tokens. It reads gateway logs and session transcripts, surfaces confirmed waste plus savings opportunities, and helps you measure fixes with --compare.

Local audits need no account. Hosted sync and hosted MCP are optional paid workspace features. No data leaves your machine unless you explicitly push results to Xerg Cloud.

Quick Start

CODEBLOCK0

Use direct commands when you need explicit control, non-interactive behavior, JSON output, or CI gates:

CODEBLOCK1

Inputs

Xerg needs one of these source inputs:

• - Local OpenClaw data at the default paths:

• - Local Hermes data at the default paths:

• - Explicit paths via --log-file and/or INLINECODE9
• An SSH target via INLINECODE10
• A Railway target via INLINECODE11
• A multi-source config via INLINECODE12

Additional requirements:

• - --compare needs at least one previously stored compatible local snapshot
• Pushing needs auth via XERG_API_KEY, ~/.xerg/config.json, or browser credentials from INLINECODE16
• SSH audits require ssh and rsync on your local PATH and are OpenClaw-only in this phase
• Railway audits require the railway CLI on your local PATH and are OpenClaw-only in this phase

Default Flow

1. 1. Start with the default first-run path when you want the fastest local result:

CODEBLOCK2

• - init detects local OpenClaw or Hermes data
• it runs a first audit with local snapshot persistence enabled
• it offers optional hosted follow-up after the audit completes
• if no local data is found, it prints explicit local-path commands plus remote OpenClaw-only guidance

1. 2. Detect sources directly when paths or connectivity are uncertain:

CODEBLOCK3

• - xerg doctor --verbose shows progress on stderr while Xerg checks local paths or remote transports
• If local defaults are empty, prefer xerg doctor --remote ... or xerg doctor --railway instead of guessing paths

1. 3. Run a baseline audit explicitly when you want direct control:

CODEBLOCK4

1. 4. Choose the right output mode for the task:

CODEBLOCK5

• - Plain xerg audit is best for a human-readable summary
• INLINECODE27 is best for automation and agents
• INLINECODE28 is best for a shareable report

1. 5. After a workflow or model change, measure the delta:

CODEBLOCK6

1. 6. Export, push, or hosted-setup only when needed:

CODEBLOCK7

• - connect is the guided hosted path: it reuses existing auth, prompts before browser login when needed, and offers to push the latest audit
• INLINECODE30 prints or writes hosted MCP config for Cursor, Claude Code, or another client
• local audits and compare remain available if you skip hosted setup

Source Selection

Local defaults:

CODEBLOCK8

If both OpenClaw and Hermes are present locally, pass --runtime openclaw or --runtime hermes explicitly.

Explicit local paths:

CODEBLOCK9

SSH remote:

CODEBLOCK10

Railway:

CODEBLOCK11

Multiple remote sources:

CODEBLOCK12

Remote config files use this shape:

CODEBLOCK13

CI And Automation

For CI gates, prefer a single command so the audit can still be pushed before threshold failure:

CODEBLOCK14

Common variants:

CODEBLOCK15

Documented exit codes:

• - 0 success
• INLINECODE34 runtime error
• INLINECODE35 no supported local runtime data found
• INLINECODE36 threshold exceeded

Automation can branch on those codes instead of scraping terminal output.

Recommendations

When using --json, expect a recommendations array alongside the audit summary. Recommendation items include:

• - id, findingId, kind, title, INLINECODE43
• INLINECODE44, confidence, INLINECODE46
• optional INLINECODE47

Current recommendation kinds fall into two buckets:

• - Confirmed waste: retry-waste, INLINECODE49
• Savings opportunities or directional findings: context-outlier, idle-spend, INLINECODE52

Prefer reversible or high-confidence fixes first. Treat model downgrades and context reductions as A/B-test candidates, not guaranteed savings.

Checks

Before finalizing work that used Xerg:

• - Say whether the audit was local, SSH, Railway, or multi-source
• Say whether the output was plain terminal text, JSON, or Markdown
• If --compare was used, confirm that it compared against a compatible stored snapshot
• If no data was found, run xerg doctor or use explicit source flags rather than guessing
• Say whether results were pushed to the Xerg API
• Distinguish confirmed waste (retry-waste, loop-waste) from directional opportunities (context-outlier, idle-spend, candidate-downgrade)

Notes

• - --compare and --no-db cannot be used together
• Xerg is local-first: it stores economic metadata and audit snapshots locally, not prompt or response content
• INLINECODE62 is recommended for CI and non-interactive automation
• If browser auth is needed without the hosted setup flow, use xerg login; remove stored credentials with INLINECODE64
• Pilot: xerg.ai/pilot
• Support: INLINECODE65