Getting started¶

This page is the shortest path from a fresh checkout to a working report.

Requirements¶

Python 3.13+
uv for dependency and command management
a writable location for the SQLite database and any generated artifacts

Local development setup¶

git clone https://code.mehalter.com/clawlter/hermes-usage-insights.git
cd hermes-usage-insights
uv sync

If you are running inside the Hermes runtime used in this environment, the equivalent commands are usually wrapped as:

/opt/hermes-runtime/tools/mise/use-mise.sh uv sync

Fastest first run¶

Use deterministic demo data before wiring a live Hermes instance.

uv run hui --db usage.db demo-data
uv run hui --db usage.db report summary
uv run hui --db usage.db report breakdown --by tool

Expected result:

the SQLite database is created if it does not already exist
deterministic demo events are inserted
you see a summary report and at least one grouped breakdown

First plot and export¶

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

This gives you two quick proof points:

a PNG trend line in artifacts/daily.png
a flat CSV export in artifacts/usage.csv

First real Hermes import¶

If you already have a Hermes home directory and want the no-source-change path, start here:

uv run hui \
  --db artifacts/hermes-usage.db \
  import-hermes \
  --hermes-home /path/to/hermes-home

Then verify the import with:

uv run hui --db artifacts/hermes-usage.db report summary
uv run hui --db artifacts/hermes-usage.db report breakdown --by session
uv run hui --db artifacts/hermes-usage.db report breakdown --by tool

Continuous collection¶

For a long-running collector loop:

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

Use this when:

you want a no-source-change collector
Hermes is already writing state.db and session artifacts
you want the local usage database to keep growing incrementally

When to use a different path¶

Use ingest-jsonl instead of import-hermes or watch-hermes when:

you already emit structured usage events
you need exact per-event or per-tool attribution
you want to ingest data from another upstream producer, not just Hermes artifacts

uv run hui --db usage.db ingest-jsonl path/to/events.jsonl

What to check if the first run looks wrong¶

If the database file did not appear, verify the output path is writable.
If report summary is empty after a real import, verify the Hermes home path is correct.
If tool breakdowns show counts but not meaningful token spend, that is expected in collector mode.
If you need exact per-tool attribution, move to JSONL emitter mode.

For deeper diagnostics, read Troubleshooting.