feat: /insights command — usage analytics, cost estimation & activity patterns

[teknium1]

Summary

Adds an /insights command inspired by Claude Code's /insights, adapted for Hermes Agent's multi-platform architecture. Analyzes session history from state.db to produce comprehensive usage analytics.

What it does

Generates a report covering:

• 📋 Overview — sessions, messages, tool calls, tokens, estimated cost, active time, averages
• 🤖 Models Used — per-model breakdown with sessions, tokens, and cost estimation
• 📱 Platforms — CLI vs Telegram vs Discord etc. (unique to Hermes's multi-platform nature)
• 🔧 Top Tools — most-used tools ranked with call counts and percentages
• 📅 Activity Patterns — day-of-week bar chart, peak hours, active days, best streak
• 🏆 Notable Sessions — longest, most messages, most tokens, most tool calls

Cost Estimation

Includes real pricing data for 25+ models (OpenAI, Anthropic, DeepSeek, Google, Meta) with fuzzy model name matching — strips provider prefixes, handles keyword heuristics (opus, sonnet, haiku, etc.), falls back to defaults for unknown models.

Three Entry Points

1. /insights slash command in CLI — full terminal-formatted report with box-drawing and bar charts
2. /insights slash command in gateway (Telegram/Discord/etc.) — compact markdown format
3. hermes insights CLI subcommand — standalone usage

Configurable

• --days N — time window (default: 30 days)
• --source <platform> — filter by platform (cli, telegram, discord, etc.)
• Gateway shorthand: /insights 7 sets days=7

Example Output

  ╔══════════════════════════════════════════════════════════╗
  ║                    📊 Hermes Insights                    ║
  ║                       Last 30 days                       ║
  ╚══════════════════════════════════════════════════════════╝

  📋 Overview
  ────────────────────────────────────────────────────────
  Sessions:          507           Messages:        44,517
  Tool calls:        40,841        User messages:   1,848
  ...

  🤖 Models Used
  ────────────────────────────────────────────────────────
  Model                          Sessions       Tokens     Cost
  claude-opus-4.6                     487            0 $  0.00
  ...

  📅 Activity Patterns
  ────────────────────────────────────────────────────────
  Mon  █████           59
  Tue  ███████         80
  Wed  ██████████      107
  Thu  ███████         77
  Fri  ███████████████ 155
  Sat  █               14
  Sun  █               15

Files Changed

File	Purpose
agent/insights.py	Core insights engine — data gathering, computation, formatting
cli.py	/insights slash command handler in CLI
gateway/run.py	/insights slash command handler in gateway (+ help text)
hermes_cli/commands.py	Command definition for autocomplete
hermes_cli/main.py	hermes insights CLI subcommand
tests/test_insights.py	56 tests — pricing, formatting, engine, edge cases

Tests

56 new tests covering:

• Pricing lookup (exact match, prefix, heuristics, unknown, null)
• Cost estimation calculations
• Duration/bar chart formatting helpers
• Empty database handling
• Full populated database with multi-platform sessions
• Source and days filtering
• Terminal and gateway formatting
• Edge cases (no tokens, no end time, no model, no tools, single platform)

Full test suite: 1982 passed, 5 skipped, 0 failures.

Future Ideas

• LLM-powered qualitative analysis (session goal categorization, friction detection) — like Claude Code's facet extraction
• HTML report export
• Cost tracking over time (trend charts)
• Per-user breakdown for multi-user gateway instances