Hermes Agentic Workflow Debugger

A local flight recorder and debugger for Hermes Agent workflows. It scans a profile without changing it, reconstructs the execution chain from the evidence already there, and turns a vague "the cron failed" into a bounded debugging surface: this run, this step, this error, these inputs and outputs, and this definition change.

The code, local setup instructions, and schema live in agentflow-health.

The dashboard starts with a selected workflow run. The graph stays tied to that evidence, and uncertainty stays visible instead of being flattened into a confident-looking diagram.

Why this exists

Agent automation gets hard to reason about long before it gets large. One workflow can cross a cron definition, a skill prompt, a preflight script, a JSON state file, a generated document, and a publish target. When the final step fails, the useful context is usually scattered across all of those places.

I built this because "the cron failed" is not a diagnosis. I wanted one place to see what actually ran, what it depended on, what it produced, where it stopped, what last worked, and which file or contract deserved attention next.

What it actually shows

• A run-first work surface. Pick a workflow run and see the failing process, exact error, relevant step trace, I/O, last-known-good baseline, and next debugging action before you start wandering through the graph.
• A pipeline graph with honest labels. Processes and data nodes are connected by evidence. Artifact-backed handoffs are linked; time-ordered but unproven handoffs remain assumed; unresolved, partial, and never-run states stay explicit.
• History assembled from the evidence Hermes already leaves behind. The scanner reads structured run records, session files, cron output, and cron state, preserves the source of each run, and uses richer records when the same execution appears in more than one place.
• Definition drift in context. Prompts and scripts are hashed on each scan, so a broken run can be compared with the version that last worked. An optional change summary runs only on demand, after redaction; nothing calls an LLM in the background.
• A safer path from observation to a maintained workflow definition. The scaffolder can prepare a strict JSON proposal and show its provenance and diff; replacing a confirmed definition also requires an explicit fresh digest.
• Keyboard triage and local-first privacy. The graph is navigable by keyboard. The scanner is read-only against the Hermes profile, the dashboard binds to 127.0.0.1, raw sessions remain in place, and derived traces are redacted before storage, export, or an optional AI summary.

The trust boundary

Hermes profile (read-only)
        ↓
Python scanner
  evidence, lineage, redaction, versioning
        ↓
Versioned JSON manifests and snapshots
        ↓
Local React dashboard: workflow runs first, graph second

The Python CLI is the only writer of the derived store. The dashboard reads generated manifests and can ask the CLI to rescan or summarize a redacted diff; it does not rediscover Hermes internals or write to the profile itself. That keeps the dashboard from becoming a second, conflicting source of truth.

Constraints I would not compromise

Observation must not become another source of risk. The debugger does not modify the profile it is trying to explain. Raw transcripts stay outside the derived store and out of static reports.

A graph cannot claim causality it has not earned. Two jobs sharing a path may be related, but it does not prove a handoff. The interface keeps linked, assumed, unresolved, partial, and never-run states separate.

Old automation should remain debuggable. New run records offer rich step-level evidence, but the scanner can still learn from legacy cron output and session files. A team should not have to rewrite a workflow before it can understand why it failed.

Try it locally

The project is clone-and-run today, not a hosted service:

git clone https://github.com/patrickluvsoj/agentflow-health.git
cd agentflow-health
make setup

uv run agentflow-health doctor --profile ~/.hermes/profiles/daily
uv run agentflow-health scan --profile ~/.hermes/profiles/daily
uv run agentflow-health serve --open

The README has the full command reference, strict workflow-definition format, and contributor notes.

Verification

At the latest product release gate, the canonical suite passed 158 Python tests and 24 dashboard Vitest tests, followed by a production dashboard build and generated-type-drift verification. The Release 3 path also exercised read-only real-profile dry-runs and an isolated dashboard browser run. The derived store was checked for redacted evidence rather than private session content.

What I learned

Agent reliability is an evidence problem before it is an alerting problem. A notification can tell you something failed. A useful debugger shows the runtime chain, the uncertainty in that chain, and the smallest credible next step.

That is the direction for Agentflow Health: operational memory for workflows that are still being built, changed, and occasionally broken, rather than a dashboard that simply claims everything is healthy.

Next

• Make confirmed workflow definitions easier to review and edit from the dashboard.
• Extend the debugger to intra-session pipelines and modern Hermes evidence only after their public contracts are stable.
• Track reliability trends and regressions over time, not just the newest failure.
• Package the local tool after the interface has been tested against more real workflows.