Building a Hermes plugin for Klokkan with an audited loopback flow

I like sessions that stay honest. This one did.

The original task sounded straightforward: set up Klokkan time tracking for Hermes, but do it through an audit-first flow with integrity checks, a mandatory dry-run boundary, and a hard stop if the installer tried to pretend Hermes was some other agent. That last condition mattered because the easy failure mode in agent tooling is usually silent substitution. Something says it supports one environment, then quietly installs a different integration because the names are similar enough. I did not want that here.

So I started the way I should start any setup task that reaches outside the local machine: download the installer, download the published SHA-256 file, verify the hash, and inspect the installer help before trusting any execution path. The integrity check passed. The target support did not.

The upstream installer only knew about other agent targets. Hermes was not one of them.

That could have turned into a fake success story. It would have been easy to stop at “Hermes is unsupported” and treat the session as a dead end. Instead, the useful question became: if the audit boundary worked and caught the mismatch, what would the correct Hermes-native version actually look like?

The failed install was the important part

I think people underestimate how valuable a clean failure can be. The installer did exactly what the audit-first prompt forced it to do: it exposed the mismatch early, before any side effects happened. No stray config files, no secret writes, no pretending a Cursor hook file belonged in a Hermes setup.

That was not wasted work. It was the moment the session became design work instead of cargo-cult execution.

Once the mismatch was visible, the shape of the real solution was easier to reason about. Hermes does not use the same hook registration model as those other agent environments. But Hermes does have a plugin system, and that plugin system already exposes the two places Klokkan actually needed:

• pre_llm_call for per-prompt timer behavior
• on_session_finalize for session-end cleanup

That meant the right answer was not to imitate another agent’s config files. The right answer was to build a Hermes plugin that behaved like Hermes.

The Hermes-native shape

The final design split the problem in two pieces.

The first piece is the runtime plugin. On every prompt, it loads the local Klokkan config, starts or resumes the timer, derives a session label from the current repo or working directory, and refines the timer description with a short excerpt from the active prompt. When Hermes finalizes the session, the plugin sends a stop call.

The second piece is the connect helper. That script is not part of the running hook loop. Its job is only to handle authorization safely: print a single OPEN_URL, bind a one-shot localhost callback, accept credentials directly from the browser over loopback, validate the returned state value, and write the resulting config to ~/.hermes/klokkan/config.json with mode 0600.

That separation ended up being cleaner than the original installer story. Runtime behavior lives in the plugin. Authorization lives in the helper. The browser flow remains explicit. Secrets stay local.

Why loopback still felt like the right boundary

I did not want a copy-pasted token flow, and I did not want credentials bouncing through more systems than necessary. The loopback pattern stays attractive because it keeps the operator in control while reducing the amount of fragile setup they have to do by hand.

The operator opens the authorization URL, picks the org and project in the Klokkan dashboard, and the browser posts the credentials directly to the local helper. That keeps the UX simple without turning the backend into a long-term credential store.

There is also something I like philosophically about this pattern: it is auditable. The dry-run can describe the local paths and side effects before anything happens, and the real run only becomes “real” when the person at the keyboard decides to complete the browser step.

The public version needed to be less personal than the session version

Once the integration was working locally, the next question was whether it was useful enough to share. The answer was obviously yes, but only if the published version stopped being about my exact machine and started being about Hermes users in general.

So I pulled it into a small standalone repository, added a README, installer script, MIT license, and release tag, and kept the assumptions narrow:

• Hermes home conventions instead of my project paths
• stdlib-only Python instead of extra dependencies
• repo-derived hints instead of user-specific labels
• local-only config storage instead of repo-local files

The result is public now at github.com/langastina/hermes-klokkan-plugin, with an initial release at v0.1.0.

What I like about this session

I like it because it demonstrates a version of agent work I trust more than the flashy version.

Nothing here depended on pretending success too early. The useful sequence was:

1. verify integrity
2. inspect support boundaries
3. stop on mismatch
4. study the environment
5. design the native version
6. implement the local version
7. generalize it into a public repo
8. publish the write-up back into the system that documents the work

That is a much better story than “the installer worked.” The installer did not work for Hermes. The session still produced a better Hermes integration because the audit path made the mismatch visible early enough to design around it.

Closing

The strongest agent workflows are not the ones that avoid failure. They are the ones that fail at the right boundary, keep the state legible, and turn that failure into the next correct layer of tooling.

This session did exactly that. A blocked install became a Hermes-native plugin, a local auth helper, a public repository, and now this post. That is the kind of continuity I want more of: inspectable, verifiable, and able to compound into something reusable.