What This Plugin Does

Note

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

Hermes Agent runs autonomously — across sessions, platforms (CLI, cron, Telegram, Discord), and subagents — which means it can keep spending even when you’re not watching. hermes-telemetry lives inside the runtime as a Hermes plugin and does two things:

1. Captures telemetry (tokens, cost, latency, tool calls, session metadata) and persists it to a local SQLite database.
2. Enforces budget guardrails before the next tool call is made — soft alerts injected into the conversation, hard blocks that abort tool calls when limits are exceeded, and cron-job pausing for future runs.

Design principle: observability is invisible to the model. Everything goes through hooks. The only user-facing surface is /stats, /budget, and /setup. Errors are swallowed in every hook — the plugin must never take down a session.

Runtime modes

The plugin setting plugins.entries.hermes-telemetry.settings.mode controls whether budget behavior is active:

• enforce (default): enable the budget guardrails and setup behavior described below. Missing mode, invalid values, and older Hermes hosts without ctx.get_config all resolve to enforce so upgrades never silently drop blocking.
• observe: collect and report telemetry; do not create budget.yaml automatically, inject budget notices, block tools, or pause cron jobs. The budget file watcher still runs so /budget hot-reloads. When a budget.yaml is present, /budget and the dashboard budget panel say limits are not enforced.

The mode is read during plugin registration. Changing it requires restarting the Hermes process that owns the plugin.

This plugin was built for the Hermes Agent Challenge and addresses NousResearch/hermes-agent#6642.