Changelog

​

LLM Key Propagation and Diagnostics

# Diagnostic output now includes sanitized provider details on failure
pflow workflow.pflow.md

• Fixed API key handling to ensure the validated key is reliably forwarded to LiteLLM during model invocations.
• Enhanced error handling to surface explicit provider error text in diagnostic failure outputs.

​

Updated Default Models

• Updated the Anthropic default from anthropic/claude-sonnet-4-5 to anthropic/claude-sonnet-5.
• Updated the Google default from gemini/gemini-3-flash-preview to gemini/gemini-3.5-flash-lite.
• Updated the OpenAI default from openai/gpt-5.2 to openai/gpt-5.6-luna.
• Updated the discovery and filtering fallback from Sonnet 4.5 to Sonnet 5.

​

Durable Workflow Resumption and Non-TTY Gates

# List all pending, unanswered paused gates across your execution traces
pflow resume list

# Continue a failed run or answer a paused gate by its token ID
pflow resume 7a9e4afb-2095-447e-8043-0660438104f9 --approve yes
pflow resume 7a9e4afb-2095-447e-8043-0660438104f9 --choose "deploy-production"

• Added the pflow resume CLI command to continue failed or interrupted runs (such as those halted by Ctrl+C or SIGKILL) from the failed node.
• Added durable pause state tracking that outputs a resume token and writes paused execution parameters cleanly to the trace file when a gate triggers in non-TTY environments.
• Implemented the pflow resume list sub-command to scan and display pending unanswered gates awaiting response.
• Added direct option mapping for the --choose parameter, converting numeric selections or label strings into structured gate resolutions inside the execution loader.
• Fixed attempt-chain tracking to prevent dead or interrupted runs from wedging resumption sequences when running pflow resume against a workflow path.
• Fixed candidate execution scans to ensure only attempts that successfully executed novel work supersede older resumable runs.

​

Unified Agent Nodes and AI-Assisted Development

### refactor-helpers
- type: agent
- backend: codex
- prompt: Modernize standard utility modules in src/core/
- sandbox: workspace-write
- approval_policy: never

• Introduced the unified agent node, allowing workflows to toggle between Claude and Codex behaviors using the backend: claude|codex parameter.
• Implemented strict parameter-shape checking inside schema_validation.py to enforce shared parameters and catch configuration anomalies before runtime.
• Improved the agent node to raise a structured PflowError for parameter validation issues, ensuring failed setups abort early during execution preparation.
• Added support for inspecting local workflow files inside pflow describe, letting developers review structural parameters without loading or generating execution history.

​

Interactive Web UI, Approval Bridges, and Voice Narration

# Direct the UI viewer to highlight a node and speak detailed instructions
pflow ui focus my-workflow.pflow.md extract-entities --say "We are analyzing this text block."

• Added the Web-UI Approval Bridge: rendering interactive Yes/No callout panels on paused nodes and Resume controls on failed nodes inside pflow ui.
• Added playback beacons (started, blocked, and ended events) that report real-time audio playback state from the browser back to the UI server.
• Added Agent Voice Narration, enabling workflows to synthesize voice messages via Gemini TTS using a custom [bracket] tag format.
• Implemented a closed-loop CLI pacing system (_await_narration_turn) that polls the UI server’s playback queues to align text narration with physical speech pacing.
• Added pflow settings llm set-tts-model and pflow settings llm set-tts-voice commands to configure global text-to-speech preferences.
• Added visual trace indicators to the UI selector, displaying the execution path lineage (⤷ resumed from <id>) under resumed attempts.

​

Windows Compatibility and Execution Robustness

# Local schema validation prevents invalid trace caching
type: object
properties:
  validated_output: { type: string }
required: [validated_output]

• Added Windows compatibility support, establishing Git Bash as the native POSIX shell emulator across win32 environments.
• Added Win32-specific pipe detection using Windows file-type handles to support UTF-8 CLI inputs in non-TTY terminals.
• Added automatic stdio stream re-encoding, forcing Windows consoles to communicate using byte-exact UTF-8 pathways.
• Fixed trace corruption at the LiteLLM integration boundary by deep-copying messages before sending requests to remote providers.
• Fixed local LLM schema validation, throwing immediate validation errors and following error-routing paths instead of caching invalid JSON outputs.
• Fixed MCP tool output guidance to expose declared nested paths under the canonical result.* namespace.
• Fixed transient Windows file locks while saving MCP server configuration by retrying atomic replacements.
• Fixed the MCP node to strip system sidecar tracking fields (_source_line and _prompt_source_line) from forwarded tool parameters.

### edit-utilities
- type: claude-code
- prompt: Fix the broken unit test.

### edit-utilities
- type: agent
- backend: claude
- prompt: Fix the broken unit test.

​

Interactive Web UI and Live Overlay

# Launch the web-based visualizer and server
pflow ui workflow.pflow.md

# Switch an active browser viewer to a specific execution run
pflow ui workflow.pflow.md --run 3a2c5e6

• Added the pflow ui command, introducing a web UI using React Flow and ELK layout engines.
• Added a live execution overlay that tails execution traces and lights up running, cached, successful, or failed nodes dynamically.
• Implemented an interactive execution launcher on the canvas with auto-generated input forms, past-run parameter pre-filling, and detached runner spawning.
• Added a stateful agent-to-browser interaction channel (“Point & Watch”) with CLI commands focus, frame, clear-focus, and user-activity.
• Added an output-node panel to inspect resolved inputs, outputs, costs, and token usages per node directly from live execution files.
• Fixed multi-tab browser connection limits by releasing connection pooling boundaries for Server-Sent Events (SSE).
• Improved UI server robustness with auto-reconnection filters and automatic viewer-tab reuse.
• Redesigned UI run selection by git-bucketing histories, grouping runs under local git repositories.

​

Declarative Stateful Loops and Human Approval Gates

### approve-release
- type: agent
- backend: claude
- prompt: Audit and approve the compiled changelog
- approval: required

### iterative-refinement
- type: workflow
- workflow: ./agent-turn.pflow.md
- loop:
    carry:
      history: ${iterative-refinement.result}
    until: ${iterative-refinement.done}
    max_iterations: 15

• Added human-in-the-loop approval gates via the approval: required modifier, pausing execution for interactive YES/NO confirmations.
• Added agent-raised escalation gates, allowing agent or code steps to pause execution using result.escalation blocks.
• Added the --auto-approve=<node-id> repeatable CLI flag and an equivalent MCP auto_approve execution option.
• Implemented the loop: node modifier with while: and until: conditions, backed by a robust engine-reentry compiler pattern.
• Added the carry: state-mapping block ({ input_key: ${loop-node.output} }) to thread outputs sequentially across loop iterations.
• Added support for settable node-level retry configurations with configurable max attempts, initial wait times, and linear/exponential backoff.
• Fixed empty-input batches to output a non-degrading advisory message rather than raising a false DEGRADED warning.
• Added a loop iteration indicator (⟳ badge) and self-edge representations to workflow visual layouts.

​

Streamable Traces and Content Interning

# Re-run a specific node using its frozen execution snapshot
pflow workflow.pflow.md --only extract-entities

• Rebuilt tracing as an incremental JSONL streaming transport, flushing execution events to disk line-by-line during runtime.
• Added content interning at the disk boundary, replacing the legacy blobs trailer with inline-first-occurrence blob keys.
• Shrink trace footprint by canonicalizing LLM prompts and systems, stripping redundant template resolutions and raw parameters.
• Added prewarm-batch prompt optimization, capturing shared prefixes as cache blocks to prevent duplicate prompt storage.
• Fixed the --only execution flag to restore a frozen snapshot of historical upstream inputs instead of re-firing side-effecting steps.
• Added support for reporting true input token counts and agent execution calls in output summaries.
• Added cache-aware API-equivalent cost estimates for Codex agent calls when workflows declare a LiteLLM-priced model.
• Added best-effort trace writing, allowing runs to execute safely even under disk-full or read-only filesystem environments.

​

LLM Control and Execution Refinements

- prompt: Process this data: ${read.content ?? "empty fallback"}
- prompt: Score threshold: ${assess.score ?? 0.8}

• Flipped memoization defaults: only llm nodes cache by default; all other node types require explicit - cache: true.
• Added support for JSON literals (string, number, boolean, null) inside ?? template coalesce operations.
• Improved the ?? operator to fall through on absent sub-fields and unexecuted branches without raising validation errors.
• Added self-healing schemas to agent outputs, enabling scalar type coercion and resume-retries on schema soft-failures.
• Added pre-execution validation for LLM model IDs, throwing validation errors before initiating live provider calls.
• Unified reasoning budget parameter mappings (reasoning_effort and reasoning_max_tokens) across LLM providers.
• Added support for shielding ${...} templates in flow-style YAML, preventing unquoted inline maps from parsing incorrectly.
• Fixed code-node type validations, allowing outputs of type list[T] to satisfy parameters expecting list[str].
• Added a redirection helper for CLI users typing pflow validate <wf> or pflow check <wf>, suggesting the correct --validate-only command.
• Added calendar validation for task scripts, rejecting impossible dates like leap-year boundary failures.

​

Declarative prompt caching and pflow analyze-cache

## Cache
- ttl: 5m

```cache [brief]
The project brief we are working from:
${brief}
```

### extract-features
- type: llm
- prompt_cache: [brief]
- prompt: Extract features from ${input.text}

# Analyze cache efficiency and get optimizations from a previous execution trace
pflow analyze-cache my-workflow.pflow.md --from-trace

• Added the top-level ## Cache markdown section to parse declarative, reusable prompt chunks.
• Added the prompt_cache and prewarm properties to LLM nodes to control cache inclusion and gate automatic batch-prefix caching.
• Implemented the pflow analyze-cache CLI command (and matching MCP tool) with Greenfield, Steady-state, Trace-driven, and Already-optimal analysis modes.
• Added a 22-entry warning catalog to flag cache misalignments, prompt shadow duplicates, and missing shared references.
• Implemented dynamic cache TTL translation for Gemini models (cachedContents) alongside Anthropic native controls.
• Added support for multi-breakpoint prompt caching for Anthropic models.
• Implemented synthetic cache warmup capabilities and detailed cost telemetry in trace formats.
• Fixed prewarm diagnostics to correctly account for declared prompt_cache chunks.

​

Native structured outputs for Claude Code

### audit-code
- type: agent
- backend: claude
- max_turns: 5
- prompt: Audit the security of the root directory.

```yaml output_schema
type: object
properties:
  vulnerabilities:
    type: array
    items:
      type: string
required: [vulnerabilities]
```

• Upgraded the Claude Code node to use ResultMessage.structured_output via the native SDK, requiring a minimum of claude-agent-sdk>=0.2.82.
• Added preflight and static validation to enforce that Claude Code output schemas define a top-level type: object.
• Added a strict constraint requiring max_turns >= 2 when an output schema is defined to allow planning and output turns.
• Implemented warning rehydration inside the persistent memoization cache, ensuring that cached soft-failures correctly replay as DEGRADED rather than passing as successful.
• Narrowed exception handling within Claude Code sessions to ProcessError to allow actionable SDK remediation messages (like installation and doctor checks) to bubble up.
• Aligned the Claude node’s output parsing by linking the “Outputs” parse-hint with the accepted source key, and stripped runtime-internal vocabulary from agent error messages.

​

LiteLLM integration and offline pricing

# Discover environment variables required for your configured LLM models
pflow settings llm providers

• Replaced the llm package with a lazy-imported LiteLLM wrapper, improving overall CLI startup performance.
• Added a typed exception hierarchy under LLMCallError to provide structured discriminators (UnknownModelError, MissingApiKeyError, LLMTransientError) for downstream retry and fallback routing.
• Redesigned tracing to use a shared["__trace_collector__"] save/restore context, fixing a thread-boundary bug where literal prompt captures were silently omitted.
• Added a deterministic offline pricing map for LiteLLM models to ensure accurate cost estimation when pricing metadata is missing from local snapshots.
• Added automatic bare model name prefixing (e.g., gpt-4o normalized to openai/gpt-4o) to ensure correct routing.
• Fixed a pricing bug where cost_usd was left unpopulated for newer LLM models released after our bundled LiteLLM snapshot.
• Upgraded the default LiteLLM engine version and fixed reasoning_effort mapping for Anthropic Claude 3 Opus.

​

CLI usability and parser refinement

• Added support for dotted paths inside CLI output destination flags (e.g. -o data.nested.field).
• Added walk-to-failure hints to the terminal output on workflow failures to assist agents in debugging sequence halts.
• Implemented a more compact summary representation for large batch node executions.
• Fixed linting for shell nodes without template inputs to offer both available cache resolutions in the warning text.
• Fixed the markdown parser to preserve blank lines inside multi-line YAML block scalars, preventing layout corruption of templates and prompts.

risk_level: str
issues: list

type: object
properties:
  risk_level:
    type: string
  issues:
    type: array
    items:
      type: string
required: [risk_level, issues]

​

Execution previews and planning

# Preview execution with cost and duration estimates
pflow workflow.pflow.md --dry-run

• Added the --dry-run flag to provide execution plans with historical cost ($USD) and duration estimates.
• Implemented recursive batch planning that aggregates child summaries into a single synthetic plan, correctly handling parallel vs. sequential durations.
• Added a cost_basis indicator (upper_bound vs exact) to dry-run summaries to help agents gate high-cost operations.
• Fixed dry-run recursion for batch sub-workflows to prevent false validation errors on ${item}-backed child inputs.

​

Modernized CLI and guidance

# Access topic-scoped guidance for agents or users
pflow guide llm code batch

• Flattened the CLI surface: pflow workflow <verb> and pflow registry <verb> are now top-level commands like pflow list, pflow describe, and pflow probe.
• Added pflow guide, a content delivery system that composes help topics based on requested scope or auto-detected workflow features.
• Improved non-interactive output routing: live progress now streams to stderr in real-time, while node data is routed strictly to stdout for clean piping to jq.
• Added an exception boundary to the MCP server via a FastMCP subclass to provide structured diagnostics to agents.
• Consolidated pflow trace report into the flattened pflow report command.
• Added confidence-based guidance and runnable command hints to the pflow find output.

​

Type safety and native diagnostics

• Refactored the type vocabulary to 7 canonical names: string, integer, number, boolean, array, object, and any.
• Upgraded the validator to produce Diagnostic objects natively, enabling numbered lists, fuzzy suggestions, and source-line tracking in all validation errors.
• Implemented a strict parent-to-child input boundary for sub-workflows that rejects undeclared inputs at both parse-time and runtime.
• Added validate-time type checking for Python code-node input and result/next annotations.
• Unified the ?? coalesce operator to correctly distinguish between nodes that were skipped and nodes that failed.
• Fixed workflow and template validators to short-circuit on structural errors, preventing cascades of redundant messages.

​

Rich Mermaid visualization

# Visualize data-flow and batch semantics in Mermaid format
pflow visualize my-workflow.pflow.md --descriptions

• Added support for “External IO” wrappers that render sub-workflow inputs and outputs as dashed subgraphs outside the primary pipeline.
• Added data-flow edges that trace the actual provenance of data through ${node.field} template references.
• Implemented the Mermaid procs shape (stacked rectangles) to visually communicate batch parallelism.
• Added --descriptions support to the visualizer to include node-level documentation in the rendered output.
• Improved layout logic to connect top-level inputs directly to their nearest consumer, preventing long-range edges from distorting the diagram.

​

Reliability and invariants

• Fixed the failed-node invariant: data from failed nodes now moves to shared["__failures__"] instead of leaking into shared[node_id], preventing downstream nodes from accidentally reading partial or failed results.
• Updated batch processing to exclude failed items from the results array, ensuring downstream nodes receive only successful data.
• Added protection against __dunder__ parameter names to prevent workflows from accidentally overwriting internal framework state.
• Implemented a _ProgressPartialLineFilter to prevent logger.warning messages from corrupting live progress lines.
• Added automatic node registry refreshing when source files change on disk.
• Fixed on-error recovery reporting to correctly reflect a DEGRADED status instead of a false SUCCESS.

​

Execution core and iteration speed

# Re-run a workflow, executing only 'target-node' and its dependencies
pflow my-workflow.pflow.md --only target-node

• Redesigned the execution core to compile sub-workflows once per batch, yielding a ~7x speedup for large parallel iterations.
• Added a persistent memoization cache system with --only and --no-cache CLI flags for precise, rapid iteration control.
• Added per-node cache opt-out support via the cache: false property.
• Fixed concurrent mutation issues in the workflow executor during compilation.
• Fixed an intermittent bug where zombie threads caused stream corruption (I/O operation on closed file) in Python code nodes.

​

Execution reports and traces

# Generate a directory of Markdown execution reports
pflow my-workflow.pflow.md --report-dir ./report/

• Added the --report flag to generate a directory of Markdown files detailing execution, including input/output token breakdowns and rendered templates.
• Upgraded trace format to 2.0.0: uses tree-structured events that correctly nest batch items and sub-workflows without truncating data.
• Added smart anomaly detection in reports to flag empty outputs (like dropped HTTP bodies) and provide template fix suggestions.
• Cross-cutting infrastructure keys and LLM costs now propagate correctly through deeply nested sub-workflows.
• Added LLM parameters (temperature, reasoning effort, system prompt) to node metadata in reports.
• Fixed cache invalidation for sub-workflow changes and eliminated phantom cost reporting in traces.

​

File references and workflow bundling

### analyze-code
- type: llm
- prompt: ./prompts/code-review.md

• Code-block parameters (prompt, code, command, batch, output_schema) can now reference external files. The system auto-detects paths, reads the files, and resolves templates inside them at compile time.
• pflow workflow save now packages workflows as folders containing the entry point and all referenced dependencies, preserving relative directory structures.
• Added per-item parameter overrides in batch nodes — each item can set its own model, reasoning_effort, or any other node parameter, so a single batch can mix providers or effort levels.
• Added the inputs parameter as template context for all node types, not just code nodes.
• Fixed relative path resolution so sub-workflow dependencies always resolve against the sub-workflow’s directory, not the current working directory.
• File references in sub-workflows are now fully resolved before validation.

​

Validation and diagnostics

# Visualize workflow structure using Mermaid
pflow visualize workflow.pflow.md --direction TD

• Added the pflow visualize command to generate Mermaid flowcharts of workflow topologies.
• Unified diagnostic rendering into a single, structured format with self-describing exceptions for both CLI text and JSON outputs.
• Added recursive sub-workflow validation at parse time to catch structural errors, unknown node types, and missing required inputs before execution.
• Added a 120-second default timeout to LLM nodes to prevent workflows from hanging indefinitely on stalled API calls.
• LLM nodes now catch JSONDecodeError when output_schema fails, preserving the raw text in the response and returning a soft error.
• Improved the markdown parser to detect orphaned content, duplicate section headings, and provide actionable errors for unquoted colons in YAML parameters.
• Fixed a bug where type annotations in Python code YAML inputs (e.g., text: str = ${ref}) were incorrectly parsed as literal values.
• Unified output auto-detection across CLI, JSON, and MCP interfaces.
• Added a CLI hint suggesting pflow mcp sync when a registry search returns no results but matching MCP servers exist.
• Fixed an issue where the registry cache would not refresh after a package upgrade.
• Fixed issues with template deduplication, double validation, raw string parsing in single-line YAML, and bash syntax correctness.
• Fixed missing error details in JSON output, dead code in error display paths, and redundant template resolution.

​

Under the hood

{
  "success": false,
  "is_error": true,
  "failed_node": "fetch"
}

{
  "success": false,
  "status": "failed",
  "error": "Execution failed",
  "errors": [{"message": "...", "category": "..."}]
}

​

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

### process
- type: workflow
- workflow: ./child.pflow.md
- text: ${source.text}
# Outputs are automatically mapped to ${process.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

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

### error-handler
- type: shell
- next: end # Explicit routing now required

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}

### input_name
- type: string
- stdin: true  # Routes pipe here

​

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

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

### use-data
- type: llm
# access nested fields directly:
# ${get-data.stdout.items[0].name}

​

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

### transform
# Must declare all inputs explicitly
- type: code
- inputs:
    data: ${fetch-data.response}

​

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.
• agent — delegate agentic subtasks to Claude Code or Codex.
• 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