Troubleshooting¶

This page covers the most common situations where the package appears to work but the output is confusing, incomplete, or empty.

`report summary` shows no data¶

Possible causes:

the database path points at a fresh or unexpected file
no events were ingested yet
the JSONL path or Hermes home path was wrong

Checks:

uv run hui --db usage.db demo-data
uv run hui --db usage.db report summary

If that works, the package is healthy and the issue is likely with your real input path.

`import-hermes` completed but the totals look too small¶

Collector mode prefers state.db when it is available because that is the most accurate source of cumulative session totals on current Hermes builds.

Possible causes:

the Hermes home path was wrong
the Hermes deployment does not have the expected state.db or sessions/ layout
you are looking at a partial snapshot of the Hermes home directory

Checks:

verify --hermes-home points at the Hermes home root
confirm the directory contains state.db
confirm the directory contains sessions/session_<id>.json files

Tool breakdowns show events but not meaningful token attribution¶

This is the most important collector-mode limitation.

In no-source-change collector mode:

session totals are imported accurately from Hermes cumulative state
tool-call events come from session transcripts
those tool-call events do not carry exact per-tool token usage unless Hermes persisted it upstream

Practical consequence:

report breakdown --by tool is reliable for tool frequency
it is not a precise spend-by-tool report in collector mode

If you need precise attribution, switch to JSONL emitter mode.

Re-running imports seems to add less data than expected¶

That is usually correct behavior.

The importer is designed to be incremental and idempotent:

session summary imports add only new deltas
tool-call imports reuse deterministic event ids so repeated imports do not duplicate the same events

This means a second import against unchanged Hermes data should add little or nothing.

`watch-hermes` needs to stop after a bounded test run¶

Use --iterations for a bounded polling run.

uv run hui \
  --db artifacts/hermes-usage.db \
  watch-hermes \
  --hermes-home /path/to/hermes-home \
  --interval-seconds 5 \
  --iterations 2

This is useful for smoke tests and automation.

`search` does not behave like full-text search¶

Search is intentionally simple.

Current behavior:

normalized substring matching over stored event text
includes notes, metadata, tool names, skills, models, and other normalized event text
does not implement advanced ranking, stemming, or fuzzy matching

If you need more sophisticated downstream analysis, export CSV and process the data in another tool.

Plot or export commands fail because the output path does not exist¶

The package expects the output location to be writable.

Recommended pattern:

mkdir -p artifacts
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png
uv run hui --db usage.db export csv --output artifacts/usage.csv

The docs-site build fails locally¶

The docs site is built from:

markdown source files in docs/
the MkDocs configuration in mkdocs.yml
optional theme overrides in docs/assets/

Typical local build flow:

uv sync
uv run mkdocs build --strict
uv run pytest -q tests/test_docs_site.py

If the Python build step fails, verify that the project dependencies were installed with uv sync first.

I need the portable command form and the Hermes-runtime command form¶

Use the portable command form in general documentation:

uv run hui --db usage.db report summary

If you are operating inside the Hermes runtime used in this environment, the wrapper form is typically:

/opt/hermes-runtime/tools/mise/use-mise.sh uv run hui --db usage.db report summary

The underlying behavior is the same. The wrapper is environment-specific convenience, not a package requirement.