kerpopule/hermes-jev-skills

What it is

Hermes Jev Skills is a collection of plug‑ins and skill definitions that let the Hermes AI‑agent (and compatible agents such as Claude Code or Codex) off‑load cheap, fast “decision‑making” work to Jev, a TypeSafe decision‑model service. Jev never generates prose – it only answers structured questions (pick one, score, yes/no) with a calibrated confidence. The repository wires those answers into a range of agent tasks (model routing, search ranking, mailbox sorting, web‑screening, turn‑selection, etc.) so the expensive LLM only does the heavy‑weight writing.

---

Core ideas

Concept	What Jev does	Typical cost
Model routing	Choose the cheapest model that can handle the current turn.	~0.4 s per turn
Search ranking	Rank fetched results, decide if a query needs to be refined, and check if evidence answers the question.	~1.9 s per round
Skill selection	Pick one of 377 installed “skills” (e.g., memory filtering, web‑screening, triage).	~2.8 s
Mailbox sorting	Classify incoming email into lanes (reply‑needed, promotional, spam, …).	~0.44 s, $0.00002 per message
Turn compaction	Decide which transcript turns to keep when the context must be trimmed.	71 turns in 0.95 s
Computer / Browser use	Choose the next GUI or page action from a pre‑approved table.	~0.4‑0.5 s
Web screening	Detect hidden instructions in web‑search results and hide them from the LLM.	~0.2 s per result

All decisions are made via short API calls to the Jev cloud service; the repository supplies the question‑templates, skill files (SKILL.md), and a command‑line tool (jev) that integrates with Hermes.

---

How to get started

# Clone and run the bundled installer (Python 3.9+)
git clone https://github.com/kerpopule/hermes-jev-skills ~/hermes-jev-skills && \
python3 ~/hermes-jev-skills/install.py

# Register your TypeSafe API key (one‑time local page)
jev setup-key   # opens a local page; paste the key, then run `jev doctor`

The installer detects any Hermes, Claude Code or Codex installations on the machine and adds the appropriate plug‑ins and lane sub‑agents. You can preview what would happen with python3 install.py --check or remove everything with --uninstall.

---

Typical workflow

1. Shadow mode – run /jev routing shadow to let Jev make decisions and log them without actually switching models. This lets you verify cost and accuracy first.
2. Turn on routing – /jev routing on to let Jev pick the model for each turn.
3. Enable skills – /jev skills on to have Jev suggest the right skill (e.g., memory filter, web screen) for each turn.
4. Optional screens – /jev screen on to automatically withhold suspicious web‑search chunks.
5. Monitor – /jev dashboard opens a web UI showing pools, confidence scores, latency, and per‑decision logs.

All commands are slash‑commands that the Hermes agent understands; they map to the public plug‑in hooks (pre_llm_call, transform_tool_result, etc.) so Hermes upgrades won’t break the integration.

---

Safety & privacy

• Zero‑exposure of raw data – before any request leaves the machine the payload is redacted (personal identifiers, credentials, long text) and only coarse features are sent.
• Fail‑open design – if Jev is unavailable, the agent falls back to the current model, keeps the existing memory list, and never blocks a turn.
• Risk‑word guards – certain high‑risk terms (payment, legal, delete, …) are never routed to the cheapest tier.
• Local key storage – jev setup-key stores the TypeSafe key in the OS secret store (Keychain, secret-tool, or a 0600 file) and never passes it to the agent process.

---

Repository layout

jevkit/            # core library and the `jev` CLI (standard library only)
skills/            # 13 SKILL.md files, agent‑agnostic decision specs
hermes/plugin/     # Hermes plug‑in that hooks into the agent lifecycle
router-dashboard/  # HTML/JS dashboard for live decision monitoring
install.py         # installer / uninstaller script
tests/             # offline tests with mocked Jev responses
scripts/           # demo home generator, nightly PR report, release gate
evals/             # measurement scripts you can rerun on your own sessions
docs/              # detailed integration notes, safety guides, design choices

Key docs to read first:

• turning-a-jev-feature-on.md – how to enable features safely.
• using-jev-in-a-hermes-fleet.md – operating Jev across multiple agents.
• writing-a-jev-question.md – crafting effective structured questions for Jev.

---

Who might use this

• Developers building autonomous agents that need to keep token costs low while still making intelligent routing, triage, and tool‑selection decisions.
• Ops teams managing fleets of Hermes agents who want a centralized, auditable decision service.
• Researchers interested in measuring the trade‑off between cheap decision models and expensive LLM output.

---

Bottom line

Hermes Jev Skills turns a cheap, fast decision‑API into a practical “second brain” for AI agents, handling everything from model selection to mailbox classification while keeping user data on‑device and providing extensive safety nets.