A language for systems that evolve through time

Docs · Getting started · Galleries · Vision · Discord · Contributing

Flow is a statically typed, compiled systems language built around one idea: you describe how a system evolves through time, and that description is the program. The production path is the self-hosted flowc compiler with a portable C backend. Algebraic effects, dynamics and control DSLs, verification, advanced stdlib domains, and alternate backends ship as explicitly Experimental surfaces until they are promoted.

Version	2.0.0
Install	brew tap flooooooooooow/flow && brew install flow
License	Proprietary from 2.0.0; MIT through 1.0.2
Cite	CITATION.cff

The compatibility promise is defined in STABILITY.md. Linux x86-64 and macOS arm64 are the Tier-1 platforms; every published release is qualified from the exact tag before GitHub Release publication.

Quickstart

The default production path is the self-hosted flowc compiler targeting portable C.

function main() -> i32 {
    println("Hello, Flow!")
    return 0
}

flow run hello.flow

Full quickstart covers variables, functions, structs, loops, and a complete flow evolution model.

---

Why Flow

Most languages are built around computation: sequences of instructions that transform inputs to outputs.

Flow is built around evolution. You describe how a system changes through time. That description is what runs.

An engineer working on a physical system today crosses Python for analysis, MATLAB for controller design, Simulink for block diagrams, C/C++ for deployment, Verilog for hardware, and vendor tools for the rest. Every handoff loses information. The mathematical model drifts from the deployed code.

Flow collapses those boundaries. The model is the program. The compiler understands units, sample rates, timing contracts, memory topology, and numeric precision as part of the type system, and emits portable C by default.

flow Pendulum {
    state angle: f64 = 0.5
    state velocity: f64 = 0.0
    param damping: f64 = 0.3

    angle evolves as velocity
    velocity evolves as -9.81 * sin(angle) - damping * velocity
}

That is a complete program. The compiler hands the right-hand side to an RK4 solver and runs it at native speed. No notebook, no glue code, no translation step between model and deployment.

Full thesis: VISION.md. Vision mapped onto grammar: docs/vision/north-star.md. Phase sequencing: ROADMAP.md.

---

What you get

• A Stable systems-language core with a self-hosted flowc compiler and portable C backend.
• Dynamical systems, controllers, algebraic effects, autodiff, graphics and domain libraries available as shipped Experimental surfaces with explicit promotion boundaries.
• C backend by default with no LLVM requirement; MLIR/JIT, CUDA and other specialised targets remain Experimental in 1.0.
• Games, morphogenesis, neurodynamics, and real-time DSP as ordinary examples under examples/.

---

Installation

Homebrew

brew tap flooooooooooow/flow
brew install flow
flow version
flow run examples/basics/hello_world.flow

Track main with brew install --HEAD flow. Formula: packaging/homebrew.

From source

git clone https://github.com/flooooooooooow/flow.git
cd flow
./flow run examples/basics/hello_world.flow

The production compiler path requires a conforming C11 toolchain. Python 3.9+ is retained for the reference/bootstrap compiler and development tooling, not as the canonical 1.0 execution host.

Optional: ./flow install puts flow on your PATH (~/.local/bin).

Longer walkthrough: Getting started.

New to programming: Start here goes from an empty terminal to a running simulation, and sets up an AI assistant to write Flow with you.

Working with an AI assistant

Flow is not in any model's training data, so an assistant does much better with the current facts in front of it. Two things help:

• Working with AI on Flow, the operating handbook.
• flow-skills, a pack of skills, references, and command-line tools. ./install.sh and your assistant knows the syntax, the compiler hosts, and how to verify its own work.

---

Examples

Each GIF is a recording of the compiled program. Frames come from the real gfx backend.

Games
Snake	Asteroids	Breakout
Flappy	Invaders	Pong
Morphogenesis
Gray-Scott	Turing spots	Diffusion-limited aggregation
L-system tree	Slime mold	Sandpile
Neurons and networks
Hodgkin-Huxley	Izhikevich zoo	Balanced network
Evolutionary biology
Lotka-Volterra	Wright-Fisher	Red Queen
Spatial SIR	Hawk-Dove	Rock-paper-scissors
Planet
Biomes	Tectonics	Erosion
Procedural generation
Wavefunction dungeon	Voronoi sites	Heightmap fBm
3D
Voxel world	FPS camera	Physics 3D
Numerical and social
Adaptive FMM	Voter model	Majority rule

./flow gfx examples/games/tetris_gfx.flow
./flow gfx examples/evolution/lorenz_gfx.flow
./flow run examples/ml/models/mlp_xor.flow
./flow gfx examples/morphogenesis/gray_scott.flow
./flow gfx examples/neuro/hodgkin_huxley.flow
./flow gfx examples/evoleco/lotka_volterra_gfx.flow
./flow gfx examples/planet/planet_biomes.flow
./flow gfx examples/procgen/wfc_dungeon.flow
./flow gfx examples/threed/voxel_world.flow

Domain	Gallery	Index
Games (24)	demos	examples/games
Morphogenesis	demos	examples/morphogenesis
Neurons and networks	demos	examples/neuro
Evolutionary biology	demos	examples/evoleco
AI / ML training	tutorials	examples/ai, examples/ml

Entrypoints by domain: examples/README.md.

---

Language at a glance

Core syntax

let x: i32 = 42              # Immutable
let mut counter: i32 = 0     # Mutable

function add(a: i32, b: i32) -> i32 {
    return a + b
}

struct Point { x: f32, y: f32 }

if x > 0 { ... } elif x < 0 { ... } else { ... }
while condition { ... }
for i in 0 to 10 { ... }

Types

Primitives:  i32, i64, f32, f64, bool, string, void
Pointers:    ptr<T>, ptr<void>
Arrays:      array<T, N>
Generics:    function identity<T>(x: T) -> T

Algebraic effects

effect Logger {
    log(msg: string) -> void
}

capability ConsoleLogger {
    effect Logger
    function log(msg: string) -> void {
        println(msg)
    }
}

Walkthrough: docs/effects-showcase.md · examples/effects/showcase.flow.

Automatic differentiation

Forward-mode dual numbers and reverse helpers live in the stdlib (lib/stdlib/autodiff.flow). The XOR tourist demo trains via checked-in grad codegen in examples/ml/models/mlp_xor.flow. Compiler-integrated loss.grad is still on the roadmap.

FFI

extern {
    function malloc(size: i64) -> ptr<void>
    function free(p: ptr<void>) -> void
}

---

Documentation

Resource	Description
Getting started	Install, first program, basics
Language overview	Features and design
Language design	Idioms and why Flow favors fluid abstraction
Language spec	Full reference
Effects showcase	Algebraic effects end to end
Examples index	Demos by domain
Examples status	Compile status of every example
Vision	Why Flow exists
Roadmap	Near-term work
Changelog	Version history
Self-hosting	Stage-A flowc in compiler/
Security · Conduct · Governance	Project policy

Site: flooooooooooow.github.io/flow

---

Project layout

Path	Contents
flow	CLI entry point
src/flow/	Python-host compiler (parser, type checker, C/MLIR/Metal backends)
compiler/	Self-hosted Stage-A flowc
lib/stdlib/	Standard library
runtime/	Native runtime (graphics, audio, recording)
examples/	Domain demos and verify corpus
tests/	Language and stdlib tests
apps/	Applications (flowdb, flow-http, …)
benchmarks/	Microbenchmarks and harness
docs/	Spec, tutorials, demos, project docs
third_party/integrations/vscode/	VS Code / Cursor extension
site/	Wiki shell and site assets

---

Self-hosting status

The self-hosted compiler (compiler/src/, written in Flow) is the default host for ./flow run and ./flow compile. It compiles itself end to end: three consecutive generation fixed-points are byte-identical, and a clean checkout needs no Python to build a working compiler.

Against the bootstrap language suite (tests/lang/, 90 .flow files) the self-hosted compiler passes 79. The remaining 11 cover features it does not yet implement: DSL keywords (effect, flow, state, evolves), generic monomorphization, overload resolution, closure snapshots, two stdlib codegen cases, and external C headers unavailable in the test environment. The full breakdown is in docs/project/self-hosting.md.

The Python-host compiler (src/flow/) remains the complete language surface: generics, effects, MLIR, GPU, DSLs, and all advanced type checking. The self-hosted compiler covers the subset needed to compile itself plus a growing set of language features. See compiler/README.md for the supported syntax list.

---

Build and develop

./flow run <file>              # Compile and run (default host: flowc)
./flow compile <file>          # Compile only → build/
FLOW_HOST=python ./flow run <file>   # Full Python-host language surface
./flow test                    # Test suite (strict by default)
./flow test --strict --tier2   # + transpile / clang compile checks
./flow fmt <file>              # Format
./flow repl                    # Interactive mode
./flow lsp                     # Language server
./flow gfx <file>              # Compile and run with graphics
./flow mlir <file>             # Emit MLIR (requires LLVM/MLIR tools)

Host switch: FLOW_HOST=flowc|python|auto (default flowc for run / compile).

# Fuzz the compiler
python3 tests/fuzz/run_fuzz.py --seconds 30

# Regenerate examples compile-status table
python3 scripts/verify_examples.py

Editor support

./scripts/publish_vscode_extension.sh --install
# Or: cursor --install-extension quilio.flow-language

Extension source: third_party/integrations/vscode/flow-language/.

Python wheels from Flow

./flow python mylib.flow --name mylib
pip install dist/mylib-*.whl

Details: docs/python-target.md.

Compiler pipeline

Flow source → Parser → AST → C / MLIR / Metal → Clang / LLVM / shaders

---

Project statistics

Counted from tracked files by CI so the numbers match the tree.

Metric	Files / modules	Physical lines
Tracked source	3,117	442,972
Flow language	2,089	226,359
Python compiler (src/flow)	73	51,614
Self-hosted compiler (compiler/src)	40	22,752
Standard library modules	111	33,350
Native runtime	44	8,035
Examples (excluding verify corpus)	426	112,671
Verify corpus	1,078	18,715
Tests (.py + .flow)	455	48,539
Application programs	8	1,537
Registry packages	19	—
Documentation pages	173	39,462

Tracked source by language

Language	Files	Physical lines
Flow	2,089	226,359
Python	376	114,884
HTML	214	38,604
C	97	23,485
C/C++ headers	49	11,017
C++	23	9,414
JavaScript	191	7,573
Shell	50	5,329
CSS	12	3,611
Objective-C	4	1,436
Objective-C++	2	654
Rust	10	606

Generated by CI from tracked files at 8cd159414c4a. Proof documents: 1,080. Raw JSON · Flow counter · Python fallback.

---

Contributing

Flow is built with humans directing design and agents writing a lot of the code. See CONTRIBUTING.md for decision authority and how to land changes.

Priorities: ROADMAP.md · docs/NEXT.md.

---

License

Version 2.0.0 and later are proprietary. All rights reserved. See LICENSE.

Version 1.0.2 and all earlier versions remain available under the MIT License. See LICENSE-1.x-MIT.

For licensing inquiries, contact abhishek.shivakumar@gmail.com.

---

Made with care by humans and AI · mascot: Flowy the Hedgehog