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:

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

Here's the one thing to know about running taskflow on Codex: taskflow_run is synchronous. The tool call doesn't return until the entire DAG finishes — every phase, every subagent. For a three-phase review that's fine; for a fan-out over fifty files with a tournament at the end, it can take a while.

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

For genuinely long work, consider splitting the flow: run the heavy phases in a saved flow, and use a downstream approval or gate phase to pause for review. (Resuming a paused run by runId is a Pi-only capability — /tf resume. On Codex there is no taskflow_resume MCP tool, so a paused run is continued by re-running the flow; phases with cache.scope: "cross-run" are reused automatically.)

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:

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