xerg

Find wasted AI spend in OpenClaw, Hermes, and Cursor.

Xerg audits AI spend in dollars, surfaces provenance-aware waste findings, compares fixes, and optionally connects hosted follow-up after the first local result.

Xerg runs locally by default. Local audits and --compare are free. No account is required for local value, and no data leaves your machine unless you explicitly push results to Xerg Cloud.

The npx @xerg/cli path fetches and executes the published npm package before running Xerg. If you want to avoid a runtime fetch, install once with npm install -g @xerg/cli.

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

Fastest first run

npx @xerg/cli init

init is the default first-run path. It:

• detects local OpenClaw or Hermes data
• runs a first audit and stores the local snapshot
• prints the provenance-aware terminal summary
• offers optional hosted follow-up with connect and mcp-setup

Prefer a global install?

npm install -g @xerg/cli
xerg init

Direct commands for explicit control

If you already know what you want, skip init and use the direct flows:

npx @xerg/cli doctor
npx @xerg/cli audit
npx @xerg/cli audit --compare
npx @xerg/cli audit --cursor-usage-csv ./cursor-usage.csv
npx @xerg/cli audit --json
npx @xerg/cli audit --markdown

Use these when you need non-interactive behavior, CI gates, JSON/Markdown output, or explicit runtime and path flags.

Bundled skill

The published @xerg/cli package includes the portable Xerg skill bundle inside the installed package at:

skills/xerg/SKILL.md

For a local project install, that usually resolves to:

node_modules/@xerg/cli/skills/xerg/SKILL.md

For a global install, the same file lives inside the global npm package directory instead. The same canonical skill is also mirrored at xerg.ai/skill.md. Use it if your agent platform imports skills from disk; installing the npm package does not automatically register the skill with every agent product.

The bundled skill frontmatter declares the CLI/package surface plus optional Xerg Cloud and remote audit requirements so registries can distinguish the default local audit workflow from opt-in hosted sync and remote audit workflows.

Supported runtime

@xerg/cli supports Node 22 and 24.

If you have access to the private Xerg source repository, .nvmrc pins the default toolchain to Node 24.14.0.

Sample output

Total spend: $148.00
Observed spend: $105.00
Estimated spend: $43.00

Waste taxonomy
- Retry waste: $12.40
- Context bloat: $18.90
- Loop waste: $7.10
- Downgrade candidates: $4.80
- Idle waste: $3.37

Action queue
Fix now
- Reduce retry waste in workspace: $12.40 (high)
Test next
- Evaluate a cheaper model for heartbeat_monitor: $4.80 (low)
Watch
- none
How to validate: `xerg audit --compare --push`

Common commands

xerg init
xerg audit --compare
xerg connect
xerg mcp-setup

More explicit examples:

xerg doctor --runtime openclaw
xerg audit --runtime hermes
xerg audit --since 24h --compare
xerg audit --push
xerg push

Works where your agent data lives

• Local machine: OpenClaw, Hermes, and explicit Cursor usage CSV exports
• VPS or remote server: OpenClaw only in this phase
• If OpenClaw runs remotely, you can audit it from your local machine with xerg audit --remote user@host
• Or point Xerg at exported files directly with flags

Remote prerequisites:

• SSH audits require ssh and rsync on your PATH
• Optional legacy Railway audits require the railway CLI on your PATH

Default paths

By default, Xerg checks:

• OpenClaw: /tmp/openclaw/openclaw-*.log
• OpenClaw: ~/.openclaw/agents/*/sessions/*.jsonl
• Hermes: ~/.hermes/logs/agent.log* with gateway.log* fallback
• Hermes: ~/.hermes/sessions/

Use explicit paths when needed:

xerg audit --runtime openclaw --log-file /path/to/openclaw.log
xerg audit --runtime openclaw --sessions-dir /path/to/sessions
xerg audit --runtime hermes --log-file ~/.hermes/logs/agent.log
xerg audit --runtime hermes --sessions-dir ~/.hermes/sessions
xerg audit --cursor-usage-csv ./cursor-usage.csv

If only one supported local runtime is present, Xerg auto-selects it. If both OpenClaw and Hermes are present locally, rerun with --runtime openclaw or --runtime hermes.

If local defaults are empty, xerg init prints next-step commands for explicit local paths plus remote OpenClaw-only flows:

xerg audit --remote user@host

Hosted follow-up

Hosted sync and hosted MCP are optional paid workspace features. The simplest hosted path is:

xerg connect
xerg mcp-setup

• connect resolves auth from XERG_API_KEY, ~/.xerg/config.json, or stored browser credentials, then offers to push the latest audit
• mcp-setup prints or writes hosted MCP config for Cursor, Claude Code, Codex, or another client

You can skip both and keep using local audits and compare.

Authentication and config

Push commands resolve credentials in this order:

1. XERG_API_KEY
2. ~/.xerg/config.json
3. stored browser credentials from xerg login at ~/.config/xerg/credentials.json

Optional API URL overrides:

• XERG_API_URL
• apiUrl in ~/.xerg/config.json

Example ~/.xerg/config.json:

{
  "apiKey": "sk_live_or_test_key",
  "apiUrl": "https://api.xerg.ai"
}

xerg connect is the guided hosted path. xerg login remains available when you want browser auth without the push prompt.

xerg login stores a browser-issued token in ~/.config/xerg/credentials.json. That token store is separate from ~/.xerg/config.json. Hosted MCP works best with a workspace API key.

What the audit shows

• Total spend by workflow and model, in dollars
• Daily spend and confirmed waste rollups in UTC
• Observed vs. estimated cost (always labeled)
• Confirmed waste: retry and loop findings when the required source structure is present
• Provenance-aware waste rollups by observed, inferred, declared, or unknown signal source
• Savings opportunities: context bloat, downgrade candidates, idle, max mode concentration where applicable
• Ranked recommendations with where-to-change guidance and compare validation steps
• Before/after normalized rates on re-audit, including waste per run and waste per 1k calls

Local JSON findings may include signalSource, ruleId, and evidence references so agents can distinguish observed signals from inferred or legacy unknown provenance. These local provenance fields are not part of the pushed v2 wire payload.

Privacy

Xerg v0 stores economic metadata and audit summaries locally. It does not store prompt or response content.

Exit codes

• 0: success
• 1: general failure
• 2: no supported local runtime data was found
• 3: a --fail-above-waste-rate or --fail-above-waste-usd threshold was exceeded

Troubleshooting

• If install fails with an unsupported engine warning, retry with Node 22 or 24.
• xerg init is interactive in v1. Use direct doctor / audit commands when you need non-interactive control.
• --verbose prints progress updates to stderr for xerg doctor and xerg audit, which helps distinguish package install time from CLI runtime.
• If xerg audit --remote ... fails before pulling files, verify that both ssh and rsync are installed and reachable on your PATH.
• If a legacy Railway audit fails immediately, verify that the railway CLI is installed, authenticated, and can access the target project.

Pilot and support

• Pilot: xerg.ai/pilot
• Support: [email protected]