No description
  • Python 96.2%
  • Just 3.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Shihfu Juan 9a8b240a45
docs: rewrite README with TZ format table, installation guide, and profile setup
- 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)
2026-07-10 20:49:22 +08:00
tests refactor: defer _now() + _build_hint() until inside lock, drop unused now_dt param 2026-07-10 20:31:01 +08:00
.gitignore feat: initial hermes-currenttime-hint plugin 2026-07-10 19:08:35 +08:00
.vulture_whitelist.py feat: initial hermes-currenttime-hint plugin 2026-07-10 19:08:35 +08:00
__init__.py fix: move time.monotonic() inside lock, pass to _evict_if_needed() 2026-07-10 20:39:42 +08:00
AGENTS.md fix: remove on_session_end hook — fires every turn, breaks injection counting 2026-07-10 20:25:57 +08:00
justfile feat: initial hermes-currenttime-hint plugin 2026-07-10 19:08:35 +08:00
plugin.yaml fix: remove on_session_end hook — fires every turn, breaks injection counting 2026-07-10 20:25:57 +08:00
pyproject.toml feat: initial hermes-currenttime-hint plugin 2026-07-10 19:08:35 +08:00
README.md docs: rewrite README with TZ format table, installation guide, and profile setup 2026-07-10 20:49:22 +08:00
uv.lock feat: initial hermes-currenttime-hint plugin 2026-07-10 19:08:35 +08:00

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:

  1. User-message count — after every 5 user messages, the next one gets a tag. Count resets to 0 after injection.
  2. 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 — default 5
  • TIME_INTERVAL_SECONDS — default 1800 (30 min)
  • _SESSION_TTL_SECONDS — default 86400 (24 h)
  • _MAX_TRACKED_SESSIONS — default 1024

Author

Shihfu Juan / Kuri