# Hermes Efficiency

> Hermes Token Efficiency

- Skill: `lucadominguez/hermes-efficiency` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lucadominguez/hermes-efficiency`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucadominguez/hermes-efficiency/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lucadominguez (https://skillmd.com/u/lucadominguez)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lucadominguez/hermes-efficiency

---

# Hermes Token Efficiency

Comprehensive cost optimization for Hermes Agent setups. Apply these techniques to reduce API spend by 25-75% without losing capability.

## Core Principles

> Transform LLM from "all-purpose butler" to "expert advisor" — CPU-fy daily operations, let complex reasoning go to large models.

### The 7 Techniques (adapted for Hermes)

| # | Technique | Hermes Implementation | Savings |
|---|-----------|----------------------|---------|
| 1 | **Tree-structured bootstrap** | Shrink SOUL.md to rules only; move references to loadable skills | ~66% bootstrap |
| 2 | **Context compression** | `compression.enabled: true` (already on) | 50% long sessions |
| 3 | **Local model for light tasks** | (needs Ollama + 3GB RAM) | up to 100% |
| 4 | **Script-to-API, bypass bootstrap** | `no_agent: true` cron jobs with Python scripts | 100% per task |
| 5 | **Quick commands vs LLM** | `quick_commands` in config.yaml | 100% per use |
| 6 | **CPU-fy cron tasks** | Replace LLM cron with Python watchdog scripts | 100% per task |
| 7 | **Checklist-ified heartbeats** | Simple `no_agent` scripts checking status | 100% per check |

## Implementation Checklist

### ✅ Immediate (zero cost, apply now)
1. Shrink SOUL.md to behavioral rules only (<1,500 bytes)
2. Convert mechanical cron jobs to `no_agent` Python scripts
3. Add `quick_commands` for common maintenance (`/status`, `/disk`, `/mem`)
4. Add RTK command prefix guidance
5. Set up tiered model routing (cheap for subagents/cron, strong for main)

### 🔧 Medium (requires setup)
6. Install Ollama + qwen2.5:3b for offline heartbeat checks (needs 3GB RAM)
7. Write Python scripts that call OpenRouter API directly for cron data collection
8. Set up the efficiency tracker cron to measure impact

### 🚀 Advanced
9. RAG-based skill descriptor filtering (only load relevant skills per task)
10. Custom `pre_tool_call` hooks to auto-route operations to local models
11. Token budget alerts via cron

## Current Setup (as of 2026-07-12)

```
SOUL.md:     1,268 bytes  (was 1,465)
Skills:      105 active   (was 114, 10 moved to disabled)
Memory:      2,135 bytes  (87% of 2200 limit)
Cron jobs:   5 total      (3 no_agent, 1 LLM, 1 script-only)
Models:      deepseek-v4-pro (default), mimo-v2.5 (subagents/cron)
Compression: enabled (threshold 0.5, target 0.2)
RTK:         installed (~/.cargo/bin/rtk), guided via AGENTS.md
Hooks:       post_tool_call filter on terminal (compact-output.py)
Tracking:    token-efficiency-tracker.py every 6 hours
```

## Common Pitfalls

### CLAUDE.md → AGENTS.md rename (avoid false model alarms)

**Problem:** Files named `CLAUDE.md` in the working directory get loaded as project context. The user sees "CLAUDE.md" in output and assumes Hermes is using Claude models (expensive), triggering unnecessary investigation sessions that waste tokens confirming the config is already correct.

**Fix:** Rename `CLAUDE.md` to `AGENTS.md`. Hermes loads both filenames as project context files — same functionality, zero "Claude" branding. The file was never calling Anthropic APIs; it was just a filename convention inherited from Claude Code/Cursor.

```bash
mv CLAUDE.md AGENTS.md  # safe, Hermes reads both
```

**Token impact:** Each false-alarm investigation burns ~5-10K tokens confirming model config. One rename prevents recurring waste.

## Efficiency Tracking

The token-efficiency-tracker runs every 6 hours and writes to `~/.hermes/logs/efficiency/efficiency-YYYYMMDD.json`.

View current stats:
```bash
cat ~/.hermes/logs/efficiency/efficiency-$(date +%Y%m%d).json | python3 -m json.tool
```

Or use quick command: `/efficiency`

## Rollback

All changes are reversible:
```bash
# Restore SOUL.md from backup
cp ~/.hermes/hermes-agent/.hermes-cost-optimization/backups/20260604-062615/files/SOUL.md ~/.hermes/SOUL.md

# Revert cron jobs to LLM mode
hermes cron update <job_id> --no-agent=false --script=''

# Remove hooks
hermes config set hooks '{}'

# Restore all skills
mv ~/.hermes/skills-disabled/* ~/.hermes/skills/
```