Using taskflow on Claude Code

Claude Code is a natural home for taskflow: it already thinks in terms of subagents, and taskflow gives those subagents a declarative graph to run inside. The plugin registers the MCP server plus a routing skill; its protocol layer needs no MCP SDK.

This page walks through the whole arc: install the plugin, confirm the MCP server is live, run a flow through a tool call, and understand the permission and long-running-flow model.

Install

taskflow is distributed through the shared plugin marketplace. Add the marketplace, then install the plugin:

Requires Node.js ≥ 22.19.0.

claude plugin marketplace add heggria/taskflow
claude plugin install claude-taskflow@taskflow

That single plugin install does three things at once:

Restart your Claude Code session if it was already running, so the new plugin is picked up.

Verify the install

Before running anything, confirm both the plugin and its MCP server registered cleanly:

claude plugin list   # claude-taskflow@taskflow should appear, enabled
claude mcp list      # taskflow should appear, enabled

If either is missing, the plugin install step didn't complete — re-run it and check for errors.

Run your first flow

On Claude Code, you don't invoke taskflow through a slash command — you invoke it through an MCP tool. The model decides when to call it, guided by the bundled skill. So the most natural way to start is to just describe the work.

Just ask

Try one of these in a Claude Code session:

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

The skill routes the request to the right tool. If a flow is saved in the current project, the model calls taskflow_run with the saved name; if you pasted an inline definition, it passes that instead.

Call the tool directly

If you want to be explicit — useful in scripts or when you know the exact shape — the tool is taskflow_run. It accepts either a saved flow name or an inline define:

{
  "name": "review-changes",
  "args": { "dir": "src" }
}

{
  "define": {
    "name": "quick-review",
    "phases": [
      {
        "id": "discover",
        "type": "agent",
        "agent": "scout",
        "task": "List changed source files under src/. Output ONLY a JSON array of {path} objects.",
        "output": "json"
      },
      {
        "id": "review-each",
        "type": "map",
        "over": "{steps.discover.json}",
        "as": "file",
        "agent": "security-reviewer",
        "task": "Review {file.path} for security risks. Return one paragraph.",
        "dependsOn": ["discover"],
        "concurrency": 4
      },
      {
        "id": "summarize",
        "type": "reduce",
        "from": ["review-each"],
        "agent": "writer",
        "task": "Combine these reviews into one prioritized summary:\n{steps.review-each.output}",
        "dependsOn": ["review-each"],
        "final": true
      }
    ]
  }
}

Either form runs the same DAG. The tool returns only the final output — the intermediate transcripts from discover, review-each, and summarize stay inside the runtime and never enter your context.

Check a flow before spending tokens

Before running a DAG, you can ask Claude Code to verify it statically. This catches cycles, dangling dependsOn, unknown phase references, and malformed configs — all at zero token cost:

{
  "name": "review-changes"
}

Or render the DAG as a diagram to eyeball its shape:

{
  "name": "review-changes"
}

taskflow_compile returns the DAG grouped into topological layers as a text outline, plus an inline SVG image for clients that render images.

How subagents run

Each phase's subagent runs as an isolated claude -p session — a real Claude Code headless process, not a pi process. The server discovers saved flows and agents from its launch cwd, so the project you start it in determines which flows are visible.

Permission mapping

Claude Code has no OS-level sandbox in headless (-p) mode — a tool call is either whitelisted or denied. The runner maps each phase's tool whitelist to a permission mode:

Taskflow requires Claude Code 2.1.169 or newer for --safe-mode. Older CLIs fail closed with an unknown-option error, so upgrade before using this adapter.

Long-running flows

taskflow_run is synchronous by default. For a long flow, set mode: "background"; the MCP call returns a durable runId immediately. Use taskflow_runs to list, inspect, wait for, or cancel that worker.

Then inspect the run afterward with taskflow_peek:

{
  "runId": "run_2026-07-04_abc123",
  "phaseId": "summarize"
}

Omit phaseId to list every phase with its status and output size. Output is hard-truncated (default 4000 chars) so a peek never floods your context.

Approvals in MCP mode

MCP-driven runs are non-interactive, so an approval phase auto-rejects (fail-closed for the approval decision). Prefer a gate (agent review) in flows you run through the taskflow_* tools; use approval only in flows a human runs interactively.

Tool reference

Here's the full MCP surface the plugin exposes:

Alternative: register the MCP server manually

If you'd rather not use the plugin, install the package and register its claude-taskflow-mcp bin yourself:

pnpm add -g claude-taskflow
claude mcp add taskflow -- claude-taskflow-mcp

Verify it registered:

claude mcp list   # taskflow … enabled

The server behaves identically to the plugin version — it just doesn't come with the routing skill or the one-command update path.

Remove

If you need to take taskflow off a machine:

claude plugin uninstall claude-taskflow@taskflow   # if installed as a plugin
claude mcp remove taskflow                          # if registered manually

This unregisters the MCP server and removes the skill. Any saved flow definitions on disk are left untouched.

Next

Last updated on