Using taskflow on Codex

Codex is a natural home for taskflow: it already thinks in terms of subagents, and taskflow gives those subagents a declarative graph to run inside. On Codex, taskflow ships as a plugin that registers an MCP server plus a routing skill, so the model can call it the moment it sees a multi-step task.

This page walks through the whole arc: install the plugin, confirm the MCP server is live, run a flow through a tool call, and configure things for long-running work.

Install

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

Requires Node.js ≥ 22.19.0.

codex plugin marketplace add heggria/taskflow
codex plugin add taskflow@taskflow

That single plugin add does three things at once:

Restart your Codex 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:

codex plugin list   # taskflow@taskflow should appear, enabled
codex mcp list      # taskflow should appear, enabled

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

Run your first flow

On Codex, 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 Codex 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 Codex 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"
}

Long-running flows

taskflow_run is synchronous by default, which is ideal when you want the final result in the current turn. For a long DAG, set mode: "background"; Codex receives a durable runId immediately and the worker continues independently.

The plugin ships a 30-minute default tool-call timeout to accommodate this. If your flows run longer, override it in your Codex config:

[mcp_servers.taskflow]
tool_timeout_sec = 3600

Start background work with taskflow_run { name: "...", mode: "background" }, then use taskflow_runs to list, inspect, wait for, or cancel it. A failed or paused run can be continued with taskflow_resume, which forks immutable history into a new child run.

Inspect a run after the fact

Every taskflow_run returns a runId. If something went wrong — a gate blocked, a phase produced odd output — you can inspect a single phase's stored output without re-running the whole flow:

{
  "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.

Tool reference

Here's the full MCP surface the plugin exposes:

Codex does not enforce tools as a strict name whitelist. Read-only sets map to -s read-only; mutating or omitted sets map to -s workspace-write. Thinking maps to model_reasoning_effort (off/none/minimal → none, max/ultra → xhigh); unsupported values fail before spawn.

Remove

If you need to take taskflow off a machine:

codex plugin remove taskflow@taskflow

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

Next

Last updated on