- Add detailed TZ format examples table (IANA and POSIX) - Add Installation section with git clone - Add Verify and Using in other profiles sections - Align format with other plugins (kuri-tool-guard, kuri-skill-gate)
2.8 KiB
hermes-currenttime-hint
Appends an ISO-8601 current-time tag to the user message tail on every Nth
turn (default 5), or after 30 minutes since the last injection — whichever
fires first. Injected via pre_llm_call, ephemeral — never persisted.
<current-time>2026-07-10T18:30:45+08:00</current-time>
How it works
Two independent triggers, whichever fires first wins:
- User-message count — after every 5 user messages, the next one gets a tag. Count resets to 0 after injection.
- Wall-clock interval — 30 minutes after the last injection, the next user message gets a tag regardless of count.
The first message in every session always fires (sentinel).
State is pure in-memory (dict[session_id, _SessionState]). Gateway restart
loses state — acceptable per the spec (miss is harmless). Stale sessions are
evicted after 24 hours; the map caps at 1,024 sessions (LRU).
Timezone
The tag uses the host's system local time by default (Asia/Taipei on this
host). Override with the TZ environment variable — time.tzset() is called
on every injection (Linux only; POSIX).
TZ format examples
| Variable | Result |
|---|---|
| (unset) | System local time |
TZ=Asia/Taipei |
Taiwan (UTC+8) |
TZ=America/New_York |
US Eastern (UTC-5/-4) |
TZ=UTC |
UTC |
TZ=Europe/Berlin |
Central European (UTC+1/+2) |
TZ=CST-8 |
POSIX: CST = 8 hours behind UTC → UTC+8 |
TZ=EST+5EDT |
POSIX: US Eastern with DST |
On glibc systems (Linux) the IANA timezone name with a leading colon also
works (TZ=:Asia/Taipei). This plugin calls time.tzset() before every
injection, so changing TZ at runtime takes effect on the next hit.
Installation
git clone https://git.xlion.tw/xlionjuan/hermes-currenttime-hint.git \
~/.hermes/plugins/hermes-currenttime-hint
Enable
hermes plugins enable hermes-currenttime-hint
Takes effect after a gateway restart (/restart or restart the Hermes
gateway service).
Disable
hermes plugins disable hermes-currenttime-hint
Verify
cd ~/.hermes/plugins/hermes-currenttime-hint
just verify
just verify runs ruff lint and format checks, Bandit, Vulture, ty, and
pytest (21 tests). Run uv sync --group dev once before the first run.
Using in other profiles
mkdir -p ~/.hermes/profiles/<profile>/plugins
ln -s ../../../plugins/hermes-currenttime-hint \
~/.hermes/profiles/<profile>/plugins/hermes-currenttime-hint
hermes plugins --profile <profile> enable hermes-currenttime-hint
Tunables (code-level only)
Edit module constants in __init__.py and restart the gateway:
USER_MESSAGE_INTERVAL— default5TIME_INTERVAL_SECONDS— default1800(30 min)_SESSION_TTL_SECONDS— default86400(24 h)_MAX_TRACKED_SESSIONS— default1024
Author
Shihfu Juan / Kuri