Skip to main content
npx @xerg/cli@latest doctor is the fastest way to confirm that Xerg can see local OpenClaw, Hermes, or Claude Code data before you run an audit. Examples use npx @xerg/cli@latest. If you installed the CLI globally, substitute xerg.

​
Local checks

Xerg reports:
  • the default gateway pattern
  • the default sessions pattern
  • detected source files
  • notes about what is missing
Use --verbose when you want progress messages on stderr while doctor is checking paths and transports. For local sources it also prints an extraction-coverage report: per source file, how many calls were extracted and which economic signals the parser found (tokens, observed cost, cache tokens, stop reasons, tool names, latency), plus any unpriced models. Detected files that produced zero included calls are listed too, with their full local paths and an explicit calls: 0 row — including total extraction failure, where a file parses but no record carries usage. Use it to spot silent extraction gaps before they show up as $0 spend. This per-file breakdown is local-only; audit reports and pushed payloads carry a count-only note instead. Use explicit local paths when your data is not in the defaults:
If OpenClaw and Hermes are both present locally, pass --runtime openclaw or --runtime hermes so doctor checks the exact runtime you mean. Claude Code checks are always explicit via --runtime claude-code. Hermes doctor opens state.db read-only and reports schema/read failures, observer installation, ledger freshness, malformed records, unmatched sessions, writer drop counts, and request-reconciliation readiness (full, partial, or none). The observer is optional; an observer ledger or Hermes trace capture by itself is not an auditable monetary source. To inspect Claude Code session transcripts:
Claude Code doctor reports the projects directory it checked (default ~/.claude/projects), the transcript files it found, and the exact audit command to run next. To inspect a local Cursor usage export instead:
Cursor CSV doctor validates the file shape, row count, date range, and current pricing coverage.

​
SSH checks

SSH doctor checks:
  • SSH connectivity
  • whether rsync exists locally and remotely
  • default remote paths
  • optional custom remote paths when you pass --remote-log-file or --remote-sessions-dir
Custom remote paths:

​
Railway checks

By default, Railway doctor uses the Railway service linked to the current working directory in your local railway CLI context. If railway link in this directory points at a database, sidecar, or another non-OpenClaw service, doctor can authenticate successfully but still report that the linked service is unreachable or has no OpenClaw data. Re-run railway link in the directory where you invoke Xerg and choose the OpenClaw app service. Use explicit --project, --environment, and --service values when you want a deterministic Railway target instead of the service linked to the current directory. You can also target a specific service:
Railway doctor checks:
  • whether the railway CLI is installed
  • whether the railway CLI is authenticated
  • whether the target service is reachable
  • default and alternate OpenClaw paths
  • optional custom remote paths when you pass --remote-log-file or --remote-sessions-dir
Railway checks these paths by default:
  • /tmp/openclaw for gateway logs
  • ~/.openclaw/agents for session files
  • /data/.clawdbot/agents/main/sessions as an alternate session directory when the default one is empty

​
When doctor says no data

If doctor cannot find any local OpenClaw or Hermes data:
  • for Hermes v0.17+, verify ~/.hermes/state.db exists or pass --state-db
  • for legacy Hermes or OpenClaw data, pass explicit paths with --log-file and --sessions-dir
  • run npx @xerg/cli@latest doctor --runtime claude-code if you use Claude Code; transcripts are created automatically under ~/.claude/projects
  • run npx @xerg/cli@latest doctor --remote user@host to inspect an SSH target directly from your machine
  • run npx @xerg/cli@latest doctor --railway to inspect a linked Railway service
  • use --project, --environment, and --service when you want a deterministic Railway target instead of the service linked to the current directory
  • run npx @xerg/cli@latest audit --remote user@host or npx @xerg/cli@latest audit --railway when the data lives on another machine or service; see remote audits for the full workflow
  • remote audits still pull telemetry to the machine where you run Xerg and analyze it locally