Xerg

Audit OpenClaw and Hermes workflows in dollars. Local-first audits with init, compare mode, OpenClaw remote support, CI gates, and optional hosted follow-up.

Security Scan

The skill's instructions match an audit tool for OpenClaw/Hermes, but the package metadata under‑declares required credentials, binaries, and config-path access — a mismatch you should review before use.

Purpose & Capability

The SKILL.md and README consistently describe a local-first audit tool for OpenClaw and Hermes and remote audits via SSH/Railway — that purpose is coherent. However, the registry metadata lists no required env vars, binaries, or config paths, while the instructions explicitly reference XERG_API_KEY, ~/.xerg/config.json, browser login, and required CLIs (ssh, rsync, railway, npx). The metadata under-declares the actual capabilities and prerequisites.

Instruction Scope

The instructions tell the agent to read local gateway logs and session files (expected for an auditor) and to connect to remote hosts via SSH/Railway (also expected). They also instruct optional pushing to a hosted service and mention browser auth and writing hosted MCP config. These behaviors are within the stated purpose, but they entail reading user-specific config files and potentially transmitting audit results if the user initiates a push — the SKILL.md claims 'no data leaves your machine unless you explicitly push', which relies on the user not running push/connect.

Install Mechanism

This is an instruction-only skill (no install spec or code files), which limits direct risk. The docs recommend using an external CLI via 'xerg' or 'npx @xerg/cli' — note that running 'npx' will fetch and execute code from npm at runtime, so the actual behavior depends on the external npm package, which is not bundled with the skill.

Credentials

SKILL.md references XERG_API_KEY, ~/.xerg/config.json, and browser login as possible auth methods for pushing, and references use of ssh/rsync/railway for remote access. Yet requires.env and required binaries in the registry metadata are empty. The skill thus implies access to secrets/configuration and remote credentials without declaring them — a proportionality and transparency issue that makes it harder to reason about what will be read or sent.

Persistence & Privilege

The skill is not always-enabled, is user-invocable, and does not request persistent platform privileges. It may write or print hosted MCP config when the user runs 'mcp-setup' or run 'connect' to prompt browser auth, which is expected behavior for an optional hosted integration.

What to consider before installing

This skill appears to be a legitimate local audit tool, but the metadata under-reports what it will touch. Before installing or running it: (1) verify the upstream npm package and GitHub repository it references (confirm publisher and review source); (2) be aware running 'npx @xerg/cli' will fetch and execute remote code; (3) inspect ~/.xerg/config.json (and any XERG_API_KEY) before using any 'push' or 'connect' commands — do not push sensitive data to hosted services unless you trust the provider; (4) if using remote audits, ensure you understand what SSH/Railway access you'll grant and consider running audits in an isolated environment; and (5) prefer installing and reviewing the CLI source locally rather than blindly running npx.

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

xerg init
xerg audit --compare

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

xerg doctor
xerg audit
xerg audit --json
xerg audit --fail-above-waste-rate 0.30

Inputs

Xerg needs one of these source inputs:

• Local OpenClaw data at the default paths:
  • /tmp/openclaw/openclaw-*.log
  • ~/.openclaw/agents/*/sessions/*.jsonl
• Local Hermes data at the default paths:
  • ~/.hermes/logs/agent.log* with gateway.log* fallback
  • ~/.hermes/sessions/
• Explicit paths via --log-file and/or --sessions-dir
• An SSH target via --remote
• A Railway target via --railway
• A multi-source config via --remote-config

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 xerg login
• 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. Start with the default first-run path when you want the fastest local result:

xerg init

• 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

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

xerg doctor
xerg doctor --verbose
xerg doctor --remote user@host
xerg doctor --railway

• 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

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

xerg audit
xerg audit --runtime openclaw
xerg audit --runtime hermes

4. Choose the right output mode for the task:

xerg audit
xerg audit --json
xerg audit --markdown

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

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

xerg audit --compare
xerg audit --compare --json

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

xerg audit --markdown > xerg-audit.md
xerg connect
xerg mcp-setup
xerg audit --push
xerg push

• connect is the guided hosted path: it reuses existing auth, prompts before browser login when needed, and offers to push the latest audit
• mcp-setup 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:

xerg audit

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

Explicit local paths:

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

SSH remote:

xerg audit --remote [e-mail]
xerg audit --remote [e-mail] \
  --remote-log-file /opt/openclaw/logs/openclaw.log \
  --remote-sessions-dir /opt/openclaw/sessions

Railway:

xerg audit --railway
xerg audit --railway --project <id> --environment <id> --service <id>

Multiple remote sources:

xerg audit --remote-config ~/.xerg/remotes.json

Remote config files use this shape:

{
  "remotes": [
    {
      "name": "prod",
      "transport": "ssh",
      "host": "[e-mail]"
    },
    {
      "name": "railway-prod",
      "transport": "railway",
      "railway": {
        "projectId": "...",
        "environmentId": "...",
        "serviceId": "..."
      }
    }
  ]
}

CI And Automation

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

xerg audit --push --fail-above-waste-rate 0.25 --fail-above-waste-usd 100

Common variants:

xerg audit --fail-above-waste-rate 0.30
xerg audit --fail-above-waste-usd 50
xerg audit --since 24h --fail-above-waste-rate 0.30

Documented exit codes:

• 0 success
• 1 runtime error
• 2 no supported local runtime data found
• 3 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. Each recommendation item includes:

• id, findingId, kind, title, summary
• priorityBucket, recommendedOrder, implementationSurface, category
• severity, confidence, effort
• estimatedSavingsUsd, estimatedSavingsPct
• scope, scopeId, scopeLabel
• whereToChange, validationPlan, actions

Current recommendation kinds map into the Action queue buckets:

• fix_now: retry-waste, loop-waste
• test_next: context-outlier, idle-spend, candidate-downgrade, cache-carryover, max-mode-concentration
• watch: unknown or uncategorized findings

Prefer high-confidence or reversible fixes first. Treat model downgrades, context changes, and Cursor behavior changes as compare-friendly experiments, 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
• XERG_API_KEY 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 xerg logout
• Pilot: xerg.ai/pilot
• Support: [e-mail]