Hermes Workflows

Agent-owned workflow graphs for Hermes Agent. Your agent authors a JSON graph of agent nodes, fan-outs and gates; a background runner executes it outside the caller process tree and hands results back through the same workflow tool it launched from. Hermes Desktop draws the live DAG.

Why this exists

A single agent turn is one long, fragile thread of work: one context, one timeout, no resumable checkpoints. A graph splits the job into nodes with explicit dependencies — parallel recon lanes, a synthesis join, an adversarial review gate — each node a separate child session with its own model, budget, and typed failure. When something dies or you change your mind mid-flight, only the affected nodes re-run: completed work is replayed from its stored fingerprint, not re-paid.

What you get

Offline checkout drift probe

Run python3 scripts/drift_check.py --repo /path/to/checkout on demand (the script’s checkout is the default). No fetch, network refresh, daemon, or cron. upstream_latest means the nearest reachable local release tag selected by git describe --tags, not proof of the remote’s newest release. The final stdout line reports installed_version, upstream_latest, local_only_commits, trailers_missing, and verdict; unknown error counts stay unknown.

Exit 0 means clean; exit 1 means drift (version_mismatch, trailers_missing, then local_only, in that precedence). Commits after the tag need (est-…) or #NN tracker references in their messages. Exit 2 means error, including an absent installed-version changelog heading, missing tag, or unreadable git state. The probe only reads plugin.yaml, CHANGELOG.md, and git describe/rev-list/log.

The workflow tool

One tool, action-routed — the complete surface, with the flags that matter:

Plus a /wf slash command: bare /wf lists the library; /wf [note] launches that graph with the note as its context seed. /wf show (or workflow {"action":"library","name":""}) returns required inputs and an instantiate command. Library-sourced launches require nonempty string bindings for every {run.KEY} on the shared text surface, including echo output, gate options and machine argv; surviving refs refuse before any write. Inline graphs retain their existing behavior, including refusing unbound machine argv.

Optional save params:{KEY:{desc,default}} stores descriptive meta.params in the envelope. Required keys derive from graph refs, not this declaration; defaults are suggestions in the instantiate command, never automatic launch bindings. Omission retains params on overwrite; {} clears them deliberately. Missing or dead declarations on an envelope save produce non-fatal s12 save warnings naming the keys; a bare save’s contract derives wholly from refs. Bare, ref-free library rows and clean save responses keep their previous key sets.

Graph grammar in 30 seconds

Four node types — agent, gate, echo, join — and a closed key set per type (anything outside it is refused at submit with a per-defect error list, never silently ignored). The smallest useful graph:

{ "name": "check",
  "nodes": [{ "id": "inspect", "type": "agent",
              "goal": "Inspect the target. Return one fenced JSON object." }] }

workflow { "action": "run",  "graph":  }   → run_id
workflow { "action": "wait", "run_id": "" }          → repeat until terminal

Fan-out with quorum, gates with when/on_skip/wait, requires output preconditions, after_partial harvest release, inputs selection from upstream output, string-field enums, answer-schema floors minItems (on type:"array") and minLength (on type:"string", counted on stripped chars — a whitespace-only string is too short), graph-level defaults (precedence: explicit node key > shape preset > defaults) and model_policy — the authoritative vocabulary is references/grammar.md; the bundled authoring skill keeps a compressed working copy in SKILL.md. Runnable templates in examples/, grouped by role — basics/ (one idea each), build/ (fan-out and ledgers), review/ (independent judgment), release/ (issue→PR, release lifecycle, gates and watchers), ops/ (incidents). examples/README.md is the map: one line per template, what it teaches, and which arm its receipts proved.

What a run leaves behind

Each run is a directory (~/.hermes/workflows// by default): the committed graph.json, an append-only events.jsonl typed event log, per-node results under nodes/, prompts and logs under logs/, gate answers under gates/, and a summary.md. Resume, amend, and the desktop all read the same shared state. There is no hidden control plane and no daemon: exactly one runner process per run, admitted by a kernel lock, spawned outside the caller’s process tree. Run states (running, held, interrupted, done, failed, stopped), owner wake semantics, silent-runner reaping, and recovery procedures: references/operations.md.

Install

hermes plugins install hermes-workflows      # from the catalog (pinned SHA)
hermes plugins enable hermes-workflows

Restart the backend (hermes serve) so the tool and dashboard routes mount. Before disabling or removing the plugin, stop live runs: use workflow {"action":"list"} to find their run IDs, then workflow {"action":"stop","run_id":""} for each. Detached runners can outlive a session, gateway restart, or plugin disable until a boundary; disabling alone does not stop them. Desktop gate answers use the SDK to send a visible resume turn to the run owner’s chat; older Desktop builds insert text for you to send, or ask you to type workflow wait in that owner chat. If Hermes Desktop runs on a different machine than the backend, copy desktop/plugin.js to that machine’s ~/.hermes/desktop-plugins/hermes-workflows/plugin.js — the app hot-loads it. Manual/zip install and removal: INSTALL.md.

Two builds, one codebase

The plugin needs no patched Hermes. Every child spawn rides the stock quiet one-shot CLI contract, and every install runs the same code. Exactly one field differs, and it is optional:

The tier is self-reported: after a failed child, status shows turn_report: typed or untyped, so you always know which build you’re on. When upstream PR #121041 lands, the branch collapses and that doc deletes itself.

Requirements

• Hermes Agent ≥ v2026.9.21 (package version 0.21.4) — measured stock -Q CLI and quiet turn-report contract; see docs/catalog/pr-body.md. Older 0.21.3 deployments are below this declared floor and will skip plugin admission.
• Python 3 (stdlib only — the plugin imports nothing outside Hermes)
• Node for the desktop half’s tests only; the app loads plugin.js uncompiled

Starter set: run something today (general/)

You don’t have to author a graph first. Five scrubbed, estate-neutral starter graphs ship with the plugin under library/general/, so a fresh install can run a real DAG out of the box:

{ "task": {"from": "general/report-and-verify"} }

Resolution order for from: general/: your runs-root library first (/library/general/.json), legacy launch root second, the packaged set last. Every graph routes agents through model tiers (worker/manager) — none names a vendor model — and each declares its seed params in meta.params.

Customize: copy a packaged JSON to your own shelf (or tune it and save name=general/); your copy shadows the packaged one at the same address, and the door never writes the packaged files. Share back: tuned graphs are welcome upstream — see the submit flow in issue #50 (“share your tuned graph back”): fork, drop the envelope under library/general/, run the scrub gate, open a PR. Per-graph author notes live in library/general/README.md.

For agents and contributors

AGENTS.md is the front door: repo map, operate/contribute procedures, and the rules that keep the tree publishable. Changes are gated by the serial suite (python3 scripts/suite.py . ci-out) and hermes plugins validate . — both run in CI.

graphify is an OPTIONAL local navigation aid — graphify query "" beats a grep dump. Its output is never committed and CI never builds it; source and tests are the spec.

License

MIT — see LICENSE.