60+ compactions into one Claude Code session, the summary had kept 0 of 12 older decisions.
- HERMES-GAUGE v0.5.0
- HERMES AGENT PLUGIN HACKATHON
Your agent never tells you its context is overflowing. Now it does.
hermes-gauge measures context continuously, like a fuel gauge. It warns before the crash. It never compacts on its own, and it never opens the next session.
- 65%up to · fewer tokens per turn
- 1Mannounced
- 250Kusable
- 35%gone before your first word
02 — Watch
Your agent forgot. Fix it in one plugin.
The full walkthrough: what the gauge reads, when it warns, and what it never does on its own.
03 — The usable window
What the million does not say.
1,000,000
Announced 1,000,000. Usable 250,000. On flash, nano, and lite the factor is 0.25. WATCH and FULL are scored on that, not on the brochure.
On flash, a detected 200,000 nominal window becomes 50,000 usable. The same fill can be 15% of the brochure and 60% of the window the model actually has.
04 — The problem
Without a gauge, context is an invisible tank.
-
35%
already gone before the first word
System prompt, tools, skills, rules. Felt across the community.
-
Existing gauges lie in public.
The wrong maximum, a stale percent after compaction, sometimes over 100%. Six documented bugs, on Cursor and on Hermes.
-
The agent forgets the beginning.
And you only find out afterwards.
Gauges that lie are worse than no gauge. We started there.
The 35% figure is from r/ClaudeAI. Wrong maxima, stale percents, and readings past 100%: Cursor (157527, 159170, 155347) and Hermes (#109760, #72453, #139492).
05 — Context rot
How output quality degrades as context fills up
Schematic of the drop. Quality stays near the top of the window, and it is still high when Hermes Gauge warns at 60%. The curve is the shape, not a benchmark score.
Output quality, 40 to 100. Context window usage, 0 to 100%. Healthy zone through about 42%. Context rot from there to 80%. Auto-compaction from 80%. Hermes Gauge warns at 60%, the WATCH threshold.
06 — Voices
They are living it.
Exact posts. Platform and date as published. Nothing added.
A fresh session loses the way of working, even when it's written down in detail. A long session keeps the way of working but slowly loses old decisions.
Claude just compacted my session and took me from 15% usage to 90%... Almost 80% of my 5-hour limit gone just from compacting context.
After a compaction it would happily suggest the exact thing we'd already ruled out two hours ago, and I'd have to relitigate it.
Hit it to save context space, then 30 minutes later realize I need to reference something that got summarized away.
Even within the same long chat, it sometimes forgets things I literally said a few messages earlier... it keeps losing the thread.
When a chat gets long, it becomes slow and almost unusable. The only option is to start a new chat, but then all context is lost.
The chat gets long. Quality starts dropping. So I opened a new chat. Instantly feels better. But now I've lost everything — the decisions we worked through.
That slow decay is worse than a hard reset. At least with a reset you know where you stand.
Two hours in, we had everything dialed in. Then the context window fills up... It feels like starting over with a stranger who skimmed a one-page summary.
07 — What the plugin does
The reading, not a promise.
Effective window
The ratio follows the model
WATCH and FULL are scored on nominal × factor. flash / nano / lite 0.25 · mini / small / fast 0.40 · haiku / air 0.50 · otherwise 1.0. window_tokens is that effective size.
Arc
A gauge, not an orphan percent
Fill, estimated tokens, tokens left, status. OK under 60%, WATCH from 60 up to 85, FULL from 85. Fill is capped at 100%.
config.yaml
WATCH and FULL are tunable
Defaults 60% and 85%, output reserve 0. The file, the /gauge command, and the Settings panel write the same config.
Alert
A reply, not a ghost button
One push per status crossing. On Telegram, reply 1 (compact + new session), 2 (compact), 3 (new session), or nothing. No second poller. No getUpdates.
/gauge
The full audit
gauge_check, gauge_report, gauge_audit (HEALTHY, WARN, ALERT), peaks, incidents, policy. The audit embeds hermes doctor warnings and does not fix them.
SQLite
Peak history stays
Compaction resets the live counter to zero and the display returns to “—” until the maximum is confirmed. The audit keeps past peaks. Local database, one row per session.
Multi-agent
The weakest link
Several sessions, several agents. The subject adds the contributions. Status follows the smallest window on the subject.
Zero intrusion
No second poller
Eight hooks, after the reply. If a hook misses, gauge_check recomputes on demand. No hook blocks the agent. The shipped mode is audit: it watches and recommends.
What is never invented
Window source on every reading: detected, configured, fallback, or unresolved. The estimate wears “≈”, method (characters // 4) × 2, unless the provider already counted the tokens. Never over 100%. Never a stale percent.
- Does it slow the agent down?
- No. The measurement is passive, after the reply.
- Every model?
- The window is detected. If it cannot be, the gauge shows “—”.
- Does the data leave?
- No. Local SQLite. Nothing is sent.
- Can it be switched off?
- Yes. No blocking hook.
08 — What you get
See. Be warned. Act. Take back control.
See
Know exactly where you stand
The percent on the usable window, the tokens left, and what fills it: conversation, tools, skills, prompt.
gauge_check · breakdown · window_source
Be warned
Before the agent forgets
The alert fires at WATCH, 60% of the usable window. Not at 97%, when it is too late to summarize cleanly.
WATCH / FULL alerts · one send per crossing
Act
One move. “1”
On Telegram, 1 asks to compact then open a session. 2 compacts. 3 opens. Nothing ignores it. Hermes runs the gesture. The plugin does not summarize the thread.
reply 1 / 2 / 3 · /compact · /new
Take back control
No memory blackout
Nothing compacts on its own. After compaction the display returns to “—” until it is confirmed. Peaks stay in the audit, on the machine.
audit mode · post_compaction · peak history
09 — Proof
The bubble, word for word.
gauge_check output. The recommendation is not executed. The reading in the capture is in French.release-review — WATCH
≈60.0 % effectif
fenêtre effective 50 000 · nominale 200 000 · facteur 0.25
source detected · gemini-2.5-flash
breakdown
system_prompt 0
tools 0
skills 0
conversation 30 000
About 20k tokens of headroom left. Finish the current topic
first; avoid starting anything big.
policy_verdict (audit)
60 % effectif, seuil débile 55 % pour ce modèle flash :
recommandé = compacter, puis nouvelle session.
This capture is the WATCH reading. On a crossing, Telegram also asks: reply 1, 2, 3, or nothing. That line is not in the image. The plugin starts nothing by itself.
10 — Install
Three steps.
No API key, no environment variable, no pip. The Python standard library is enough.
-
01 — Install
The plugin attaches to Hermes Agent.
hermes plugins install SidelightAi/hermes-gauge --enable -
02 — See the gauge
In Hermes Desktop the mark sits in the composer bar. The Gauge panel opens on click. This is navigation, not a command.
PathHermes Desktop → Gauge panel
-
03 — Audit
One command for the reading, the report, the peaks, and the policy.
/gauge
11 — Hermes Desktop
Zoom in on the Gauge plugin within Hermes Desktop.
The plugin shows in the composer bar and in a native panel. Three views: Gauge, Audit, Settings. The plugin is the subject. The desktop is the room.
- Segmented gauge. The panel draws the fill next to the percent and the status. The composer repeats the same colors: OK, WATCH, FULL. A click refreshes.
- Settings, dark and light. The panel follows the Hermes Desktop theme. Fields stay readable in both. Thresholds, alert statuses, and the route save into the same
config.yamlas/gauge. - Status in the bar. Percent and status stay visible. Recent history stays in the panel. Compaction resets the live counter to zero. The audit keeps the peaks.
- Med. In the capture, the gauge sits in the composer beside the model name and the Med control. Med belongs to Hermes Desktop. The gauge reads the session next to it.
- Targeted push. Current session, home channel, or one chat (
custom:platform:chat_id). Once per status, then silence until it changes. The capture is set to session, cooldown 30 min, reply reserve 0.
12 — Surfaces
Where the session lives.
The alert follows the session. It is not one more app per network.
Hermes Gauge
Keep the thread.
Cron: the line asks you to open the session and run the command. Nothing is sent before a crossing, and not twice for the same status while it holds. Silent until then.
13 — Story
Hermes Hackathon 2026
At SIDELIGHT, we advise Swiss companies so they save at least 10 hours a week, by shining a light on their business processes with AI.
And of course, we are Hermes maximalists. We use Hermes every day, for ourselves and for our clients. Taking part in this 2026 Hackathon is a real pleasure for us.
Deadline · 11 Nov 2026 · 17:00 ESTMIT · open source
Stay in touch
Nous Research @NousResearch The Hermes Agent Plugin Hackathon starts now! It runs for 7 days, with $20,000 in cash prizes and more. Submissions are due 5PM EST on Nov 11th.
November 4, 2026