Colloq GitHub

v0.1 · research prototype · Apache 2.0

The conversation
is the computation.

Colloq starts with one typed conversation instead of a client program, a server program and a protocol file that drift apart. The compiler projects that conversation into one checked endpoint per role.

Start here Read the RFC
~/colloq 
$ colloq check examples/route.colloqconv.json
valid conversation example.route (2 roles, 11 states)

$ colloq compile examples/route.colloqconv.json
wrote build/route.colloqplan.json
conversation sha256:92c198d0…
plan         sha256:016d5975…

$ colloq run-plan build/route.colloqplan.json --transport quic --wire compact
✓ client and server report the same semantic trace

One source of truth

Write the agreement once.
Every server gets its half.

A conversation names the roles, the messages between them, the choices, the loops, the cancellation and the failures. The compiler derives a local state machine for each role, so two servers cannot disagree about the protocol.

route.colloq
conversation Route(request: Request) {
    roles gateway, router

    gateway -> router: request within 20ms

    choice router {
        cached { router -> gateway: CachedAnswer; end }
        infer  { router -> gateway: ModelAnswer;  end }
        review { router -> gateway: ReviewTicket; end }
    }
}

  • Typed choices, not guesses

    A branch label is part of the type. A role can only send a transition the plan declares, and the receiver checks it before it advances.

  • Failure is in the language

    A timeout or a reset is a declared transition to a declared state, not a generic exception that each service handles differently.

  • One identity across the cluster

    The conversation and the compiled plan are content addressed. Both peers exchange those identities before frame zero, and a mismatch stops there.

Transports

The meaning survives the wire.

The same plan runs over shared memory, TCP, authenticated QUIC and Iroh. Every transport reconstructs the same semantic trace, so a local run and a two-host run mean the same thing.

memory TCP QUIC (mTLS) Iroh (peer identity) reference wire compact wire

Extensions

The core needs no model.

Colloq is a language and a runtime. Nothing in it depends on a model. An optional binding lets a typed model pick the label at a choice state, with an explicit confidence threshold and a declared escalation branch. Remove it and the conversation still compiles, still runs and still checks. Read how the optional chooser works.

Measured, not claimed

Here is where Colloq loses.

A research language that only publishes its wins is marketing. These numbers come from the checked-in benchmark on an Apple M4, 500 iterations, three tokens.

1.51×slower than hand-written Rust, whole exchange
1.83 µscompact checked transition, median
51.6 µsplan compilation, once per plan
0.125 µsto start two sessions from a compiled plan

The compact wire is still JSON. The target of 1.25× is not met. There is no hosted product, no scheduler and no SLA. What exists is a checker, a compiler, a reference runtime over four transports, an Automerge draft gate and 76 tests.

Read the benchmark

Start with the two-node run.

Clone it, compile one conversation, then run the same plan across two processes with mutual authentication.

quickstart 
$ git clone https://github.com/Vantar-AI/colloq
$ cargo run -- check examples/generate.colloqconv.json
$ cargo run -- bootstrap-two-node --out build/two-node
Open on GitHub Two-node runbook