Module Map

Note

Generated from ONBOARDING.md — the design authority for this project. Edit the source file, not this page.

hermes-telemetry/
├── __init__.py          ← Plugin entry point. Registers all 10 hooks + 3 slash
│                          commands. Contains the cron regex, approx-token store,
│                          and the fallback estimation logic for usage=None.
├── db.py                ← SQLite persistence layer. Schema v1→v3 migrations,
│                          per-thread connections, WAL mode, write API and
│                          read/budget query API.
├── pricing.py           ← Cost estimation engine. Priority-chain lookup
│                          (custom YAML `_subscription`/`:free` → core snapshot
│                          → remaining custom/built-in → prefix match).
│                          All 5 token components. Google-symmetric normalization.
├── pricing_refresh.py   ← Auto-refresh from remote pricing APIs. PricingSource
│                          ABC, OpenRouterSource, GoogleAISource. Merge strategy
│                          preserves manual overrides.
├── budget.py            ← Budget verdict engine. Window math in local tz,
│                          verdict cache, anti-spam ledger, tool-gate helpers,
│                          /budget command, burn-rate forecast.
├── stats.py             ← /stats command implementation. All subcommands:
│                          summary, cron, providers, models, raw, efficiency,
│                          smells.
├── smell_detector.py    ← AI smell detection. Read-only heuristics over existing
│                          runs/tool_calls that flag session anti-patterns
│                          (context rotation, loop traps, tool thrashing, high
│                          error rate, massive sessions). See `§ Agent Intelligence`.
├── moa.py               ← Mixture-of-Agents awareness. Resolves the `provider=
│                          "moa"` virtual-provider preset to its aggregator's
│                          real provider/model so the call is priced/attributed
│                          correctly. See `§ Mixture of Agents (MoA)`.
├── setup_wizard.py      ← /setup command + auto-setup on first load. Generates
│                          pricing.yaml and budget.yaml with defaults.
├── plugin.yaml          ← Plugin metadata: name, version, declared hooks.
│                          `provides_hooks` is declarative only (the loader does
│                          NOT filter against it). Keep it accurate so it matches
│                          the code, but enabling/disabling a hook is done in
│                          `__init__.py`. See `§ Plugin Discovery Gotcha` for the
│                          `name`-collision trap that bit us with PR #44.
├── dashboard/
│   ├── index.html       ← Standalone SPA. Vendored Chart.js, no build step, no auth.
│   └── serve.py         ← stdlib HTTP server, port 8765, --host flag.
├── tests/
│   ├── conftest.py      ← Autouse HERMES_HOME isolation (see Test Isolation).
│   └── test_*.py        ← 262 tests. All in-memory SQLite, no live gateway.
├── config.example.yaml  ← Annotated pricing.yaml example.
└── budget.example.yaml  ← Annotated budget.yaml example.