claude-taskflow

English · 简体中文

1.0 overview · Quickstart · Docs · Examples · Changelog

taskflow 1.0: declarative coding-agent workflows

taskflow is a declarative runtime for coding-agent workflows. It turns a graph into a verifiable execution contract, runs phases in isolation, and keeps intermediate work out of the host conversation. In Taskflow 1.0, the contract also describes the effects a phase is allowed to propose.

Taskflow 1.0.0 includes the DAG runtime, trusted filesystem effects and complete Control Plane (CLI/MCP/WebUI). GitHub Releases and npm establish publication; see the acceptance scoreboard for verified scope and limits.

The declared-effect contract

An agent can propose content. It should not become the mutation authority merely because it can run a command.

For admitted, declared filesystem-write targets, taskflow 1.0 makes the path explicit and routes the final mutation through the resources transaction:

flow / .tf.ts
       │
       ▼
  validate + verify ──► EffectIR + FlowIR hash
       │                         │
       │                         ▼
       │                 admit declared targets
       │                         │
       ▼                         ▼
  isolated phase ───────► stage → commit | restore + reject
                                      │
                                      ▼
                          ledger-backed why-effect

This is not an OS sandbox. Resolve-only hosts cannot prevent every write to an undeclared path. Secret and service references are typed and fail closed in this cut; they do not imply a vault or network backend.

The 1.0 target and current implementation

Layer	What it does	Support boundary
Taskflow runtime	Declarative DAGs, 12 phase types, budgets, retries, approvals, isolation, resume, replay, trace, and recompute	Stable runtime contract
Trusted Effects	Closed EffectIR, PathRef / SecretRef / ServiceRef, confidentiality/integrity labels, effect validation, overlap checks, and ledger-backed why-* explainers	Declared-target contract
Resource transaction	Snapshot → lease → durable intent/permit → stage → commit, or restore and reject	Declared-target contract
Host adapters	Pi, Codex, Claude Code, OpenCode, Grok Build, and Hermes Agent use the same flow contract	Existing host surface; support remains host-specific
Control Plane	Authenticated multi-project admission, global concurrency, durable replay, approvals/CAS, Receipts and operator CLI/MCP	Bundled in public taskflow-mcp-core; Unix UDS, Windows pipes non-GA
WebUI	Runs, approval edits, Receipts and evidence browsing	Local token login, live authorization and project isolation

The 1.0 release plan defines the stable scope and acceptance gates. The filesystem-transaction details are in docs/internal/0.3.0-trusted-effects-mvp.md. The 0.3-C Control Plane plan is docs/internal/0.3-c-control-plane-plan.md.

Quickstart

Use Node.js ≥ 22.19.0. To run from the 1.0 source checkout:

git clone https://github.com/heggria/taskflow.git
cd taskflow
git checkout v1.0.0
pnpm install
pnpm run typecheck
pnpm test

Install the matching 1.0.0 package set after confirming the release is available:

npm install --global pi-taskflow@1.0.0
npm install --global codex-taskflow@1.0.0

The host-specific plugin and MCP commands remain in the host guides.

Run the no-LLM Trusted Effects vertical-slice fixture:

pnpm exec node --conditions=development --experimental-strip-types --test \
  packages/taskflow-core/test/effects-e2e-fixture.test.ts

This exercises the checked-in examples/trusted-effects-write.json path without a live LLM. For an interactive run, use the host guide for the adapter you already run. The release guide covers packed-consumer validation and release gates.

Local Control Console

In Pi, run /tf web to start the bundled local Control Console and open the default browser. If browser opening fails, the command shows a manual loopback URL. Use the one-use token in the reported private (0600) handoff file to log in; tokens are never included in the URL or command notifications.

The console shows Control Plane runs, approvals, Receipts and existing evidence. Legacy Pi run transcripts are outside this view. Repeating the command in the same project reuses its service; changing projects or leaving the Pi session stops only the console process started by that session. Unix local transport is required. If another host already owns the Control home, stop that owner explicitly before launching this console.

See Pi compatibility for the tested SDK matrix and the distinction between real-process fixtures and live-provider acceptance.

Declare an effect

Effects are part of the flow contract, not a free-form prompt promise:

{
  "name": "trusted-effects-write",
  "phases": [
    {
      "id": "write-report",
      "type": "script",
      "run": ["node", "scripts/render-report.mjs"],
      "effects": [
        {
          "id": "report",
          "kind": "fs.write",
          "purpose": "write final report",
          "target": {
            "kind": "path",
            "path": {
              "workspace": "project",
              "subpath": { "literalPath": "out/report.md" },
              "intent": "create-file"
            }
          },
          "confidentiality": "internal",
          "integrity": "project"
        }
      ],
      "final": true
    }
  ]
}

The declaration is not authorization by itself. The runtime resolves the PathRef, checks labels and overlaps, records the resource intent, and only then permits the transaction to stage and finalize the declared target. taskflow_why_effect explains the resulting authorization and ledger state without model calls.

The runtime contract

The 0.2 runtime remains the foundation. A flow can be authored as portable JSON or compiled from TypeScript DSL to FlowIR:

JSON / .tf.ts
      │
      ▼
validate → Taskflow JSON → FlowIR + content hash
                                  │
                                  ▼
                         isolated DAG runtime
                                  │
                   resume · replay · recompute · trace
                                  │
                                  ▼
                         finalOutput to the host

One runtime, 12 phase types

Family	Phases	Use them for
Work	agent · parallel · map · reduce · script	Single tasks, static concurrency, dynamic fan-out, aggregation, and zero-token shell steps
Control	gate · approval · flow · loop	Quality decisions, human checkpoints, composition, and iterative refinement
Selection	tournament · race	Best-of-N quality or first-success latency
Dynamic graph	expand	Validate and execute a runtime-produced nested or grafted fragment

Across those phase types, the runtime provides shared behavior: dependencies, conditions, retries, timeouts, output contracts, budgets, workspace isolation, explicit final-output selection, and persistence for resume. Each phase kind accepts only the fields that are safe and meaningful for it.

Useful zero-token operations include:

Operation	Question it answers
taskflow_plan	What will run, what arguments bind, and what is the worst-case agent-call bound?
taskflow_verify / taskflow_compile	Is the graph structurally valid and what is its canonical form?
taskflow_trace / taskflow_replay	What happened, or what would a zero-token what-if replay decide?
taskflow_why_stale / taskflow_recompute	What changed and what is the smallest affected frontier?
taskflow_why_effect	Why was a declared effect allowed, staged, committed, rejected, or left unknown?
taskflow_analytics	How have recent runs behaved?

The MCP surface currently exposes 20 tools. Intermediate transcripts remain inside the runtime unless you explicitly inspect them with peek or trace; the host normally receives only finalOutput.

Host adapters

The same flow contract can be delivered through six coding-agent hosts:

• Pi — native extension, /tf commands, live run views, and interactive approvals.
• Codex — plugin and stdio MCP server.
• Claude Code — plugin and stdio MCP server.
• OpenCode — MCP configuration and generated skill.
• Grok Build — MCP configuration and generated skill.
• Hermes Agent — MCP delivery with explicit child toolsets and isolation policy.

Host support is not a blanket security guarantee. Read the host support baseline and the Trusted Effects documentation before enabling mutating phases.

Security boundaries we state plainly

• effects[] is a declaration and validation surface; it is not ambient authority.
• The resources layer is the only finalizer for admitted declared filesystem effects.
• Direct writes to declared targets are detected and restored by the MVP path.
• Writes to undeclared paths remain host-policy dependent under resolve-only execution.
• SecretRef and ServiceRef are typed handles only; no vault or live service adapter ships in this cut.
• There is no FileBroker or full OS sandbox claim in 0.3 MVP.
• Control Plane admission, authorized replay, durable approvals, Receipts, global coordination and WebUI are implemented. Public taskflow-mcp-core provides the control binaries; operator actions require an explicitly provisioned separate credential. Request audit fields never grant authority.

Development

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

The monorepo contains the host-neutral taskflow-core, Trusted Effects and resources code, the taskflow-control 0.3-C contract package, the TypeScript DSL, MCP/host adapters, examples, and the website. See AGENTS.md for architecture and coding conventions.

Documentation

Start here	Use it for
1.0 overview	1.0 scope, support, and the security boundary
Getting Started	First flow and host setup
Core Concepts	DAGs, isolation, verification, resume, and evidence
Compiler & Runtime	JSON, TypeScript DSL, FlowIR, replay, and recompute
Host Guides	Pi, Codex, Claude Code, OpenCode, Grok, and Hermes
Examples	Runnable flow definitions, including Trusted Effects
Changelog	Release history and version notes

License

MIT © heggria

Declare the effect. Verify the path. Commit through one authority.

Read the docs · Install Taskflow 1.0 · View releases