██████╗ ██████╗ ██████╗ ███████╗
     ██╔══██╗██╔═══╝ ██╔══██╗██╔════╝
     ██████╔╝██║     ██║  ██║█████╗
     ██╔═══╝ ██║     ██║  ██║██╔══╝
     ██║     ╚██████╗██████╔╝███████╗
     ╚═╝      ╚═════╝╚═════╝ ╚══════╝

     Fluid Language Universal eXecution
  

A self-assembling, self-improving runtime that compiles markdown to bytecode.

pip install flux-runtime  ·  GitHub  ·  Playground

FLUX is a markdown-to-bytecode runtime designed for AI agents. You write structured markdown files containing polyglot code blocks — mixing C, Python, Rust, or any language line by line — and the FLUX compiler weaves them into a single optimized, verifiable bytecode that runs on a 64-register Micro-VM.

But that's the mechanics. Here's the idea:

FLUX-ese is what you get when you make a programming language that reads like a lawyer writes a contract. Every word is defined. Every operation is precise. Custom definitions are spelled out up front, like "for the purposes of this operation, 'depth' means sonar reading in fathoms corrected for tidal state." The language is natural but precise — like legalese is to lawyers, FLUX-ese is to agents.

The key insight: if a translator can turn any line of code in any language into a line of FLUX-ese, then you have a common language that's completely observable, understandable, and changeable by humans — both technical and non-technical. You don't need to read Python to know what the system does. You read the .ese file.

.-- FLUX-ese (.ese files) --.
|                           |
|  Like legalese for code.  |
|  Every word defined.      |
|  Every operation precise. |
|  Custom = up to you.      |
|  Markdown-readable.       |
|  Bytecode-executable.     |
|                           |
'-- Agents read fast.      --'
    Humans understand.      

Agents are the primary readers. They learn the symbols, scan for what matters, skip the commentary. But the commentary is there for the human who needs to understand what happened. Inline comments explain custom vocabulary — little reminders that a word or phrase has an entry in the project's encyclopedia of ground truth.

The .ese file format (pronounced "easy") is markdown with structured annotations:

• ** marks defined terms
• -- marks inline comments for human context
• == marks equivalence definitions ("for the purposes of this operation...")
• >> marks agent-jump markers (scan past this if you know the domain)

== For the purposes of this operation:
**depth** := sonar reading corrected for tidal state in fathoms
**safe** := depth > vessel_draft + 5 fathoms

>> Navigation sequence
check depth at current heading
if safe, maintain course
if not safe, compute alternate heading +-30 degrees
steer to safe heading

A lawyer uses best practices of legalese to build contracts and documentation. An agent uses best practices of FLUX-ese to build operations. Same principle: precision through shared vocabulary, not through syntax complexity.

pip install flux-runtime

flux hello                              # Run the hello world demo
flux compile examples/02_polyglot.md -o output.bin   # Compile FLUX.MD to bytecode
flux run output.bin                     # Execute in the VM

That's it. Three commands from zero to running bytecode.

┌─────────────────────────────────────────────────────────┐
│  TIER 8: SYNTHESIS — FluxSynthesizer (the DJ booth)    │
│  Wires ALL subsystems together                          │
├─────────────────────────────────────────────────────────┤
│  TIER 7: MODULES — 8-Level Fractal Hot-Reload          │
│  TRAIN → CARRIAGE → LUGGAGE → BAG → ... → CARD        │
├─────────────────────┬───────────────────────────────────┤
│  TIER 6A: ADAPTIVE  │  TIER 6B: EVOLUTION             │
│  Profiler + Selector│  Genome + Mutator + Validator     │
├─────────────────────┴───────────────────────────────────┤
│  TIER 5: TILES — 35 composable computation patterns    │
├─────────────────────────────────────────────────────────┤
│  TIER 4: AGENT RUNTIME — Trust, scheduling, resources  │
├─────────────────────────────────────────────────────────┤
│  TIER 3: A2A PROTOCOL — TELL, ASK, DELEGATE, BROADCAST│
├─────────────────────────────────────────────────────────┤
│  TIER 2: SUPPORT — Optimizer, JIT, Types, Stdlib, Sec  │
├─────────────────────────────────────────────────────────┤
│  TIER 1: CORE — FLUX.MD → FIR (SSA) → Bytecode → VM   │
└─────────────────────────────────────────────────────────┘

Zero external dependencies — runs on Python 3.10+ stdlib alone.

FLUX-ese is the natural-but-precise language layer. It sits on top of the bytecode VM the way legalese sits on top of contract law. The bytecode doesn't change — the vocabulary does.

Vocabulary files (.fluxvocab or .ese) define the words an agent knows:

## pattern: track origin of $data
## assembly: MOVI R0, ${data}; HALT
## description: OCDS origin tracking — every datum carries provenance
## result_reg: 0
## tags: ocds, provenance, paper-01

Higher-level vocabulary tiles into lower-level vocabulary:

• Level 0: compute 3 + 4 → 7
• Level 1: average of 10 and 20 → uses compute internally
• Level 2: is temperature normal → uses average + deadband + classify
• Level N: Each level arranges the previous level's words in more sophisticated ways

The same bytecode engine runs every level. The vocabulary just gets richer.

32 native bytecode instructions for agent-to-agent communication. Agents use TELL, ASK, DELEGATE, and BROADCAST opcodes to coordinate — with trust gating, capability-based routing, and binary serialization.

Write in any language, mix freely, compile to a single binary. C, Python, Rust, TypeScript — they all compile to the same FIR (SSA IR) intermediate representation, then to a unified bytecode.

Research papers become executable vocabulary. The PaperDecomposer reads a paper, extracts named concepts, and creates vocabulary entries:

Each concept is implemented as a working function in the PaperBridge. Ideas become operational.

Vocabulary compounds. Words build into bigger words:

Level 0: compute, factorial, square, sum, power  (primitives)
    ↓ tiles into
Level 1: average, percentage, triple, difference  (compositions)
    ↓ tiles into
Level 2: is-normal, classify, in-range            (domain concepts)
    ↓ tiles into
Level 3: safe-to-proceed, recommend, triage       (decisions)

Each level uses the previous level's words as building blocks. No new bytecode needed — just new arrangements of existing vocabulary.

FLUX is part of the Cocapn ecosystem — vessel intelligence systems for commercial fishing and beyond. The goal: a common-language-to-bytecode protocol that's completely observable, understandable, and changeable by humans — both technical and non-technical.

In the Cocapn vision:

• Oracle1 (this agent) is the lighthouse keeper for fleet nodes
• FLUX is the common language agents use to communicate instructions
• I2I (Iron-to-Iron) is the protocol — agents communicate through git commits, not conversation
• Captain's Log tracks agent growth and learning over time
• The Hermit Crab 🦀 is the logo — agents outgrow their hardware, move to bigger shells, bring their vocabulary and lessons with them

flux hello                              Run the hello world demo
flux compile <input> -o <output>        Compile source to FLUX bytecode
flux run <bytecode> [--cycles N]        Execute bytecode in the VM
flux test                               Run the full test suite (2037 tests)
flux version                            Print version info
flux demo                               Run the synthesis demo
flux info                               Show system architecture info
flux repl                               Open the FLUX REPL (hex bytecode)
flux debug <bytecode>                   Step-through debugger with breakpoints
flux disasm <bytecode>                  Disassemble bytecode to human-readable

Create .fluxvocab files to teach agents new words:

## pattern: steer heading $deg
## assembly: |
##   MOVI R0, ${deg}
##   MOVI R1, 360
##   IDIV R1, R0, R1
##   HALT
## description: Normalize heading to 0-359 range
## result_reg: 0
## tags: maritime, navigation

Or decompose any Python library into vocabulary:

from flux.open_interp.decomposer import Decomposer
d = Decomposer()
vocab = d.decompose_module("math")  # 53 patterns from Python's math module
vocab.save("vocabularies/custom/math.fluxvocab")

Agents compile their own domain-specific runtimes from vocabulary files:

from flux.open_interp.compiler import compile_interpreter
compile_interpreter("vocabularies/maritime/", "maritime_flux.py")
# Now any agent can: maritime_flux.run("steer heading 270")

The PaperDecomposer reads research papers and extracts executable concepts:

from flux.open_interp.paper_decomposer import PaperDecomposer
pd = PaperDecomposer()
vocab = pd.decompose_papers("/path/to/papers")  # 244 papers → 2979 concepts

244 research papers → 2,979 FLUX vocabulary concepts. Each concept becomes a word any agent can learn.

Working implementations in PaperBridge:

• Confidence Cascade: 3-zone confidence with deadband optimization
• OCDS Origin Tracking: S=(O,D,T,Φ) provenance tuples
• Tile Composition: compose(f,g) with confidence propagation
• Rate-Based Change: Anomaly detection via rate monitoring
• Emergence Detection: Collective > individual detection
• Structural Memory: Memory-as-structure constraint encoding

FLUX is now implemented in 11 languages, with vocabulary interpreters in 4:

FLUX integrates ideas from:

FLUX C VM is 4.7x faster than CPython for tight arithmetic. FLUX Zig VM is the fastest at 210ns/iter.

MIT