handflow

Handflow — a Manus-style planning flow, native to Hermes

The agent writes a step plan before it starts working, marks each step
in_progress / completed / blocked with a one-line note as it goes, and
replans mid-flight. You watch the same plan in a dockable desktop pane and can
nudge it with a click.

One stdlib-only tool (handflow), one right-rail pane, three backend routes,
plan state as plain JSON under $HERMES_HOME/handflow/. No model calls of its
own, no network, no vendored runtime, nothing to keep up to date.

HAND FLOW                                  1 blocked  [active]
Ship the catalog entry
───────────────────────────────────────────────●──────  2/5
 01  write the entry                    [✓]
 02  pin the commit sha                 [✓]
 03  open the PR to plugin-catalog      [→]   note: draft pushed
 04  wait on the merged sha             [!]
 05  announce it                        [ ]
plan_1789888793_9y8q                           12s ago

Why

Autonomous work that is watchable beats autonomous work you have to trust.
OpenManus (MIT) popularised the planning-flow shape — a plan the agent rewrites
as it executes, with statuses and notes on every step. Hermes already has the
model, the tools and the delegation; what it lacked was that shared, visible
plan. Handflow is that piece, written from scratch as a Hermes plugin: the
planning-flow semantics are ported from OpenManus's PlanningFlow, the
implementation and the pane are ours.

Install

Inside Hermes:

hermes plugins install handflow          # from the catalog
hermes plugins enable handflow           # user plugins are opt-in

From a checkout:

git clone https://github.com/DECRUX9812/hermes-handflow
hermes plugins install --path ./hermes-handflow
hermes plugins enable handflow

Then restart the desktop app: the Plan pane appears in the right rail and
the ▤ n/m chip in the status bar. State lives in
$HERMES_HOME/handflow/plans/*.json (override the directory with
HANDFLOW_HOME); it is per-profile, and deleting the folder just forgets plans.

Using it

The agent drives it. Ask for anything with more than a couple of steps and it
should call the tool first:

you: port the price parser to the new adapter and prove it on last week's data

agent: (handflow start — goal + 5 steps) → works → (handflow complete 1 … note "…")

You can also call it yourself from chat — handflow is a normal tool:

| action | what it does |
| --- | --- |
| start | create the plan: goal + steps (list, or bullets in a string). First step goes in progress |
| plan | show the active plan |
| begin / complete / block / reopen | move a step; add a note |
| note | attach a note to a step |
| add | insert a step (replanning); position is 1-based |
| finish / abort | close the plan (finish refuses while steps are open unless force is set) |
| list / use | recent plans / pin one as active |

Steps are addressed by 1-based number, id (s02), a title substring, or
nothing at all (the current step). Every call returns the rendered plan, so the
agent never spends a second call to look at its own state.

Rules worth knowing: starting a step auto-completes the previous one; completing
the last step closes the plan; adding a step or reopening one reopens it.

What it does not do

• No model calls. The agent is the intelligence; Handflow stores the plan.
• No network, no subprocess, no self-update. The security scan runs clean
  and the plugin never fetches its own code.
• No new palette. The pane uses Hermes theme variables (--ui-*,
  --foreground), so it reskins with whatever theme you run.
• No pane-side notes. One-line toggles only — prose belongs to the agent,
  which is why the note field is written by the tool, not typed in the UI.

Development

python3 -m venv .venv && .venv/bin/pip install pytest pyyaml fastapi httpx
.venv/bin/python -m pytest                  # 41 tests: store, tool, routes, contract
node --test tests/desktop.test.mjs          # 6 tests: registration + render, no app needed
hermes plugins validate .                   # the catalog gate (14 checks)

tests/desktop.test.mjs runs desktop/plugin.js in a node:vm with a stubbed
SDK, so the pane's registration shape, its render output, its click payload and
its poll interval are all checked without launching the app.

Licence

MIT © Ritesh Patel. The planning-flow design (statuses, notes, step-wise
execution) is ported from OpenManus
(MIT, MetaGPT/FoundationAgents); no OpenManus code is included. Handflow is an
independent plugin and is not affiliated with, or endorsed by, Manus or the
OpenManus project.

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