Hermes Usage Insights

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 usage events
• generating summary and breakdown reports
• filtering reports, search, exports, and plots to a date window
• searching stored events
• exporting CSV
• rendering daily token plots

When to use it

Use this project when you want to answer practical questions about Hermes usage over time without manually spelunking raw session artifacts.

Typical use cases:

• backfill a running Hermes deployment into a local analysis database
• keep a no-source-change collector loop running against Hermes artifacts
• ingest richer JSONL telemetry from an upstream emitter
• inspect usage by session, model, skill, tool, or day
• inspect usage by provider or event source
• export results into a spreadsheet or another analysis workflow

Choose a collection path

Path	Best when	Requires Hermes source changes	Continuous	Session totals	Per-tool token attribution
demo-data	You want a fast local proof first	No	No	Demo only	Demo only
import-hermes	You want a one-shot no-source-change backfill	No	No	Yes	No
watch-hermes	You want a continuous no-source-change collector	No	Yes	Yes	No
ingest-jsonl	You already emit structured events and want richer attribution	Usually yes upstream	Depends on caller	Yes if emitted	Yes if emitted

Rule of thumb:

• start with demo-data to prove the package locally
• use import-hermes or watch-hermes for the no-source-change Hermes path
• use ingest-jsonl when you need exact event-level attribution

Installation

From source

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

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

The fastest local proof uses deterministic demo data.

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 report breakdown --by provider --since 2026-04-09 --until 2026-04-10
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png

No-source-change Hermes import

If you already have a Hermes home directory, the simplest real collector path is:

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

For a continuous collector loop:

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

Important limitation:

• collector mode gives accurate session-level totals and tool-call counts
• it does not provide exact per-tool token attribution unless that telemetry is emitted upstream

JSONL ingestion

If you already emit structured usage events, ingest them directly:

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

Common commands

uv run hui --db usage.db init
uv run hui --db usage.db report summary
uv run hui --db usage.db report breakdown --by model
uv run hui --db usage.db report breakdown --by source
uv run hui --db usage.db search "browser_navigate" --limit 10
uv run hui --db usage.db search "browser_navigate" --since 2026-04-09 --until 2026-04-10
uv run hui --db usage.db export csv --output artifacts/usage.csv
uv run hui --db usage.db export csv --since 2026-04-09 --output artifacts/usage.csv
uv run hui --db usage.db plot daily-tokens --output artifacts/daily.png

Documentation

Public documentation site:

• https://clawlter.mehalter.page/hermes-usage-insights/

Key pages:

• docs/overview.md — project overview and operator framing
• docs/getting-started.md — shortest path to a working first run
• docs/collection-paths.md — importer vs JSONL decision guide
• docs/integration.md — Hermes collector-mode and emitter-mode details
• docs/cli-reference.md — command reference
• docs/schema.md — event schema and collector-generated event semantics
• docs/troubleshooting.md — common operational issues

Development

Install dependencies:

uv sync

Run validation:

uv run black --check src tests
uv run isort --check-only src tests
uv run pyright
uv run pytest -q
uv run python -m build
uv run mkdocs build --strict
uv run pytest -q tests/test_docs_site.py

Build distributions:

uv run python -m build
uv run twine check dist/*

Build the documentation site locally:

uv run mkdocs build --strict

This writes a static site into site-build/ using MkDocs Material.