English · 简体中文

Install · Quickstart · What's new in 0.2 · Docs · Examples

Build multi-agent systems you can inspect before they run.

taskflow turns agent plans into compiled task graphs: declared once, verified before model spend, executed in isolated subagents, resumed across sessions, replayed without tokens, and recomputed from the smallest stale frontier.

It runs on the coding agent you already use:

Pi · Codex · Claude Code · OpenCode · Grok Build

JSON or .tf.ts
      │
      ▼
 validate ──► Taskflow JSON ──► FlowIR + content hash
                                      │
                                      ▼
                           isolated DAG runtime
                                      │
                         ┌────────────┼────────────┐
                         ▼            ▼            ▼
                      resume        replay      recompute

Your host receives the final result. Intermediate transcripts stay inside the runtime unless you explicitly inspect them.

Why taskflow?

Built-in subagent tools are excellent for one turn. The moment the work branches, retries, crosses sessions, or needs a quality gate, the plan becomes infrastructure.

The trade is deliberate: less arbitrary orchestration code, more verifiability, observability, recovery, and reuse.

60-second start

Install taskflow on Pi:

pi install npm:pi-taskflow

Then ask naturally:

Use taskflow to audit src/api in parallel and return one prioritized report.

The routing skill uses the same familiar task / tasks / chain shape:

{
  "chain": [
    { "agent": "scout", "task": "Map the public API under src/api." },
    {
      "agent": "security-reviewer",
      "task": "Audit this surface for missing auth and unsafe input boundaries:\n{previous.output}"
    },
    {
      "agent": "reviewer",
      "task": "Turn these findings into one prioritized report:\n{previous.output}"
    }
  ]
}

That already gives you an isolated, tracked run. When the job needs real topology, declare the graph:

{
  "name": "audit-api",
  "args": { "dir": { "default": "src/api" } },
  "concurrency": 4,
  "phases": [
    {
      "id": "discover",
      "type": "agent",
      "agent": "scout",
      "task": "List source files under {args.dir}. Output ONLY a JSON array of {\"path\":\"...\"} objects.",
      "output": "json"
    },
    {
      "id": "audit-each",
      "type": "map",
      "over": "{steps.discover.json}",
      "as": "file",
      "agent": "security-reviewer",
      "task": "Audit {file.path}. Cite evidence and assign severity.",
      "dependsOn": ["discover"]
    },
    {
      "id": "report",
      "type": "reduce",
      "from": ["audit-each"],
      "agent": "reviewer",
      "task": "Synthesize one prioritized report:\n{steps.audit-each.output}",
      "dependsOn": ["audit-each"],
      "final": true
    }
  ]
}

Save it as .pi/taskflows/audit-api.json, then run:

/tf:audit-api dir=src/api

On Codex, Claude Code, OpenCode, and Grok Build, run the same saved definition by name through taskflow_run.

Follow the full quickstart →

See the graph run

This is real output from a Pi run—not a mock dashboard:

⊗ taskflow self-improve  6/7 · blocked · $0.095
    ✓ discover            agent   deepseek-v4-flash  10t ↑38k ↓6.7k $0.011
  ┌ ✓ write-runner-tests  agent   claude-sonnet-4-6  10t ↑13 ↓6.6k $0.020
  ├ ✓ write-store-tests   agent   claude-sonnet-4-6  10t ↑11 ↓10k $0.018
  ├ ✓ write-agents-tests  agent   claude-sonnet-4-6  10t ↑28 ↓13k $0.030
  └ ✓ fix-stability       agent   claude-sonnet-4-6  10t ↑13 ↓3.9k $0.012
    ✓ verify              gate    BLOCK 3 type errors in test files
    ⊘ report              reduce  skipped · Gate blocked  ↳ fix-stability

The layout is the DAG. Parallel rails expose concurrency; long edges expose dependencies; the gate explains why downstream work stopped. No separate control plane is required to understand the run.

0.2 is the compiler turn

Before 0.2, taskflow executed declarative graphs. Now the graph also has a compile-time frontend, a canonical intermediate representation, an append-only decision trace, offline replay, and incremental recompute.

Author in JSON or TypeScript

JSON remains the portable runtime contract. For larger flows, taskflow-dsl adds a compile-time TypeScript authoring layer:

import { agent, flow, json, map, reduce } from "taskflow-dsl";

export default flow("audit", (ctx) => {
  ctx.budget({ maxUSD: 2 });

  const files = agent("List files under {args.dir}", {
    agent: "scout",
    output: json<{ path: string }[]>(),
  });

  const audits = map(files, (file) =>
    agent(`Audit ${file.path}`, { agent: "security-reviewer" }),
  );

  return reduce(
    [audits],
    (parts) => agent(`Write one report:\n${parts.audits.output}`),
    { final: true },
  );
});

pnpm add -D taskflow-dsl
taskflow-dsl check audit.tf.ts
taskflow-dsl build audit.tf.ts --emit both
# → audit.taskflow.json + audit.flowir.json

.tf.ts is compile-time only. Hosts execute the emitted Taskflow JSON; they never interpret TypeScript.

Compile to a contract you can reason about

FlowIR canonicalizes the graph and gives it a content hash. That compiled identity makes provenance and stale analysis inspectable, while the runtime adds content-addressed caching and deterministic tools:

Explore the compiler and runtime →

One runtime, 12 phase types

Across those phase types, the DSL provides dependencies, conditions, retries, timeouts, output contracts, budgets, workspace isolation, and explicit final-output selection. Each kind accepts only the fields that are safe and meaningful for it; freshness-sensitive phases are excluded from cross-run caching.

Read the phase reference →

Runtime guarantees, not prompt conventions

Verify before spend

Cycles, dangling dependencies, invalid references, impossible joins, unsafe dynamic fragments, and configuration hazards are rejected or surfaced before the expensive work starts.

Keep intermediate work out of the host context

Agent-running phases execute in isolated subagent processes; control and script phases stay inside the runtime. Upstream outputs are wired into downstream inputs internally. Only finalOutput returns to the host unless you explicitly use peek or trace.

Survive sessions and failures

Phase state is persisted atomically. Resume skips unchanged completed work; detached Pi runs can outlive the initiating session; an idle watchdog terminates stalled subagents.

Reuse work honestly

Within-run resume is content-addressed. Cross-run caching is opt-in and can fingerprint Git commits, files, globs, environment variables, and TTLs. Change one declared input and only its dependents become stale.

Bound the blast radius

Budgets, concurrency caps, retries, timeouts, nesting limits, dynamic-graph breadth caps, path containment, non-idempotent phase classification, and fail-closed approval behavior are runtime semantics—not suggestions in a prompt.

Read the core concepts →

Install on your host

All packages require Node.js ≥ 22.19.0.

Pi

pi install npm:pi-taskflow

Pi provides the richest local experience: the taskflow tool, /tf commands, live DAG rendering, interactive approvals, background runs, and model-role setup.

Pi guide →

OpenAI Codex

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

Codex guide →

Claude Code

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

Claude Code guide →

OpenCode

opencode mcp add taskflow -- \
  npx -y -p [email protected] opencode-taskflow-mcp

OpenCode guide →

Grok Build

grok mcp add taskflow -- \
  npx -y -p [email protected] grok-taskflow-mcp

Grok Build support is new in 0.2. Its CLI stream does not report token/cost usage, so budget-declaring flows are rejected rather than silently running without enforcement.

Grok Build guide →

Built to survive real work

                              taskflow-core
                 ┌──────────────┼───────────────┐
                 │              │               │
           taskflow-dsl   pi-taskflow   taskflow-mcp-core ─┐
                                       taskflow-hosts ─────┼─ codex-taskflow
                                                          ├─ claude-taskflow
                                                          ├─ opencode-taskflow
                                                          └─ grok-taskflow

taskflow-core is host-neutral and imports no host SDK. taskflow-mcp-core implements stdio JSON-RPC without an MCP SDK dependency; taskflow-hosts owns the shared host process runners. The four MCP delivery packages bind both layers (and core), while Pi keeps its native adapter.

The test suite covers orchestration semantics, persistence and file-lock races, cache freshness, path traversal, dynamic graph hardening, cancellation, budgets, all 12 phase kinds, FlowIR/replay/recompute, TypeScript DSL erasure, host argv contracts, MCP servers, and packed consumer imports.

Documentation

Also see examples/, the changelog, and the release guide.

Contributing

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run test:pack

Contributions are welcome. Start with CONTRIBUTING.md for the workflow and AGENTS.md for architecture and coding conventions.

License

MIT © heggria