> ## Documentation Index
> Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Doctor

> Check local, SSH, or Railway audit readiness before you run a full Xerg audit.

`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

```bash theme={null}
npx @xerg/cli@latest doctor
npx @xerg/cli@latest doctor --verbose
```

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:

```bash theme={null}
npx @xerg/cli@latest doctor --runtime openclaw --log-file /path/to/openclaw.log
npx @xerg/cli@latest doctor --runtime openclaw --sessions-dir /path/to/sessions
npx @xerg/cli@latest doctor --runtime hermes --state-db ~/.hermes/state.db
npx @xerg/cli@latest doctor --runtime hermes --hermes-events-dir ~/.hermes/xerg/events
```

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:

```bash theme={null}
npx @xerg/cli@latest doctor --runtime claude-code
npx @xerg/cli@latest doctor --runtime claude-code --claude-code-dir /path/to/projects
```

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:

```bash theme={null}
npx @xerg/cli@latest doctor --cursor-usage-csv ~/Downloads/usage-events-2026-04-08.csv
```

Cursor CSV doctor validates the file shape, row count, date range, and current pricing coverage.

## SSH checks

```bash theme={null}
npx @xerg/cli@latest doctor --remote deploy@prod.example.com
```

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:

```bash theme={null}
npx @xerg/cli@latest doctor \
  --remote deploy@prod.example.com \
  --remote-log-file /var/log/openclaw \
  --remote-sessions-dir /srv/openclaw/sessions
```

## Railway checks

```bash theme={null}
npx @xerg/cli@latest doctor --railway
```

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:

```bash theme={null}
npx @xerg/cli@latest doctor \
  --railway \
  --project <project-id> \
  --environment <environment-id> \
  --service <service-id>
```

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](/docs/remote-audits) for the full workflow
* remote audits still pull telemetry to the machine where you run Xerg and analyze it locally