---
name: hermes-token-usage-audits
description: Audit Hermes Agent token/context burn and recommend optimizations using session DB, insights, cron/job metadata, and tool-output patterns.
version: 1.0.0
created_by: agent
---

# Hermes Token Usage Audits

Use this skill when the user asks why Hermes is using many tokens, hitting limits, burning context, or becoming expensive/slow. The goal is to produce a grounded, prioritized analysis from real Hermes telemetry — not a generic cost-saving essay.

## Trigger phrases

- "viel Token", "Tokenverbrauch", "costs", "usage", "why is this expensive"
- "optimize context", "reduce tokens", "rate limits", "too many tool calls"
- Requests to audit cronjobs, skills, sessions, tool usage, cache, or model routing

## Safety and privacy

1. **Never print secrets.** Do not dump `.env`, auth files, PAT files, or raw secret-bearing config.
2. Prefer aggregate metrics, table summaries, session titles, counts, and rough token estimates.
3. Treat financial/health/project data titles as potentially sensitive; summarize, do not expose raw contents.
4. Do not mutate config or cronjobs during the audit unless the user explicitly asks to implement changes.

## Audit workflow

### 1. Load relevant guidance

- Load this skill.
- If the task is about Hermes configuration itself, consult the Hermes Agent docs/skill for authoritative command names, but do not edit protected bundled/hub skills.
- If a generic token-optimizer skill exists, use its ideas, but verify against Hermes-native telemetry.

### 2. Collect telemetry

Use live tools and actual files/DBs where available:

- `hermes insights --days 30` and/or `hermes insights --days 7` for official overview.
- `~/.hermes/state.db` `sessions` table for input/output/cache/reasoning/API-call counts.
- `messages` table for tool output volume by `tool_name`.
- `~/.hermes/cron/jobs.json` or the cron tool for active LLM-vs-script jobs.
- `~/.hermes/config.yaml`, `AGENTS.md`, skill sizes, and loaded skills for context overhead.

Keep outputs bounded. Use Python summaries or SQL aggregation rather than dumping rows.

### 3. Separate token classes

Always distinguish:

| Class | Meaning | Optimization interpretation |
|---|---|---|
| Input tokens | Non-cache prompt/context sent to model | Direct cost/context pressure |
| Output tokens | Generated answer/tool-call text | Verbosity/loop pressure |
| Reasoning tokens | Hidden/visible reasoning budget | Model/reasoning setting pressure |
| Cache-read tokens | Previously cached context re-read | Often high volume but cheaper; still indicates long sessions/tool loops |
| Cache-write tokens | Cache creation | Expensive when present |
| API-call count | Number of model turns | Usually the best proxy for runaway agent loops |

Do not collapse these into one ambiguous number without explanation.

### 4. Identify top burners

Rank at least four lenses:

1. **Source/platform:** Telegram vs cron vs subagent/CLI.
2. **Session:** top sessions by total tokens and by non-cache tokens.
3. **Theme/category:** approximate from session titles, e.g. Crypto, FamilyDashboard, AutoShorts, Health, Finance, Work/Protocols.
4. **Tools:** aggregate tool result chars by `tool_name`; common burners are `terminal`, `read_file`, `skill_view`, `session_search`, browser snapshots, and large patches.
5. **Skills/context:** estimate large `SKILL.md` files and repeated `skill_view` loads.
6. **Cronjobs:** list which are `no_agent=True` versus LLM-driven; do not assume cron is the problem.

### 5. Interpret before recommending

Common durable patterns:

- Interactive Telegram/build/debug sessions usually dominate over cron if they contain hundreds of API calls.
- Long sessions with many tool calls multiply context even when cache-read tokens mask true incremental cost.
- `read_file` and terminal logs burn tokens when broad outputs are repeatedly fed back to the model.
- Large umbrella skills are worthwhile but should be loaded once and split into short index + deep references when they become recurring overhead.
- Script-only cronjobs (`no_agent=True`) are usually cheap in model tokens; optimize LLM cronjobs last unless telemetry proves otherwise.

## Recommendation framework

Prioritize actions by expected impact:

1. **Session hygiene:** split or compress after long build/debug blocks, high API-call count, or clear milestones. Save a compact checkpoint rather than carrying all history. After an independently approved sprint/commit boundary, prefer a fresh session for the next sprint instead of continuing the full review transcript.
2. **Batch mechanical inspection:** use scripts/SQL/Python summaries for repeated reads, log scans, metrics, and file inventories instead of model-tool ping-pong.
3. **Bound tool output:** read narrow line ranges; summarize logs; filter test output to failures; avoid dumping whole files or full session_search windows.
4. **Lightweight worker routing:** when a separately-quotaed model profile exists, proactively send bounded tests, lint fixes, small bug fixes, log analysis, and PR drafts through its wrapper. Native `delegate_task` usually inherits the parent model and therefore does not realize this quota split. The main model still verifies and owns every side effect.
5. **Review discipline:** avoid serial waves of broad independent reviews after every tiny patch. Reproduce exact findings locally, batch related fixes/tests, then run one final independent approval pass on the frozen candidate. Re-dispatch only when the reviewed code changed materially.
6. **Skill diet:** split large skills into short SKILL.md plus `references/` details; avoid re-loading the same giant skill repeatedly.
7. **Cron audit:** convert routine LLM cronjobs to script-only or script-gated LLM where possible; set explicit lightweight model/toolsets for scheduled reasoning jobs.
8. **Toolset minimization:** for scheduled/subagent work, enable only needed toolsets.
9. **Regular reporting:** run `hermes insights --days 7/30` periodically and compare deltas.

## Reporting format for Sir

Sir prefers concise German status with clear symbols. For token audits:

- Start with a short verdict: what burns most tokens.
- Include grounded tables with counts/tokens.
- Separate "Befund" from "Empfehlung".
- Prioritize with impact/effort.
- Avoid generic lectures; make it operational.

Suggested structure:

```markdown
Sir, Kurzfassung: ...

## ✅ Befund
| Bereich | Sessions | API-Calls | Tokens | Anteil |
...

## 🔥 Top-Brenner
...

## 🎯 Optimierungsplan
1. ...

## Prioritäten
| Prio | Massnahme | Aufwand | Wirkung |
```

## Verification checklist

Before finalizing an audit:

- [ ] Did you use actual Hermes telemetry or clearly state what was unavailable?
- [ ] Did you distinguish cache-read from non-cache tokens?
- [ ] Did you check cronjobs before blaming them?
- [ ] Did you identify tool-output and skill-load patterns?
- [ ] Did you provide prioritized, actionable optimizations?

## References

- `references/state-db-token-audit.md` — SQL/Python query patterns for Hermes session DB token audits.