Skip to content

feat(plugins): add on_context_window_update hook for context pressure events #8643

@charleneleong-ai

Description

@charleneleong-ai

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:

  1. Poll state via _get_status_bar_snapshot() (no public API for this)
  2. 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()

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Low — cosmetic, nice to havecomp/cliCLI entry point, hermes_cli/, setup wizardcomp/pluginsPlugin system and bundled pluginstype/featureNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions