taskflow

Using taskflow on Hermes Agent

Install taskflow as an MCP server on Hermes Agent and orchestrate multi-phase workflows with isolated Hermes subagents.

Taskflow 1.0.0 documentation. These instructions use exact 1.0.0 package pins. Check GitHub Releases for publication and the acceptance scoreboard for tested scope and limitations. The Control Plane and WebUI are implemented; control binaries are bundled in taskflow-mcp-core.

Hermes Agent is Nous Research's open-source coding agent (CLI, TUI, desktop, messaging gateways). Taskflow's published path is its MCP server: Hermes discovers taskflow_* tools and each agent phase spawns an isolated hermes chat -q -Q child.

The full reference lives in docs/hermes-mcp.md in the repo.

Install

Published MCP package (after npm publish)

Register taskflow MCP
hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@1.0.0 hermes-taskflow-mcp

Or paste into ~/.hermes/config.yaml / $HERMES_HOME/config.yaml:

mcp_servers.taskflow
mcp_servers:
  taskflow:
    command: "npx"
    args: ["-y", "-p", "hermes-taskflow@1.0.0", "hermes-taskflow-mcp"]
    env:
      # Required for mutating agent phases (terminal / file write / coding).
      # PI_TASKFLOW_HERMES_UNSAFE_YOLO: "1"  # required for mutating agent phases
    timeout: 600

Requires Node.js ≥ 22.19.0. Restart Hermes so MCP tools are rediscovered as mcp_taskflow_*.

Local monorepo dogfood (before npm publish)

Local dogfood install
pnpm install
pnpm --filter taskflow-core build
pnpm --filter taskflow-mcp-core build
pnpm --filter taskflow-hosts build
pnpm --filter hermes-taskflow build

# Point MCP at the compiled bin:
#   command: node
#   args: ["/abs/path/to/packages/hermes-taskflow/dist/mcp/bin.js"]
#   env: { PI_TASKFLOW_HERMES_UNSAFE_YOLO: "1" }

Optional skill:

cp -R packages/hermes-taskflow/plugin/skills/taskflow ~/.hermes/skills/taskflow

Verify the install

hermes mcp list
hermes mcp test taskflow

In a Hermes session, tools should appear as mcp_taskflow_list, mcp_taskflow_verify, mcp_taskflow_run, …

Run your first flow

Just ask

> List my saved taskflows.
> Verify this flow, then run it: {name:"review-changes", phases:[...]}
> Run the "review-changes" taskflow with dir set to src.

Call tools directly

Prefer mcp_taskflow_plan or mcp_taskflow_verify before any spend, then mcp_taskflow_run.

Permissions & safety

Phase kindBehavior
Child isolationephemeral HERMES_HOME with non-secret model/fallback routing, a routed-provider-only inference auth.json, and provider-only dotenv; no parent MCP/skills/memory/rules; RO plugin only on RO children
Read-only tool whitelistlocal-read → taskflow_readonly_files; else model-only; PI_TASKFLOW_HERMES_READONLY_WEB=1 → web,search (never attach writable file)
Mutating / default-capableRequires PI_TASKFLOW_HERMES_UNSAFE_YOLO=1 → child --yolo
Budgeted flowsRejected — Hermes quiet mode does not report token/cost

Install footgun: write MCP env: in config.yaml. Do not pass --env after bare CLI args in a way that lands in the node argv list.

Optional env:

  • PI_TASKFLOW_HERMES_UNSAFE_YOLO (mutating only; leave unset for verify/script)
  • PI_TASKFLOW_HERMES_READONLY_WEB (opt-in network on RO)
  • PI_TASKFLOW_HERMES_MAX_TURNS (default 64)
  • PI_TASKFLOW_HERMES_BIN (default hermes)
  • HERMES_HOME as the parent source for model routing and allowlisted provider auth; every child receives a separate ephemeral home

How subagents run

Each agent phase is:

hermes chat -q "<system + task>" -Q --source tool -t <toolsets> --max-turns N [--in cwd] [-m model] [--yolo]

Quiet mode prints answer text on stdout and session_id metadata on stderr. The runner preserves stdout, including blank lines and answer text that begins with session_id:.

Next

Last updated on

Was this helpful?

Help us improve the docs or ask a question in the community.

On this page