All plugins

jwt-ref

@jwt: context references that decode a JSON Web Token for the model: @jwt:<token> (or a quoted "Bearer <token>") attaches the header with the algorithm in words, every claim as JSON, the exp, nbf, iat and auth_time claims in UTC with how long ago or ahead they are, whether the token has expired and its lifetime, and notes on alg none, a missing or empty signature, a header that names its own key (jku, x5u, jwk), crit and duplicate names; encrypted tokens (JWE) show their header only; the TUI and Desktop composer preview a token as you type it. The signature is never verified. Disclosure — reads only the text of the reference itself and the system clock, using Python's base64, json and datetime; no network (no key sets fetched), no files read or written, no subprocess, no credentials read; the plugin keeps no copy of the token, but the @jwt: reference and the decoded header and claims become part of the message sent to your model provider and saved in the session history, so decode only tokens you are willing to share with it; register() only adds the @jwt: reference provider.

olric3015Toolsv1.0.0Updated 29 days ago

About

@jwt: context references that decode a JSON Web Token for the model: @jwt:<token> (or a quoted "Bearer <token>") attaches the header with the algorithm in words, every claim as JSON, the exp, nbf, iat and auth_time claims in UTC with how long ago or ahead they are, whether the token has expired and its lifetime, and notes on alg none, a missing or empty signature, a header that names its own key (jku, x5u, jwk), crit and duplicate names; encrypted tokens (JWE) show their header only; the TUI and Desktop composer preview a token as you type it. The signature is never verified. Disclosure — reads only the text of the reference itself and the system clock, using Python's base64, json and datetime; no network (no key sets fetched), no files read or written, no subprocess, no credentials read; the plugin keeps no copy of the token, but the @jwt: reference and the decoded header and claims become part of the message sent to your model provider and saved in the session history, so decode only tokens you are willing to share with it; register() only adds the @jwt: reference provider.

jwt-ref

@jwt: references for Hermes: put @jwt:eyJhbGciOi... in a message and Hermes replaces it with
the token decoded on your machine: the header with the algorithm in words, every claim, the
time claims (exp, nbf, iat, auth_time) in UTC with how long ago or how far ahead they
are, whether the token has expired and how long it was meant to live, and notes on things worth
a second look.

A JWT in a log line, an Authorization header or a failing API call is unreadable as it
stands, and a model decoding base64url in its head gets claims and dates wrong often enough to
matter. With @jwt: it gets the exact contents, and "is this token expired?" is answered by
the clock instead of a guess.

Install

hermes plugins install jwt-ref --enable

Requires Hermes 0.21.5 or newer. No API key, no configuration, no dependencies.

Use

@jwt:<header>.<payload>.<signature>           a signed token (JWS)
@jwt:"Bearer <token>"                         an Authorization header value, in quotes
@jwt:<header>.<key>.<iv>.<ciphertext>.<tag>   an encrypted token (JWE): its header only

Example, from the end-to-end test (a one-shot hermes chat turn). The message
Why is the API refusing this? @jwt:"Bearer eyJhbGciOiAiUlMyNTYi..." reaches the model as the
message followed by:

JWT, signed (JWS), 3 parts; the signature is NOT verified
Header
  alg (algorithm)  "RS256" = RSA PKCS#1 v1.5 with SHA-256
  typ (type)       "JWT"
  kid (key id)     "k-2026"
Claims
  iss (issuer)     "https://auth.example.com"
  sub (subject)    "user-4821"
  iat (issued at)  1792584101 = 2026-10-21 12:01:41 UTC, 2 hours 5 minutes ago
  exp (expires)    1792587701 = 2026-10-21 13:01:41 UTC, 1 hour 5 minutes ago
Status at 2026-10-21 14:07:07 UTC
  EXPIRED 1 hour 5 minutes ago
  lifetime 1 hour (exp - iat)
Notes
  - signature: 9 bytes, not checked (jwt-ref decodes; it never verifies)
  • Values are shown as JSON, as written in the token (strings in quotes, lists and objects
    inline); a value longer than 200 characters is cut and its length given. At most 60 claims
    are listed and the rest counted.
  • Times are read as seconds since 1970, as the JWT standard says. A time that only makes
    sense in milliseconds is shown as such and flagged, because a server reading it as seconds
    sees a date thousands of years ahead.
  • Status says whether the token has expired, whether nbf lies in the future, whether
    iat does (a clock is off, or the token was made by hand; differences up to a minute are
    ignored), and the lifetime exp - iat.
  • Notes call out alg: none (an unsigned token anyone can write), a missing or empty
    signature, a header that names its own key (jku, x5u, jwk), crit, and names that
    appear twice (JSON keeps the last one, other parsers may not).
  • Encrypted tokens (JWE) show their header; the claims cannot be read without the key.
  • A payload that is not a JSON object is shown as text; when cty is JWT it is itself a
    token, which can go in its own @jwt: reference.

An unsigned token ends in .. Unquoted, Hermes reads that last dot as the end of your
sentence and drops it; jwt-ref still decodes the token and says the signature part is missing.

Errors say what is wrong (a JWT has 3 parts (signed) or 5 parts (encrypted) separated by dots; this has 1) and reach the model under Hermes's context warnings.

Suggestions

In the TUI and the desktop app, @jwt: followed by a token previews it as a suggestion
(alg HS256, sub "1234567890", plus expires in ... or expired ... ago when it has an
exp). The classic CLI does not show reference suggestions.

What it does not do

jwt-ref decodes; it never verifies. It does not check the signature, fetch a key set, or
contact the issuer, so a decoded token says nothing about whether it is genuine. A token
pasted into a message is already sent to your model provider whether or not it is decoded;
the plugin adds only the readable form of what is in it.

Security and footprint

  • register() only registers one context reference provider (@jwt:).
  • It reads nothing but the text of the reference itself and the system clock, and only when you
    write @jwt: in a message.
  • No network access, no subprocesses, no downloads, no credentials read, no files read or
    written. The token is not stored anywhere.
  • Standard library only (base64, json, datetime).

Development

python -m pytest tests                                         # unit tests, no Hermes needed
PYTHONPATH=<hermes checkout> python tests/e2e/jwt_ref_e2e.py   # real hermes chat turns and TUI suggestions
hermes plugins validate jwt-ref

Changes

  • 1.0.0: first release.

MIT licensed.

README from the reviewed commit 9c842d6; it updates when the author re-pins.

More by olric3015

18 plugins by olric3015 in the catalog.

olric3015approval-ledgerLocal ledger of Hermes's approval prompts (dangerous commands, protected writes, MCP consent, smart-mode verdicts): /approval-log shows how often each rule asked, how many prompts were approved, denied or left unanswered, and how long a person took to answer, per rule, per surface or per day, for the last 24 hours, any number of hours or days, the latest session or everything recorded; /approval-log recent lists the newest decisions (ten, or up to 100 with /approval-log recent 50). Disclosure — writes decision metadata (session id, surface, rule label, answer, timings; no command, description or session key) to plugin-data/approval-ledger/approvals.jsonl, trimmed to 5,000 rows past 2 MB; observer only, cannot answer or change an approval; no networkCommunitytoolsolric3015aux-ledgerLocal ledger of Hermes's auxiliary LLM calls (titling, compression, vision, approval): /aux shows tokens, time and failures per task, model, provider or day, or lists the newest calls (ten, or up to 100 with /aux recent 50), for the last 24 hours, any number of hours or days, the latest session or everything recorded. Disclosure — writes auxiliary-call metadata (ids, models, timings, token counts, no prompt or response text) to plugin-data/aux-ledger/calls.jsonl, trimmed to 5,000 rows past 2 MB; no networkCommunitytoolsolric3015b64-ref@b64: context references that decode encoded text for the model: @b64:<value> takes base64 (standard or URL-safe, padded or not), hex (0x48656c6c6f, 48:65:6c, \x48\x65), percent-encoding or a data: URI, told apart by the value's shape or picked with base64:, base64url:, hex: or url:, and attaches what it holds: text as text with control and invisible characters escaped, JSON pretty-printed, gzip and zlib inflated in memory (at most 1 MiB, one layer), and binary named by its format (PNG and GIF with their size, JPEG, PDF, ZIP, ELF, SQLite and more) with a hex dump of its first 128 bytes; notes point out a value that was cut short, padding that is off, a second layer of encoding and a JWT inside; the TUI and Desktop composer preview a value as you type it. Disclosure — reads only the text of the reference itself, using Python's base64, json, urllib.parse and zlib; nothing decoded is run, opened or saved; no network, no files read or written, no subprocess, no credentials read; the plugin keeps no copy of what it decodes, but the @b64: reference and the decoded contents become part of the message sent to your model provider and saved in the session history, so decode only values you are willing to share with it; register() only adds the @b64: reference provider.Communitytoolsolric3015chmod-ref@chmod: context references that explain a file permission mode for the model: @chmod:<mode> takes an octal mode (755, 0755, 4755), ls -l text (-rwsr-xr-x, with the file type letter and a trailing + . or @) or an st_mode as stat and git write it (100644), and attaches both forms, each class's rights in words (directory rights named as such), what setuid, setgid and the sticky bit do and where they are ignored, and notes such as a mode everyone can change, one private to the owner, or a class holding rights the class before it lacks; @chmod:"644 u+x,go-w" applies a symbolic change step by step the way GNU chmod does (u g o a, + - =, r w x X s t, copies like u=g), @chmod:"100644 100755" shows what changes between two modes, and @chmod:"umask 027" shows what new files and directories get; the TUI and Desktop composer preview a mode as you type it. Disclosure — reads only the text of the reference itself, using Python's re; it never looks at a file on disk; no network, no files read or written, no permission changed, no subprocess, no credentials read; the plugin keeps no copy of what you write, but the @chmod: reference and the explanation become part of the message sent to your model provider and saved in the session history; register() only adds the @chmod: reference provider.Communitytools

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section