Flow
Contents · The Flow Book

Start here

The Flow Book1. Your first run2. Let the outside answer3. Keep the original answer

Build the decision

4. Give the program an input5. Name the work6. Give values a shape

Build the workflow

7. Decide what failure means8. Put the decision in its own file9. Put the pieces together

Go further

10. Work on several things11. Leave room for an answer12. Take Flow into an application

Build an application

13. Investigate a real question14. Challenge: diagnose and extend
Language reference ↗
The Flow Book / Go further

Take Flow into an application

The browser has been our host: it supplied sources, inputs, fixture replies and memory storage. A real application supplies those same responsibilities with implementations appropriate to its own environment.

Start with the boundary

Keep the program's Tool declaration small and meaningful. Decide what data the call accepts, what success returns and which failures the program should handle. The implementation behind it may call a service or perform some other operation, but that mechanism belongs to the host.

A model returning structured data is one example. Give the output a type, have the host obtain and decode a reply, and let the Flow program decide what to do with the typed outcome. Flow does not choose a provider or run the surrounding model loop for you.

Reproduce the practice program locally

Build the CLI from the repository with cargo build -p flow-cli. Ask target/debug/flow --help for its command inventory. Keep the example's complete files together, and check them with flow check main.flow before wiring in an implementation.

The tool-author guide walks through toolkits, descriptors and implementations. The runtime execution reference owns the precise CLI and embedding contracts. Use those for exact commands and protocol details rather than guessing a transport from a Tool's name.

Keep the application responsibilities visible

Credentials, permissions, approvals, retries and lifecycle management belong to the application. A typed call is not proof that an operation is authorized. A recorded reply is not system-wide telemetry. Keeping those boundaries clear lets the program stay small while the host enforces the policies it actually controls.

Choose your next experiment

For a small working starting point, try the repository's development workflow. It records one local effect, parks on a signoff call, and resumes in another CLI process. Its verifier checks success, typed failure and an uncertain outcome, then replays completed records without another effect. The Python host writes only its temporary fixture log; the browser's in-memory fixtures cannot perform that filesystem operation.

After building the CLI, run python3 examples/development-workflow/verify.py from the repository root. Read main.flow beside tools.flow, then inspect the verifier to see which responsibilities belong to the host. This is a local development exercise, not a service integration that needs credentials.

Take the complete workflow from chapter 9. Replace its fixture with one local implementation. Test success and failure. Retain a completed record and replay it with no dispatcher. Once that path is understandable, add one capability at a time: a richer reply, another call, a bounded batch or a wait.

Continue with Investigate a real question: a guided local research application with evidence gaps, rejected quotations and changed requirements. The Reference and pattern catalog are there for deeper questions as your own programs grow.

From a failed check to a checked delivery

For a real local exercise, use examples/checked-repair/README.md in the source repository. Its verifier needs the CLI and Python, creates its own temporary workspace, and requires no model or credentials. Run the successful case, then read the ambiguous-patch and stale-check cases in its receipt.

Follow these five observations: initial check, proposed patch, applied patch, recheck, and delivery. The receipt shows that a passing candidate was not rewritten. With two failures, every patch is prepared before the first one is applied. An ambiguous match prevents application; a final unchecked edit prevents delivery. These are application examples, not additional Flow semantics.

The CLI and agent interface both read the same recorded history. In the agent interface, request history, filter kind to Call, and follow page.nextOffset. Request a recorded source to see the module that produced the run. Source hashes refer to that recorded bundle, not whatever is currently open in your editor. The inspection marks omitted previews and unavailable sources explicitly.

A specialist engine can replace the small byte checker. Return its actual status and measurement domain through the Tool reply, and record the exact artifact revision checked. The host still owns dependencies, process execution, monitoring and delivery. Replay explains the orchestration; it does not rerun the engine or establish its scientific correctness.

Exact rules: CLI and MCP, Tool protocol.