Hermes Token Diet: 32% Less Overhead, 96% Less per-Turn Growth
Hermes Agent ships with a full toolset and a large skills catalog enabled by default. For a first-time user this is the right call - everything works out of the box. For a daily driver, those defaults mean every API call carries thousands of tokens of tool schemas the agent never uses.
Brice Neal released hermes-token-diet v0.2.1 on July 2 to address this. It is a CLI that audits real token usage, shows exactly what is burning context, applies a preset to trim unused tools and skills, and verifies the savings. Every change is a documented edit to ~/.hermes/config.yaml with automatic timestamped backups. No Hermes patches.
What gets trimmed
Hermes sends tool definitions, system prompts, and loaded skill schemas on every API turn. Tool definitions alone account for 8,000 to 10,000 tokens per call. Disabling toolsets you never use removes their schemas from every request. Disabling skill categories removes them from the eager system-prompt index - skill_view() still works on demand.
The tool ships three profiles:
| Profile | Toolsets kept | Use case |
|---|---|---|
| minimal | Core only (file, terminal, memory, skills, todo, session_search, context_engine) | Minimal token budget, headless use |
| daily | Core + web, browser, code_execution, cronjob | Coding and ops assistant (recommended) |
| balanced | Daily + creative and media skills | Multimedia and research workflows |
Each profile also sets conservative file-read and tool-output caps. The daily profile limits file_read_max_chars to 20,000 and tool_output.max_bytes to 8,000 - lower than the unrestricted defaults, which prevents the agent from loading large files into context on every turn.
An optional --usage-tuned flag re-enables toolsets or skill categories you actually used in the last 14 days, pulled from ~/.hermes/state.db. You get back whatever you need and nothing you do not.
The numbers
Neal ran the tool against a live Hermes v0.17.0 instance with the kimi-k2.6 model on Ollama Cloud. The daily profile produced these results:
| Metric | Before | After | Reduction |
|---|---|---|---|
| Fixed overhead (single "hi" message) | ~19,200 tokens | ~13,140 tokens | -32% |
| Per-exchange token growth | ~9,500 tokens | ~371 tokens | -96% |
The per-exchange growth reduction is the more important number for long sessions. At 9,500 tokens per exchange, a 256K context window fills past 50% after 13 turns. At 371 tokens per exchange, the same model can sustain hundreds of turns before compression fires. The 32% fixed-overhead savings compounds across every session, but the 96% per-turn growth reduction is what keeps long-running workflows affordable.
Context Watch
The package includes a live monitoring addon called Context Watch. It polls active Hermes sessions and reports context-window fatigue metrics, with configurable warning and critical thresholds:
token_diet_watch:
thresholds:
token_ratio_warning: 0.60
token_ratio_critical: 0.80
compactions_warning: 3
compactions_critical: 6
growth_per_exchange_warning: 4000
growth_per_exchange_critical: 7000
A check command runs on the active session and writes a markdown report to ~/.hermes/scratch/context-diet-latest.md when thresholds are crossed. Hermes can read its own diet report - the tool feeds back into the agent it monitors.
What does not change
The tool does not touch MCP server configs, provider settings, or any non-toolset configuration. Disabling a skill category removes it from eager indexing but does not delete the skill file. Backups are created automatically before every profile application with timestamps in the filename (config.yaml.bak.token-diet-*). A revert command restores from any backup.
For users running large skill catalogs with dozens of connected MCP servers, this targets the single biggest line item in per-call token cost - tool schema payloads - without restructuring the agent.
[^1]: Neal, Brice. "hermes-token-diet v0.2.1." PyPI. July 2, 2026. [^2]: Neal, Brice. "Hermes Token Diet repository." GitHub. [^3]: "Cut your Hermes Agent token bill in half." LumaDock. April 16, 2026.