Hermes Workflows

Code-first durable workflows for agent work that should not disappear into chat history. Hermes Workflows gives Python projects persistent workflow state, typed agent work, typed human review, a resident Workflow Worker, and inspectable receipts for restarts, approvals, retries, and handoffs.

Affiliation disclaimer: Hermes Workflows is an independent project by Skylar Payne. It is not affiliated with, endorsed by, sponsored by, or officially connected to Nous Research or the Nous Research Hermes Agent project.

The launch-facing SDK is intentionally small:

from hermes_workflows import agent, ask, bash, goal, parallel, pipeline, workflow

Use agent(...) for typed AI/worker work, ask(...) for typed human or external review, bash(...) for deterministic durable shell commands, parallel(...) / pipeline(...) for fan-out and staged item work, and goal(...) for bounded improve-until-accepted loops.

Start here

Author workflows Learn the public SDK: workflow, agent, ask, bash, parallel, pipeline, and goal.
Setup guide Install from source, create a registry, run a workflow, start the Workflow Worker, and reach the Review Queue.
Hermes dashboard plugin Configure the Review Queue dashboard, DB aliases, workflow catalog entries, and trusted approval actions.
Architecture Domain model, runtime loop, extension seams, execution environments, and failure modes.
Inspectability cookbook Commands for status, event history, outbox, approvals, failed commands, and recovery.
Runtime boundary What belongs in durable workflow state versus prompts, skills, subagents, and operators.

Dashboard preview

Sanitized screenshot of the Hermes Workflows dashboard overview with run counts, Review Queue status, and recent workflow runs. — Sanitized example dashboard overview. The live dashboard uses configured workflow DB aliases so the CLI, worker, and Review Queue read the same state.

Runtime model in one pass

operator starts/replays workflow
  hermes-workflows run <alias-or-ref> --config .hermes/workflows.registry.json --id <id>
    -> durable workflow activation is recorded
    -> missing workflow/step/agent/child work is queued
    -> command exits after current durable state is stored

resident Workflow Worker
  hermes-workflows worker --config .hermes/workflows.registry.json
    -> leases queued commands from configured DBs
    -> executes step/agent/child work through configured runners
    -> replays the workflow against the same DB/run id
    -> stops at Review Queue requests, approvals, or terminal state

review surface
    -> dashboard/chat/CLI records typed human input or approval with provenance
    -> the worker observes the durable transition and continues

The CLI, worker, and dashboard must point at the same configured workflow DB. If they do not, the dashboard may look empty while work is waiting somewhere else.

Design archive

These implementation/design records are useful for contributors, but they are not required for the launch quickstart.

Site build

GitHub Pages builds the repository with Jekyll from main. The committed layout adds navigation and client-side Mermaid rendering for architecture diagrams.