{"slug": "flows-a-custom-markdown-runtime-for-visualizing-long-running-agent-loops", "title": "\"flows\": a custom Markdown runtime for visualizing long-running agent loops", "summary": "A developer released 'flows', a custom Markdown runtime that allows users to write, run, and visualize long-running agent loops within a single .md file. The tool combines prompt blocks for fuzzy tasks and code blocks for deterministic work, with explicit inputs, outputs, and loop control driven by code output. It aims to simplify agent workflow development by making the process markdown-native and visually debuggable.", "body_md": "Markdown-native agent workflows: write prompts, code blocks, inputs, outputs,\ngoals, and loops in one `.md`\n\nfile, then run or visualize the flow.\n\nInspired by [https://github.com/snarktank/ralph](https://github.com/snarktank/ralph).\n\n- Prompt blocks handle fuzzy work such as rewriting, review, planning, and summarizing.\n- Code blocks handle deterministic work such as parsing, tests, validation, and benchmarks.\n- Inputs and outputs are explicit, so later blocks only receive what the flow declares.\n- Loops are ordinary start rules, driven by code output such as\n`fast_enough`\n\nor`too_slow`\n\n. - Goal cards attach human-readable objectives and validation criteria to a single agent block.\n\n```\nmake build-go\n./flow validate examples/jax_short_goal_loop.md\n./flow chart examples/jax_short_goal_loop.md\n```\n\nRun the short JAX optimization demo:\n\n```\npython3 -m venv .venv\n.venv/bin/python -m pip install \"jax[cpu]\"\n\nFLOW_PYTHON_COMMAND=.venv/bin/python ./flow run examples/jax_short_goal_loop.md -f \\\n  --input code=@examples/inputs/slow_jax.py \\\n  --input target_ms=5\n```\n\nEach `##`\n\nheading is one block. The first fenced `yaml`\n\nblock configures inputs,\nstart conditions, executor, model, and routing. Prompt text or an executable\ncode fence supplies the block body.\n\n```\n## speed_optimizer\n\n``` yaml\ninputs:\n  code:\n    from: external\nstart:\n  - always: {max_runs: 1}\n  - when: benchmark\n    contains: too_slow\n    max_runs: 3\nprompt_executor: codex_cli\nmodel: gpt-5.3-codex-spark\n```\n\nRewrite the input code to reduce runtime. Return only the improved code.\n./flow validate <flow.md>\n./flow run <flow.md> -f --input name=value --input file=@path/to/file\n./flow chart <flow.md>\n./flow viz <flow.md>\n```\n\n", "url": "https://wpnews.pro/news/flows-a-custom-markdown-runtime-for-visualizing-long-running-agent-loops", "canonical_source": "https://github.com/samleeney/flows", "published_at": "2026-06-30 09:26:09+00:00", "updated_at": "2026-06-30 09:50:06.207094+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "generative-ai"], "entities": ["flows", "Markdown", "JAX", "GPT-5.3-codex-spark", "codex_cli"], "alternates": {"html": "https://wpnews.pro/news/flows-a-custom-markdown-runtime-for-visualizing-long-running-agent-loops", "markdown": "https://wpnews.pro/news/flows-a-custom-markdown-runtime-for-visualizing-long-running-agent-loops.md", "text": "https://wpnews.pro/news/flows-a-custom-markdown-runtime-for-visualizing-long-running-agent-loops.txt", "jsonld": "https://wpnews.pro/news/flows-a-custom-markdown-runtime-for-visualizing-long-running-agent-loops.jsonld"}}