Feature Request: on_context_window_update plugin hook
Summary
Add an on_context_window_update plugin hook that fires whenever the
context window usage changes significantly, allowing plugins to react
to context pressure (warn, compress, log) without polling.
Motivation
Currently there is no event-driven way for a plugin to know when context
usage crosses a threshold (e.g. 50%, 80%, 90%). Plugins that want to
react to context pressure must either:
- Poll state via
_get_status_bar_snapshot() (no public API for this)
- Patch
cli.py directly (breaks on updates)
Common use cases that need this:
- Auto-compact above 80%
- Warn user at 90% ("consider /reset or /compress")
- Log context milestones for debugging
Proposed API
# Hook: on_context_window_update
# Called when context usage crosses a 5% threshold (debounced).
# snapshot matches the status bar snapshot dict.
#
# Example:
# def setup(ctx):
# ctx.register_hook("on_context_window_update", my_handler)
#
# def my_handler(snapshot: dict, previous_percent: int) -> None:
# if snapshot["context_percent"] >= 90:
# print("⚠️ Context at 90% — consider /compress")
In cli.py, after each API response updates context usage:
prev = getattr(self, '_last_ctx_pct', 0)
curr = snapshot["context_percent"] or 0
if abs(curr - prev) >= 5:
invoke_hook("on_context_window_update",
snapshot=snapshot, previous_percent=prev)
self._last_ctx_pct = curr
Threshold / Debounce
Fire only when usage changes by ≥5% to avoid hook spam on every token.
Optionally expose a config key:
plugin_hooks:
context_update_threshold_pct: 5 # default
Use Cases
- Auto-warn at 80%:
"⚠️ Context 80% full — type /compress to continue"
- Auto-compress at 90% (if user opted in via config)
- Save context milestone snapshots to
~/.hermes/logs/
- Surface in terminal tab title (complement to
on_status_bar_render)
Related
on_status_bar_render feature request (companion to this)
- Context compressor:
agent/context_compressor.py
- Status bar snapshot:
cli.py:_get_status_bar_snapshot()
Feature Request: on_context_window_update plugin hook
Summary
Add an
on_context_window_updateplugin hook that fires whenever thecontext window usage changes significantly, allowing plugins to react
to context pressure (warn, compress, log) without polling.
Motivation
Currently there is no event-driven way for a plugin to know when context
usage crosses a threshold (e.g. 50%, 80%, 90%). Plugins that want to
react to context pressure must either:
_get_status_bar_snapshot()(no public API for this)cli.pydirectly (breaks on updates)Common use cases that need this:
Proposed API
In
cli.py, after each API response updates context usage:Threshold / Debounce
Fire only when usage changes by ≥5% to avoid hook spam on every token.
Optionally expose a config key:
Use Cases
"⚠️ Context 80% full — type /compress to continue"~/.hermes/logs/on_status_bar_render)Related
on_status_bar_renderfeature request (companion to this)agent/context_compressor.pycli.py:_get_status_bar_snapshot()