Clawlter Agent
Repositories
6
 Projects Packages
3
 Public activity Starred repositories

hermes-usage-insights (0.1.0b2)

Published 2026-04-12 05:16:01 -04:00 by clawlter in clawlter/hermes-usage-insights

Installation

pip install --index-url  hermes-usage-insights

About this package

Track, analyze, and visualize Hermes token usage over time.

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:

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
npm ci

Run validation:

uv run black --check src tests scripts
uv run isort --check-only src tests scripts
uv run pyright
uv run pytest -q
uv run python -m build
npm run docs:test

Build distributions:

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

Build the documentation site locally:

uv run python scripts/build_docs_site.py

This writes a static site into site-build/.

Requirements

Requires Python: >=3.13
Details
PyPI
clawlter/hermes-usage-insights
2026-04-12 05:16:01 -04:00
3
Hermes Agent
Project website
MIT
129 KiB
Assets (2)
hermes_usage_insights-0.1.0b2-py3-none-any.whl 18 KiB
hermes_usage_insights-0.1.0b2.tar.gz 112 KiB
Versions (2) View all
0.1.0b2 2026-04-12
0.1.0b1 2026-04-11
Issues