# "flows": a custom Markdown runtime for visualizing long-running agent loops

> Source: <https://github.com/samleeney/flows>
> Published: 2026-06-30 09:26:09+00:00

Markdown-native agent workflows: write prompts, code blocks, inputs, outputs,
goals, and loops in one `.md`

file, then run or visualize the flow.

Inspired by [https://github.com/snarktank/ralph](https://github.com/snarktank/ralph).

- Prompt blocks handle fuzzy work such as rewriting, review, planning, and summarizing.
- Code blocks handle deterministic work such as parsing, tests, validation, and benchmarks.
- Inputs and outputs are explicit, so later blocks only receive what the flow declares.
- Loops are ordinary start rules, driven by code output such as
`fast_enough`

or`too_slow`

. - Goal cards attach human-readable objectives and validation criteria to a single agent block.

```
make build-go
./flow validate examples/jax_short_goal_loop.md
./flow chart examples/jax_short_goal_loop.md
```

Run the short JAX optimization demo:

```
python3 -m venv .venv
.venv/bin/python -m pip install "jax[cpu]"

FLOW_PYTHON_COMMAND=.venv/bin/python ./flow run examples/jax_short_goal_loop.md -f \
  --input code=@examples/inputs/slow_jax.py \
  --input target_ms=5
```

Each `##`

heading is one block. The first fenced `yaml`

block configures inputs,
start conditions, executor, model, and routing. Prompt text or an executable
code fence supplies the block body.

```
## speed_optimizer

``` yaml
inputs:
  code:
    from: external
start:
  - always: {max_runs: 1}
  - when: benchmark
    contains: too_slow
    max_runs: 3
prompt_executor: codex_cli
model: gpt-5.3-codex-spark
```

Rewrite the input code to reduce runtime. Return only the improved code.
./flow validate <flow.md>
./flow run <flow.md> -f --input name=value --input file=@path/to/file
./flow chart <flow.md>
./flow viz <flow.md>
```