Skip to content

Hermes Usage Insights

Operational manual · Clawlter edition

Track, search, report on, and visualize Hermes token usage with a calm, instrument-panel workflow instead of raw artifact spelunking.

Quick start Choose a collection path

  • deterministic demo data
  • Hermes importer + watcher
  • SQLite reports
  • daily plots + exports

Field posture

Built for operators who want exact answers fast.

  • start from a known-good local database
  • import existing Hermes data without patching Hermes itself
  • move to JSONL ingestion only when you need exact upstream control
  • keep schema, CLI, and troubleshooting pages close at hand

Quick start

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

Common tasks

Get a database running quickly

  • Getting started gives the shortest first-run path.
  • Use deterministic demo data before pointing the tool at real Hermes artifacts.
  • Treat the demo pass as a smoke test for the local environment.

Choose the right collection path

  • Choose a collection path maps the tradeoffs between demo data, import, collector mode, and JSONL ingestion.
  • Use collector mode when low-friction adoption matters most.
  • Use JSONL ingestion when exact upstream event control matters most.

Import or watch Hermes data

  • Hermes integration covers the importer and the always-on collector workflow.
  • Use import-hermes for one-shot backfills.
  • Use watch-hermes when the usage database should stay warm.

Report, search, export, and plot

  • CLI reference is the fastest route to exact command behavior.
  • Event schema matters when emitting structured JSONL yourself.
  • Troubleshooting is the first stop when totals or tool breakdowns look wrong.

Documentation map

Guides

Move from first run to steady operation.

Reference

Keep the command surface close.

Why this docs stack

These docs use MkDocs Material because the project needs a maintainable operational manual, not a hand-built HTML site and not an API-autodoc-heavy framework. The result is simpler to extend, easier to theme, and faster to keep accurate as the CLI evolves.

  • Markdown-native authoring and navigation
  • built-in search and mobile-safe structure
  • documented theming hooks instead of custom page assembly
  • enough room for a distinct Clawlter voice without fighting the framework