Overview¶

Hermes Usage Insights is a small Python package for collecting, storing, and inspecting Hermes usage telemetry.

It gives you a local SQLite database plus a CLI for:

importing Hermes session artifacts without changing Hermes source
ingesting structured JSONL events when you already emit telemetry upstream
generating summary and breakdown reports
searching stored events
exporting CSV for external analysis
rendering daily token plots as PNG files

What problem it solves¶

Hermes already produces useful runtime artifacts, but those artifacts are not organized for inspection over time.

Hermes Usage Insights turns that raw material into a durable usage database so you can answer questions like:

which sessions consumed the most tokens?
which models or tools appear most often?
what changed across days or deployments?
can I backfill a running Hermes instance without modifying Hermes itself?
can I export the data into a spreadsheet or another analysis tool?

What the package does not promise¶

This project is intentionally small and explicit about its limits.

In no-source-change collector mode, it provides accurate session-level totals and tool-call counts, not exact per-tool token attribution.
For exact per-event attribution, you need to emit structured JSONL events from Hermes or another upstream source.
It is a local analysis tool, not a hosted telemetry service.

Choose a collection path¶

There are three practical ways to start.

1. Demo data¶

Use this when you want to verify the package locally before wiring real Hermes data.

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

2. No-source-change Hermes import¶

Use this when you already have a Hermes home directory and want to backfill or continuously collect usage without patching Hermes.

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

3. Structured JSONL ingestion¶

Use this when you already emit usage events upstream and want the most flexible ingestion path.

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

For a fuller decision guide, read Choose a collection path.

Installation¶

Install from source for local development¶

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

Install from the Forgejo PyPI registry¶

pip install \
  --index-url https://<username>:<token>@code.mehalter.com/api/packages/clawlter/pypi/simple \
  --no-deps \
  hermes-usage-insights==0.1.0b2

Notes:

Use a Forgejo personal access token when authentication is required.
Prefer --index-url over --extra-index-url to avoid dependency-confusion risk.
0.1.0b2 is the current beta release and should be treated as pre-1.0 software.

Quick start¶

This is the fastest local proof that the package is working.

uv sync
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
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png

Typical outcomes¶

Once data is in the database, the package supports a few common workflows well:

inspect high-level usage totals with report summary
rank usage by tool, skill, session, model, or day with report breakdown
search notes and metadata with search
export rows for spreadsheets with export csv
produce a quick visual daily trend with plot daily-tokens