Changelog

​

Branch convergence

### summarize
- type: llm
- prompt: Result was: ${branch-high.stdout ?? branch-low.stdout}

• Added the ?? coalesce operator for template syntax (${a.stdout ?? b.stdout}). The resolver tries each operand left-to-right and skips branches that did not execute.
• Coalesce is supported in all template contexts: inline strings, shell commands, LLM prompts, input dicts, workflow output sources, and batch items.
• Python code nodes now accept Optional[T] or T | None input annotations. If the source branch didn’t execute, None is injected automatically instead of raising a runtime error.

​

Nested workflows

### process-document
- type: workflow
- workflow: ./child.pflow.md
- title: "Hello World"
- body: ${read-file.content}

• Unified workflow parameter handles both file paths and saved workflow names.
• Non-reserved parameters become child inputs.
• If the child workflow declares ## Outputs, they are exposed to the parent via standard dot notation (${node_id.output_name}).
• Fixed relative path resolution so ./child.pflow.md always resolves from the parent workflow’s directory, even across deep nesting levels.
• The template validator now statically resolves child workflow outputs to catch typos during compilation.

​

LLM reasoning and cost tracking

### analyze-data
- type: llm
- model: claude-sonnet-4-5
- reasoning_effort: high
- prompt: Analyze this dataset...

• Added reasoning_effort (xhigh, high, medium, low, minimal, none) and reasoning_max_tokens (direct token budget) to the LLM node.
• Added a model_options parameter to the LLM node as an escape hatch for provider-specific fields.
• Unified LLM cost access: ${node.llm_usage.cost_usd} now works in workflow templates for both standard LLM and Claude Code nodes.
• LLM costs are computed at execution time, making cost_usd available in the shared store immediately after each node runs.
• The Claude Code node’s redundant _claude_metadata output was removed; all metadata is consolidated into llm_usage.

​

Validation and execution robustness

• The template validator now infers the internal structure of batch items based on the upstream batch source, catching invalid ${item.field} references at compile time with “did you mean?” suggestions.
• Validation now recurses into nested dictionaries and lists (such as the inputs dict on code nodes) to catch typos and non-existent forward references.
• Required workflow inputs now strictly fail validation when provided as empty strings.
• Batch nodes now return an “error” action on partial failures when error_handling: continue is set, enabling proper on-error routing for partial batch failures.
• Fixed a bug where the validator blocked batch processing entirely on nested workflow nodes.
• Resolved a _thread.RLock pickle error that caused parallel batch processing to crash at runtime.

• Added --timeout and --sse-timeout flags to pflow mcp add so custom timeout values are preserved in config files.

### process
- type: workflow
- workflow_ref: ./child.pflow.md
- param_mapping:
    text: ${source.text}
- output_mapping:
    summary: child_summary

​

Conditional branching and loops

### router
- type: code
- on-error: error-handler

```python code
data: dict
if data["category"] == "premium":
    next: str = "premium-handler"
else:
    next: str = "standard-handler"
```

• Added - next:, - on-error:, and - next: end syntax for static and error routing.
• Python code nodes support a next variable for dynamic, data-driven routing.
• Caching is now automatically invalidated when a node is revisited in a loop, ensuring exit conditions are correctly re-evaluated.
• flow.run() is now always wrapped to ensure visit counts reset correctly between executions.
• Topological sorting now uses position-based edge filtering to allow valid data dependencies while preventing cycle errors on backward loop edges.

​

Guaranteed structured JSON

### extract-entities
- type: llm
- prompt: Extract entities from ${read.content}

```yaml output_schema
type: object
properties:
  people:
    type: array
    items:
      type: string
required:
  - people
```

• yaml output_schema code blocks pass JSON Schema dicts directly to the llm library.
• The API response is parsed and stored as a dict, avoiding downstream string parsing.
• Code block stripping is safely skipped when a schema is set, since the API returns clean JSON.

​

Stateful MCP servers and error reporting

• Persistent connection pool keeps both stdio and http MCP sessions alive across nodes.
• Automatic crash recovery evicts and retries sessions once if a transport error (like a broken pipe) occurs.
• MCP error reporting now un-wraps internal ExceptionGroup task failures to show the actual HTTP error (e.g., “Authentication failed” instead of a raw 40-line traceback).
• Fixed a logging bug that prepended “MCP tool failed:” twice.
• Node output formatter correctly detects error keys so MCP failures show as “failed” instead of “succeeded”.

### router
- type: code
- on-error: error-handler

### error-handler
- type: shell
# Silently fell through to the next node below it

uv tool install pflow-cli

​

Agent skills

# Publish a workflow to multiple tools at once
pflow skill save pr-analyzer --cursor --copilot

• pflow skill save enriches workflows with usage sections and metadata for the agent.
• Support for multiple targets: --cursor, --copilot, --codex, and --personal.
• pflow workflow history shows execution stats and last-used inputs.
• Improved discovery matching by including input names and node IDs in the context.

​

Data integrity

• LLM nodes preserve prose explanations alongside code blocks.
• JSON fields are still accessible via dot notation: ${node.response.field}.
• Numeric strings (like Discord IDs) declared as type: string are no longer coerced to integers.
• Batch node error messages now correctly list available outputs for inner items.
• Workflow frontmatter tracks average execution duration for performance monitoring.

​

Developer experience

• Code node errors show Location and Source fields with correct line mapping.
• MCP server configs now expand environment variables in URLs and settings.json.
• Markdown parser specifically detects and explains nested backtick errors.

uv tool install pflow-cli
# or
pipx install pflow-cli

​

Workflows are documentation

# Daily Report
## Steps
### fetch-data
- type: http
- url: https://api.github.com/repos/owner/repo/issues

### summarize
- type: llm
- prompt: Summarize these issues: ${fetch-data.response}

• New .pflow.md extension with YAML frontmatter for metadata.
• Line-by-line error reporting with context, replacing JSON syntax errors.
• “Save” operations update the file in place, preserving your comments.
• pflow workflow save extracts the description directly from the document prose.

​

Native Python execution

### transform-data
- type: code
- inputs:
    data: ${fetch.response}
    limit: 10

```python code
data: list
limit: int

result: list = data[:limit]
```

• Zero-overhead data passing for heavy transformations.
• Required type annotations catch type mismatches before execution.
• stdout/stderr capture for debugging, with configurable timeouts.

​

Unix piping and validation

# Chain workflows with the -p (pipe) flag
pflow -p fetch-logs | pflow -p parse-logs | pflow analyze-errors

• stdin: true input property for explicit pipe routing.
• FIFO detection prevents hangs when no input is piped.
• Unified validation logic ensures --validate-only matches runtime behavior.
• Improved error messages for unknown node types (no more stack traces).
• disallowed_tools parameter on Claude Code nodes to block specific tools in agentic workflows.
• Fixed nested template validation for ${item.field} inside array brackets.

### process
- type: shell
- stdin: ${stdin}

​

Batch processing

### classify-items

Classify each item in parallel. 30 concurrent LLM calls.

- type: llm
- batch:
    items: ${fetch-data.result}
    parallel: true
    max_concurrent: 30

• Sequential and parallel execution with configurable concurrency (max_concurrent).
• error_handling: continue keeps going when individual items fail — you get partial results instead of nothing.
• Progress indicators in the CLI so you can see where a 200-item batch is at.
• Access results with ${node.results}, individual items with ${node.results[0].response}.

​

Smarter templates

• ${node.stdout.field} resolves through JSON strings without an intermediate node.
• Inline object templates preserve types correctly — no more double-serialization when passing dicts.
• Dicts and lists auto-coerce to JSON strings when mapped to string-typed parameters.
• Optional inputs without defaults resolve correctly instead of erroring.

### get-data
- type: shell
# curl outputs JSON string

### extract-json
- type: shell
# jq extracts the field you need

### use-data
- type: llm
# finally gets the value

​

Shell node fixes

• stderr visible on successful commands, not just failures.
• Trailing newlines stripped from stdout by default (disable with strip_newline: false).
• Pipeline-aware error detection for grep | sed chains where only the last exit code was visible.
• Fixed SIGPIPE crashes when a subprocess closed its input early.

### transform
# Could silently read "data" from shared store
- type: code

​

Validation that helps you fix things

✗ Node 'format-report' references unknown output 'fetch-data.email'

Available outputs from 'fetch-data':
  ✓ ${fetch-data.response} (dict)
  ✓ ${fetch-data.status_code} (int)
  ✓ ${fetch-data.response_headers} (dict)

Tip: Did you mean ${fetch-data.response}?

• Template references checked against actual node outputs before execution starts.
• “Did you mean?” suggestions for misspelled node names and output paths.
• Type mismatch warnings when connecting incompatible outputs to inputs.
• --validate-only flag for CI pipelines and agent pre-checks.

​

Agent tooling

• pflow registry discover "fetch API data and send to Slack" returns matching nodes ranked by relevance.
• pflow registry run node-type param=value tests individual nodes outside of a workflow — output is pre-filtered for agents, showing structure without data.
• pflow instructions usage gives agents a complete guide to pflow’s commands and patterns.
• Allow/deny filtering via pflow settings to control which nodes are available.

# Agent gets a task from the user
# Step 1: Check if a workflow already exists
pflow workflow discover "analyze git commits and post to slack"

# Step 2: No match — find building blocks
pflow registry discover "git log, LLM classification, slack message"

# Step 3: Check a node's output structure
pflow registry run mcp-composio-slack-SLACK_SEND_MESSAGE \
  channel="test" markdown_text="hello"

# Step 4: Build the workflow using discovered nodes

​

MCP server improvements

• Environment variables expanded in all MCP config fields, not just API keys.
• Smart sync skips re-scanning when server configs haven’t changed (~500ms saved on warm starts).
• HTTP transport support for remote MCP servers alongside stdio.
• Better error messages when MCP servers fail to start or authenticate.

​

Workflow engine

### fetch-users

Get active users from the API.

- type: http
- url: https://api.example.com/users?status=active

### filter-active

Keep only users who logged in this month.

- type: code
- inputs:
    users: ${fetch-users.response.data}

```python code
users: list

result: list = [u for u in users if u['last_login_days'] < 30]
```

### summarize

Summarize the filtered users for the weekly report.

- type: llm

```prompt
Summarize these ${filter-active.result} active users for a weekly report.
```

• Run from file path (pflow workflow.pflow.md) or by name (pflow my-workflow).
• Templates reach into nested objects and arrays — ${node.result.data.users[0].email}.
• Execution traces saved to ~/.pflow/debug/ with per-node inputs, outputs, and timing.
• Pipe workflows together: pflow -p workflow-a | pflow -p workflow-b.

​

Built-in nodes

• shell — run commands with dangerous-pattern blocking and timeouts.
• code — inline Python with native object passing (no serialization overhead).
• llm — any model via Simon Willison’s llm library, with token tracking.
• http — all methods, auth, request bodies, automatic JSON parsing.
• file — read, write, copy, move, delete.
• mcp — bridge to any MCP server over stdio or HTTP transport.
• claude-code — delegate agentic subtasks to Claude Code.
• git / github — common operations without shell scripting.

​

MCP server

• 11 tools covering workflow execution, node discovery, and registry inspection.
• Structure-only output mode — agents see schema types without actual data, keeping context windows small.
• Works alongside CLI usage. Same workflows, same registry, different interface.

uv tool install pflow-cli

pflow settings set-env ANTHROPIC_API_KEY "sk-ant-..."

pflow workflow.pflow.md