All plugins

b64-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.

olric3015Toolsv1.0.0Updated 27 days ago

About

@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.

b64-ref

@b64: references for Hermes: put @b64:SGVsbG8= in a message and Hermes replaces it with what
the value holds, decoded on your machine: text as text, JSON pretty-printed, gzip and zlib
inflated, and anything else named by its format (a PNG with its size, a ZIP, a PDF, an ELF ...)
with a hex dump of its first bytes.

Base64 turns up everywhere: Kubernetes secrets, Authorization: Basic headers, data URIs,
message queue payloads, compressed log fields. A model decoding it in its head gets bytes wrong
often enough to matter, and cannot inflate gzip at all. With @b64: it gets the exact contents.

Install

hermes plugins install b64-ref --enable

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

Use

@b64:SGVsbG8sIHdvcmxkIQ==          base64 (standard or URL-safe, padded or not)
@b64:48656c6c6f                    hex (also 0x48656c6c6f, 48:65:6c:6c:6f, \x48\x65...)
@b64:caf%C3%A9%20au%20lait         percent-encoding
@b64:data:image/png;base64,iVBO... a data: URI
@b64:base64:<value>                pick the encoding: base64:, base64url:, hex: or url:
@b64:"SGVs bG8s IHdv cmxk IQ=="    a value with spaces or line wrapping, in quotes

The encoding is told by the value's shape: a %XX sequence means percent-encoding, a value made
only of hex digit pairs (or starting with 0x) means hex, and the base64 alphabets cover the
rest. A value that fits both hex and base64 is read as hex, with a note saying how to read it
as base64 instead.

Example, from the end-to-end test (a one-shot hermes chat turn). The message
What happened here? @b64:H4sIAAAAAAAC/6tWSi1LzStRslJQSkktyMmvVNJRUMrPBvLTEnOKU2sBCu+5NiAAAAA=.
reaches the model as the message followed by:

base64: 67 characters -> 50 bytes
Content: gzip data, inflates to 32 bytes
Inflated: JSON object, 2 keys
JSON
  {
    "event": "deploy",
    "ok": false
  }
  • Text is shown as is, up to 3,000 characters and 60 lines (the rest is counted). Control
    and invisible characters (a zero-width space, a bell) are shown as \x07 / \u200b so they
    cannot hide in plain sight. UTF-8 and UTF-16 byte order marks are recognised.
  • JSON objects and arrays are pretty-printed.
  • gzip and zlib are inflated in memory, at most 1 MiB, one layer deep, and what they held is
    described the same way.
  • Binary is named when its first bytes give it away (PNG and GIF with their size, JPEG, WebP,
    PDF with its version, ZIP, gzip, bzip2, xz, zstd, 7-Zip, ELF, Mach-O, Windows PE, Java class,
    WebAssembly, SQLite, DER, Ogg, MP3, WAV, MP4) and shown as a hex dump of its first 128 bytes.
  • Notes call out a value that was cut short or edited (its last character carries bits that
    decoding drops), padding that is off, text that is base64 or percent-encoded again (decode it
    with another @b64:), and a JWT inside (decode it with @jwt: from jwt-ref).

Errors say what is wrong ('=' may only appear at the end of base64, as padding, base64 cannot be 5 characters long (one character is left over); it was probably cut short) and reach
the model under Hermes's context warnings. Values longer than 65,536 characters are refused.

Suggestions

In the TUI and the desktop app, @b64: followed by a value previews it as a suggestion
(base64 -> 13 bytes, text "Hello, world!"). The classic CLI does not show reference suggestions.

What it does not do

b64-ref decodes; it never runs, opens or saves what it decodes, and it does not decrypt anything.
It does not follow a URL in the decoded text.

Security and footprint

  • register() only registers one context reference provider (@b64:).
  • It reads nothing but the text of the reference itself, and only when you write @b64: in a
    message.
  • No network access, no subprocesses, no downloads, no credentials read, no files read or
    written. 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. Base64 often hides a secret (a Kubernetes secret, a Basic auth header): decode it only
    where you would paste the secret itself.
  • Standard library only (base64, json, urllib.parse, zlib).

Development

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

Changes

  • 1.0.0: first release.

MIT licensed.

README from the reviewed commit 89b1572; 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 networkCommunitytoolsolric3015chmod-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.Communitytoolsolric3015command-ledgerLocal ledger of the slash commands you run in Hermes (built-in commands in the CLI, built-in and plugin commands on messaging platforms): /command-log shows how often each command was used, its share, in how many sessions and when last, per command, platform, surface or day, for the last 24 hours, any number of hours or days, the latest session or everything recorded; /command-log recent lists the newest commands (ten, or up to 100 with /command-log recent 50) with the alias typed. Disclosure — writes command metadata (command name, alias typed, surface, platform, a 12-digit hash of the session key; no arguments, session key or user id) to plugin-data/command-ledger/commands.jsonl, trimmed to 5,000 rows past 2 MB; observer only, cannot block or change a command; no networkCommunitytools

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section