Commands
Pi slash commands and MCP tools (Codex, Claude, OpenCode, Grok, Hermes).
taskflow exposes the same operations two ways. On Pi, you type slash commands like /tf run and /tf:review-changes. On Codex (and Claude Code, OpenCode, Grok, Hermes), the same operations are MCP tools the model calls — taskflow_run, taskflow_list, and so on.
This page is a grouped reference for both. Every command has a one-line purpose and, where useful, a concrete example. If you just want to skim, jump to the example session at the end.
Saved flows become CLI shortcuts on Pi (/tf:<name>). On MCP hosts, you run a saved flow by name through taskflow_run.
Pi /tf commands
The /tf command is the user-facing surface on Pi. Its subcommands fall into four groups.
Run
| Command | Description |
|---|---|
/tf run <name> [args] | Run a saved flow, optionally passing args as key=value pairs or JSON. |
/tf:<name> [args] | Shortcut — equivalent to /tf run <name> [args]. Registered for every saved flow. |
/tf resume <runId> | Resume a paused or failed run from where it stopped. |
Inspect
| Command | Description |
|---|---|
/tf list | List all saved flows in this project. |
/tf show <name> | Print a saved flow's full JSON definition. |
/tf runs | Browse recent run history (last 50) and pick one to inspect or resume. |
/tf peek <runId> [phaseId] | Inspect a stored run's intermediate phase output (post-hoc debugging). Supports --json, --item <n>, --limit <chars>. |
Verify & analyze
| Command | Description |
|---|---|
/tf plan <name> [args-json] | Zero-token preflight — bind args, project phase order + dynamic bindings, worst-case agent-call bound. Prefer this before run. |
/tf verify <name> | Statically verify a flow — cycles, missing deps, dead ends — at zero token cost. |
/tf compile <name> [lr|td] | Render the DAG as a Mermaid diagram (lr = left-right, td = top-down). |
/tf analytics <name> [--last N] | Aggregate last-N runs: status histogram, durations, per-phase fail/cache rates (read-only). |
/tf ir <name> | Compile to FlowIR + content hash (the incremental-recompute intermediate). |
/tf provenance <runId> | Show the observed read-set provenance for a run. |
/tf why-stale <runId> [phaseId] | Explain why a cached run is stale — which fingerprint input changed. |
/tf recompute <runId> <phaseId> [--apply] | Minimally recompute a stale phase. Default is a safe dry-run (with savings line); --apply spends tokens. |
/tf trace <runId> [--json] | Show the append-only event log (subagent I/O + runtime decisions). |
/tf replay <runId> [--threshold phase=n] [--budget-usd n] [--json] | Offline what-if re-judge of thresholds/budget from a recorded trace (zero tokens). |
Lifecycle
| Command | Description |
|---|---|
/tf save | Save the most recent inline flow definition under a name (makes /tf:<name> available immediately). |
/tf search | Search the reusable-flow library by purpose/tags. |
/tf init | Configure model roles — map the built-in agent roles to your models. |
peek, provenance, why-stale, and recompute explain what would re-run. trace + replay explain what was decided and counterfactual knobs — see Deterministic Replay.
The taskflow tool (Pi)
On Pi, the model can also invoke a taskflow tool directly. It takes an action plus parameters. The actions mirror the /tf subcommands and add a few the model uses internally:
| Action | Description |
|---|---|
run | Run an inline or saved flow. |
plan | Zero-token preflight (args bind + phase plan + budget bound). |
save | Persist a flow definition. |
search | Search the reusable-flow library by purpose/tags. |
resume | Resume a run by runId. |
list | List saved flows. |
agents | List the built-in agents. |
verify | Static check. |
compile | Mermaid diagram + verification report. |
analytics | Read-only last-N run aggregation for a flow name. |
ir / provenance / why-stale / recompute | Incremental recompute toolkit. |
trace / replay | Event log inspection + offline decision what-if (zero tokens). |
cache-clear | Clear the cross-run memoization cache. |
init | Configure model roles. |
Codex / Claude / OpenCode / Grok / Hermes MCP tools
On MCP hosts, taskflow exposes these tools (the model calls them; you usually don't type them):
| Tool | Description |
|---|---|
taskflow_run | Run an inline or saved flow; returns the final output and a runId. |
taskflow_runs | List background runs, or status / bounded wait / cancel one by runId. |
taskflow_resume | Fork a failed or paused run into a new immutable child run, with optional one-phase overrides. |
taskflow_version | Report package version, build commit, schema version, build time, and host. |
taskflow_list | List saved flows discoverable in this directory. |
taskflow_show | Print a saved flow's definition. |
taskflow_plan | Zero-token preflight: bind args, phase plan, budget bound (no execution). |
taskflow_analytics | Aggregate last-N runs for a flow (status, duration, fail/cache rates). |
taskflow_verify | Statically verify a flow (no execution). |
taskflow_compile | Render a DAG as SVG plus a standalone text outline and verification status; oversized graphs fall back to text only. |
taskflow_peek | Inspect one phase's intermediate output from a stored run (post-hoc debugging). |
taskflow_trace | Read-only timeline of the run's append-only event log. |
taskflow_replay | Offline what-if re-judge of thresholds/budget from a recorded trace (zero tokens). |
taskflow_why_stale | Explain observed/declared dependency staleness. |
taskflow_recompute | Report the stale frontier (dry-run only over MCP). |
taskflow_reconcile_workspace | Explicitly accept an inspected/repaired resolve-only workspace after a dirty-unknown write; requires Host authorization and exact acknowledgement. |
taskflow_save | Save a flow to the library with purpose/tags. |
taskflow_search | Search the reusable-flow library. |
On MCP hosts there is no /tf slash command — you describe the work in natural language and the model calls taskflow_run. Use taskflow_peek / taskflow_trace / taskflow_replay with the runId from taskflow_run for post-hoc inspection and offline what-if.
An example session
A realistic session on Pi, from first run to debugging:
/tf verify review-changesVerify catches a cycle and a missing dependsOn before any tokens are spent. Fix the JSON, then run it:
/tf run review-changes dir=srcThe run completes and returns the final summary. You like it, so save it:
/tf save review-changesFrom now on, the shortcut works:
/tf:review-changes dir=srcA few days later the summary looks stale. Check why without re-running:
/tf runs
/tf why-stale <runId> summarywhy-stale reports that git:HEAD changed since the cached run. Recompute just that phase:
/tf recompute <runId> summary --applyOnly summary re-runs; the rest of the flow is reused from cache.
Next
Shorthand
task, tasks, chain — the quick-delegation shortcuts.
Getting Started
Run your first taskflow.
Caching
Cross-run memoization and the why-stale / recompute toolkit.
Last updated on
Was this helpful?
Help us improve the docs or ask a question in the community.