All plugins

rariflat

Live character reactions for Hermes tool calls; local reliability learning and explainable tool/skill recommendations weighted by task fit, reliability, measured usage-frequency rarity, and repeated-call restraint. The router recommends tools/skills only; it does not dispatch tasks to agents or invoke selected tools. An opt-in failure-streak and repeated-call guard is disabled by default. Tool arguments are inspected in memory for non-secret task tokens and repeat fingerprints; credential-like fields and recognized inline secrets are filtered before learning. No raw arguments or credentials are intentionally persisted. No network requests, telemetry, or subprocesses are initiated by the plugin.

wadezigh96Desktopv2.0.0Updated 2 hours ago

About

Live character reactions for Hermes tool calls; local reliability learning and explainable tool/skill recommendations weighted by task fit, reliability, measured usage-frequency rarity, and repeated-call restraint. The router recommends tools/skills only; it does not dispatch tasks to agents or invoke selected tools. An opt-in failure-streak and repeated-call guard is disabled by default. Tool arguments are inspected in memory for non-secret task tokens and repeat fingerprints; credential-like fields and recognized inline secrets are filtered before learning. No raw arguments or credentials are intentionally persisted. No network requests, telemetry, or subprocesses are initiated by the plugin.

Rariflat 2.0.0

Rariflat adds live status characters, local reliability learning, task-aware tool recommendations, and an opt-in failure-streak / repeated-call guard to Hermes Agent.

It is designed to make tool activity easier to understand, help operators compare tools using observed outcomes, and surface repeated-call or failure patterns without silently taking over agent execution.

Problems Rariflat helps address

| Operational problem | How Rariflat helps | Important limitation |
|---|---|---|
| Tool calls are hard to follow in a busy agent session | Character reactions and an optional Desktop pane show tool activity and outcomes | The pane depends on Hermes Desktop and the supported plugin event bridge |
| Operators do not know which previously used tool may fit a task | rariflat_route ranks observed tool names using task fit, reliability, rarity, and restraint, with measured values and an explanation | It recommends only; it does not dispatch work to agents, call the recommended tool, or guarantee the best result |
| Recommendation scores can be mistaken for certainty | The Desktop decision card shows the top choice, factor scores, and observed call counts; fewer than five calls are labeled as limited history | The threshold is an evidence cue, not a calibrated confidence estimate; new installations have little or no history |
| Reliability is difficult to compare from memory | Local success/use counts and failure streaks provide a lightweight evidence trail | Scores reflect only activity observed since Rariflat was installed and can be reset |
| Repeated identical calls can waste time or tokens | Optional loop detection can block a configured repeated-call pattern | Disabled unless explicitly enabled and configured; tune thresholds for the workflow |
| Repeated failures may cause an agent to retry without noticing a pattern | Optional failure-streak guard can block after a configured number of consecutive failures | Disabled by default; it is a simple guard, not a replacement for application-level retries, budgets, or human review |

How ranking works

The advisory router uses a weighted score:

  • Task fit — 40%: overlap between task tokens and tokens learned from observed tool names and arguments.
  • Reliability — 25%: observed successful calls divided by observed calls, with a neutral 50% starting value for an unseen tool.
  • Rarity — 20%: less frequently used tools receive a higher rarity score.
  • Restraint — 15%: fewer repeated identical calls receive a higher restraint score.

Each recommendation includes the measured factor values, use/repeat counts, and a human-readable reason. The optional Desktop decision card shows the top recommendation and alternatives using aggregate fields only; its route event omits raw task text, tool arguments, and the reason string. It labels tools with fewer than five observed calls as limited history; this is not a statistical confidence claim. New installations have little or no history, so recommendations become more informative as the user works.

Router boundary: rariflat_route returns ranked names of tools observed by its hooks and dispatches_to_agent: false. It does not index installed skills, route a task to another agent, invoke tools, or execute a plan.

Quick start

1. Requirements

  • A working Hermes Agent installation with plugin support.
  • Python available in the Hermes environment.
  • For the optional Desktop pane: a Hermes Desktop build that supports the official plugin SDK and event bridge.

2. Install Rariflat

Until the official catalog PR is accepted and published, install the reviewed source revision directly:

hermes plugins install wadezigh96/rariflat-hermes --ref 911a10bac40ff536115f7485d4bba42186f36e83 --enable

The --ref value is a full immutable 40-character commit SHA for the latest public source revision checked during this audit. The command uses Hermes' documented Git installation flow; --enable skips the enable prompt. Review and accept any dependency-consent prompt shown by Hermes. Before publishing later source changes, update this pin and the catalog PR to the exact pushed commit. After the catalog listing is accepted, users can install by catalog name with hermes plugins install rariflat --enable.

3. Validate the plugin

From the Rariflat plugin directory, run:

python -m pytest -q tests
hermes plugins validate . --install-deps
hermes plugins doctor .

The test suite checks ranking, measured rarity/restraint behavior, safe fingerprinting, guard behavior, and other plugin logic. Validation against an installed Hermes CLI checks compatibility with that installation. A passing unit test suite alone does not prove that a particular Desktop runtime is connected.

4. Start using it

After Hermes loads the plugin:

  • Use the Hermes plugin/tool interface to call rariflat_status and inspect tracked tools and guard status.
  • Call rariflat_route with a task description to receive advisory recommendations.
  • Use the /rariflat command to view local reliability status.
  • Make ordinary tool calls. Rariflat learns from observed pre_tool_call and post_tool_call events; it does not have historical data from before installation.

Example task for the recommendation tool:

{
  "task": "Find the official documentation for Python asyncio and summarize the key usage examples"
}

Example response fields include:

For backward compatibility, router_type and the result key skill retain their historical names; values in skill are names of observed tools, not installed skill-catalog entries.

{
  "router_type": "tool_skill_recommender",
  "dispatches_to_agent": false,
  "best": "web_search",
  "recommended": [
    {
      "skill": "web_search",
      "score": 74.2,
      "task_match_score": 80.0,
      "reliability": 90.0,
      "rarity": 35.0,
      "restraint": 100.0,
      "reason": "..."
    }
  ]
}

The values above are illustrative only; actual results depend on locally observed history.

5. Enable the optional guard only when ready

The guard is off by default. Enable or disable it from the command:

/rariflat guard on
/rariflat guard off

Or configure it before starting Hermes:

export RARIFLAT_GUARD=1
export RARIFLAT_FAIL_STREAK=3
export RARIFLAT_COOLDOWN=30
export RARIFLAT_LOOP_REPEAT=3
export RARIFLAT_LOOP_WINDOW=30
  • RARIFLAT_FAIL_STREAK: consecutive failures before the failure-streak guard blocks (default: 3).
  • RARIFLAT_COOLDOWN: seconds before a failure-streak lockout can recover; 0 resets the streak immediately on the next call (default: 30).
  • RARIFLAT_LOOP_REPEAT: repeated identical calls required for loop protection; 0 disables loop detection (default: 0).
  • RARIFLAT_LOOP_WINDOW: repeated-call observation window in seconds (default: 30).
  • RARIFLAT_LEARN_ARGS=0: disable learning task tokens from tool arguments (default: enabled).
  • RARIFLAT_DATA_DIR: optional directory override for local score storage.
  • RARIFLAT_VERBOSE=1: enable character logs.

The /rariflat guard on/off choice is saved locally and survives restarts; an explicitly set RARIFLAT_GUARD environment variable takes precedence at startup. Start with conservative thresholds and test in a non-critical workflow. The guard is a lightweight safeguard, not a substitute for tool-level permissions, rate limits, idempotency, or operator approval.

6. Optional Desktop pane

The Desktop UI is provided in desktop/plugin.js and listens for the plugin event bridge. It displays the latest tool activity, a short recent history, and a route decision card when rariflat_route is called. The card shows the top recommendation, alternatives, score factors, and evidence counts. It requires a compatible Hermes Desktop runtime; command-line tests of the event contract do not by themselves prove live Desktop integration.

Data handling and reset

  • Scores are stored locally at <active HERMES_HOME>/plugin-data/rariflat/scores.json through Hermes' profile-aware plugin_data_dir() API, unless RARIFLAT_DATA_DIR is set.
  • Tool arguments are inspected in memory to learn non-secret task tokens and build repeated-call fingerprints.
  • Credential-like fields and recognized inline secret patterns are filtered before token learning and fingerprinting. No raw arguments or credentials are intentionally persisted.
  • Set RARIFLAT_LEARN_ARGS=0 to disable argument-token learning; repeated-call fingerprints remain local and continue to exclude recognized credential fields.
  • Rariflat itself does not initiate network requests, telemetry, or subprocess execution.
  • Review your own tool payloads and environment before enabling plugins; pattern-based redaction cannot guarantee detection of every possible secret format.
  • Clear learned scores with:
/rariflat reset

Resetting removes the local learned history, so recommendations start learning again.

Troubleshooting

  • No recommendations: make some ordinary tool calls first; Rariflat needs observed history.
  • Recommendations seem weak: provide a more specific task description and allow more representative calls to accumulate.
  • Guard blocks too often: turn it off with /rariflat guard off, then raise RARIFLAT_FAIL_STREAK or RARIFLAT_LOOP_REPEAT before re-enabling.
  • Desktop pane is empty: confirm your Desktop version supports the plugin SDK/event bridge and that the plugin is loaded. The pane is optional; core CLI/plugin tools can work without it.
  • Validation fails: check the Hermes version, run hermes plugins validate . --install-deps, and inspect the full error output before changing the manifest.

Development and tests

python -m pytest -q tests
node --test tests/desktop_event_contract.test.mjs
git diff --check
hermes plugins validate . --install-deps
hermes plugins doctor .

Run hermes plugins doctor . in the plugin directory for Hermes runtime-contract diagnostics. CI tests and manifest validation are useful checks, but do not replace a manual end-to-end test on the target Hermes Desktop version.

Project scope

Rariflat is an observability, local scoring, recommendation, and optional guard plugin. It is not an autonomous multi-agent dispatcher, does not guarantee performance improvements, and does not replace human oversight.

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