Code

Agent commands. Your AI agent uses this node in workflows. You don’t configure it directly.

The code node runs Python in-process with direct access to input data as native objects. Use it when the logic is deterministic — filtering, reshaping, merging, computing values. If you can write a Python expression for it, there’s no reason to burn tokens on an LLM call.

Parameters

Parameter	Type	Required	Default	Description
`code`	str	Yes	-	Python code (or path to `.py` file, e.g., `./scripts/transform.py`) with type-annotated inputs and a `result` variable
`inputs`	dict	No	`{}`	Variable name to value mapping (template variables go here)
`timeout`	int	No	`30`	Maximum execution time in seconds
`requires`	list	No	`[]`	Package dependencies (documentation-only, not enforced)

Output

Key	Type	Description
`result`	any	Value of the `result` variable after execution
`stdout`	str	Captured `print()` output
`stderr`	str	Captured stderr output
`error`	str	Error message (only on failure)

stdout and stderr hold what your code prints, kept separate per batch item. Output from threads your code starts itself (threading.Thread, ThreadPoolExecutor, loop.run_in_executor) is not captured — it goes to pflow’s own streams — so return data from threads through result. Don’t wrap calls in contextlib.redirect_stdout to silence them: prints are already captured, and the redirect swaps the process-wide stream, which misroutes output when batch items run in parallel.

Type annotations

Every input variable and the result variable must have a type annotation. pflow uses these to validate inputs before your code runs — so a wrong type gets caught immediately with a fix suggestion, not as a cryptic Python error mid-workflow.

data: list            # required for every input
limit: int            # required for every input
result: dict = {}     # required on result too

Use Any when you don’t know or care what the input type is. pflow auto-injects Any, so you don’t need from typing import Any.

Supported types

Annotation	Python type	Notes
`int`	`int`
`float`	`int`, `float`	Integers are accepted where float is declared
`str`	`str`
`bool`	`bool`
`list`	`list`	Generic params like `list[dict]` check outer type only
`dict`	`dict`	Generic params like `dict[str, Any]` check outer type only
`set`	`set`
`tuple`	`tuple`
`bytes`	`bytes`
`Any`	—	Auto-injected. Skips type validation entirely

Only the outer type is checked — list[dict] validates that the value is a list, but doesn’t check whether the elements are dicts.

Template placement

Template variables go in inputs, never in the code block. The code block is plain Python: pflow never fills in ${var} there, and each inputs key becomes a Python variable. A ${var} in a string that names a value pflow knows about ("${name}".upper()) fails validation, and the message names the inputs binding to use.

### transform

Filter active users from the API response.

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

```python code
data: list

result: list = [u for u in data if u['active']]
```

Templates in the inputs dict get resolved before your code runs. By the time Python sees data, it’s already a native object — no parsing needed.

Bridge to workflow inputs

Workflow ## Inputs / ## Outputs use canonical names. Code blocks use Python annotations.

Workflow `type:`	Code annotation
`string`	`str`
`integer`	`int`
`number`	`int \| float` or `float`
`boolean`	`bool`
`array`	`list`
`object`	`dict`
`any`	`Any`

Inputs are native objects

Upstream JSON object and array text is parsed before your code runs. If the source node produced a JSON string, declare dict or list to get real Python objects — or str to get the text exactly as produced.

Upstream output	Declare as	You get
JSON string `'{"a": 1}'`	`dict`	`{"a": 1}`
JSON array `'[1, 2, 3]'`	`list`	`[1, 2, 3]`
JSON string `'{"a": 1}'`	`str`	`'{"a": 1}'`, unchanged
Plain text	`str`	The text string
Number	`int` or `float`	The number

A workflow input declared with a type other than any is never parsed: it arrives as its declared type. Binding a - type: string input to a dict or list annotation is a validation error — declare the input object or array instead.

Examples

Simple transformation

### filter-active

Filter users to only active accounts.

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

```python code
users: list

result: list = [u for u in users if u['status'] == 'active']
```

Multiple inputs

### merge-sources

Combine data from two upstream nodes.

- type: code
- inputs:
    api_data: ${fetch-api.response}
    db_records: ${query-db.result}

```python code
api_data: list
db_records: list

merged = api_data + db_records
result: dict = {
    'items': merged,
    'count': len(merged),
}
```

Access fields downstream: ${merge-sources.result.items}, ${merge-sources.result.count}.

No inputs

### generate-range

Generate a sequence with no external inputs.

- type: code

```python code
result: list = list(range(1, 11))
```

Using subprocess

### get-git-log

Fetch recent git history.

- type: code
- timeout: 60

```python code
import subprocess

output = subprocess.run(
    ['git', 'log', '--oneline', '-10'],
    capture_output=True, text=True, check=True
).stdout
result: str = output.strip()
```

Imports

Standard library imports work without restrictions — json, re, subprocess, pathlib, datetime. Third-party packages work too, but they need to be installed in pflow’s environment.

Installing third-party packages

pflow runs in an isolated environment, so pip install pandas won’t work. How you add packages depends on how you installed pflow:pipx (simpler — additive, doesn’t touch existing packages):

pipx inject pflow-cli pandas

uv tool (replaces the full environment — list existing extras first):

# Check what's already installed so you don't lose it
uv tool list --show-with

# Include ALL extras — both new and existing
uv tool install --with pandas --with llm-openrouter pflow-cli

uv tool install is not additive — it recreates pflow’s environment from scratch. If you previously installed with --with llm-openrouter and now run --with pandas alone, you’ll lose llm-openrouter. Always run uv tool list --show-with first and include all existing --with flags.

A simpler way to manage code node dependencies is coming in a future release.

### parse-dates

Parse and sort date strings.

- type: code
- inputs:
    raw_dates: ${fetch.response.dates}

```python code
from datetime import datetime

raw_dates: list

parsed = [datetime.fromisoformat(d) for d in raw_dates]
parsed.sort()
result: list = [d.isoformat() for d in parsed]
```

Security

Code runs directly in the pflow process via exec() without sandboxing. It has full access to your filesystem, network, and standard library — same as running a Python script yourself. Sandboxed execution is planned for a future release.

You’re in control. Your agent asks before running workflows, and you can open any .pflow.md file to see exactly what code will run. To disable this node entirely: pflow settings deny code.

External code file

For larger scripts, reference an external Python file. The file is read and used as the code block. Path is relative to the workflow file. Inside the file, __file__ is its absolute path, so Path(__file__).parent finds files next to it from any working directory. Relative paths in the code itself (open("data.json")) still resolve against the working directory. An if __name__ == "__main__": block in the file does not run — the file is a step body, not the program’s entry point.

### transform

Transform data using external script.

- type: code
- code: ./scripts/transform.py
- inputs:
    data: ${fetch.response}

Error handling

Errors include line numbers, the actual source line, and a suggestion for how to fix it. For example, a type mismatch looks like:

Input 'data' expects list but received dict

Suggestions:
  - Change the type annotation to: data: dict
  - Or convert the input value to list

Error	Cause	What you see
Missing annotation	Input or result has no type annotation	Which variable needs an annotation
Type mismatch	Input value doesn’t match declared type	Expected vs actual type, with fix suggestion
`NameError`	Undefined variable	Variable name, suggestion to add to inputs
`ImportError`	Module not installed	Module name, install command
Timeout	Code exceeded time limit	Current timeout, suggestion to increase
`SyntaxError`	Invalid Python	Line number from Python parser
Runtime error	Any other exception	Exception type, line number, source line
`sys.exit`	Code called `sys.exit` (any code, 0 included)	The exit call, line number, source line, and what the code printed to stderr — a step failure like any other, never pflow’s own exit code

By default the node doesn’t retry — code execution is deterministic, so retrying the same code produces the same result. A step’s retry: re-runs a body that raises or calls sys.exit.

CLI commands

Nodes

Configuration

Experimental

Parameters

Output

Type annotations

Template placement

Bridge to workflow inputs

Inputs are native objects

Examples

Simple transformation

Multiple inputs

No inputs

Using subprocess

Imports

Security

External code file

Error handling

​Parameters

​Output

​Type annotations

​Template placement

​Bridge to workflow inputs

​Inputs are native objects

​Examples

​Simple transformation

​Multiple inputs

​No inputs

​Using subprocess

​Imports

​Security

​External code file

​Error handling

Parameters

Output

Type annotations

Template placement

Bridge to workflow inputs

Inputs are native objects

Examples

Simple transformation

Multiple inputs

No inputs

Using subprocess

Imports

Security

External code file

Error handling