SISO Institute

What Is SISO?

SISO is a virtual machine built on a simple idea: data enters a stream, flows through gates, and comes out transformed. Each gate is a pure function that matches events and emits new ones. That's the entire computational model.

The trusted base is ~190 lines of JavaScript. It defines three things:

⟐

Store

Content-addressed, append-only. Objects go in, hashes come out. Nothing is ever modified or deleted.

→

Refs

Named pointers to hashes. The only mutable structure. Think of them as the file system.

⚡

Stream

Routes events through gates in order. First match wins. Output re-enters from the top.

Everything else — Git, SQL, a wiki, a project board — is built as gates on this base. Same three mutation types: STORE_PUT, REF_SET, REF_DELETE. No exceptions.

How Gates Work

A gate has two methods:

gate anatomy
class MyGate extends SISO.Gate {
    matches(event) {
        // Return true if this gate handles the event
        return event.data.startsWith("greet:");
    }
    transform(event, stream) {
        // Process the event and emit the result
        const name = event.data.split(":")[1];
        stream.emit(new SISO.Event("Hello, " + name, stream.getId()));
    }
}

Gates are registered in order. When an event enters the stream, each gate is tried in sequence. The first gate that matches handles it. The output re-enters the stream from gate 0 — so gates can chain naturally.

This means gate order is priority. It means a gate that matches its own output will loop. It means you build complex systems by composing small, focused gates that each do one thing.

What's Been Built on SISO

Git

Full version control — init, add, commit, branch, checkout, merge, diff, log. Trees, blobs, and commits are objects in the store. Branch refs are just refs. Same three mutations.

SQL Database

CREATE TABLE, INSERT, SELECT with WHERE/ORDER BY/LIMIT, UPDATE, DELETE, DROP. Schemas are objects. Rows are objects. Table pointers are refs.

Wiki

Create, edit, read, delete pages. Automatic [[wikilink]] parsing and backlink tracking. A crosstalk gate syncs .md files from Git commits into wiki pages.

Project Board

Task CRUD with status tracking and assignment. A crosstalk gate auto-completes tasks when commit messages reference #id. No coupling to Git — just event matching.

These systems share one store, one set of refs, and one stream. They compose through events — a Git commit emits an event, and the board and wiki gates pick it up independently. Register the crosstalk gate and it works. Unregister it and it stops. The VM doesn't notice either way.

The Institute

This site is built to help you learn SISO, build with it, and collaborate with Claude to create projects.

Learn

Seven interactive lessons. Start with how streams work, build up to sub-streams and capstone projects. Hands-on from the first minute.

Build

Visual workbench with a code editor, stream visualization, test runner, and HTML export. Write gates, see them fire, ship the result.

Gallery

Working examples you can try, read, and open in the Workbench. Unit converters, calculators, text processors, validators, and more.

Collaborating with Claude

SISO projects are designed to be built with AI assistance. The key: give Claude the right context.

The File Set

Every time you ask Claude to build a SISO project, upload three files:

File	What It Does	Without It
siso.js	The actual framework API — `SISO.Gate`, `SISO.Stream`, `SISO.Event`	Claude invents a fake API that doesn't exist
SISO-SKILL.md	Patterns, rules, gate ordering, safety gates, sub-streams	Claude ignores safety patterns, gets gate order wrong
your-spec.md	What you want built — behaviors, inputs, outputs, edge cases	Claude guesses everything — mediocre results

All three files, every time. This is the single biggest factor in getting good results.

Writing a Good Spec

Make me a converter

No inputs. No behaviors. No constraints. Claude guesses everything.

# SISO Unit Converter ## Behaviors - km:10 → 10000 (km to meters) - mi:1 → 1.609344 (miles to km) - f:32 → 0 (fahrenheit to celsius) ## Edge Cases - Non-numeric input: show error - Negative numbers: handle correctly

Concrete behaviors. Clear inputs and outputs. Claude builds this correctly first try.

Spec Template

# [Project Name] ## Attached Files - `siso.js` — The SISO framework - `SISO-SKILL.md` — Development guide ## What It Does [1-2 sentence description] ## Behaviors - `input format` → `expected output` (description) ## Requirements - Output: single standalone HTML file - Embed SISO framework inline (with GPL v3 header preserved) - Works completely offline (no external dependencies) - Include GPL v3 license header ## UI - Title: "[Project Name]" - [Input mechanism] - [Output display] - [Design direction] ## Edge Cases - [Invalid input behavior] - [Boundary conditions]

The Iteration Loop

Upload — siso.js + SISO-SKILL.md + your spec.
Review — Does it use SISO correctly? Correct gate structure?
Targeted feedback — "The KmGate matches too broadly" beats "it doesn't work".
Know when to intervene — Sometimes it's faster to edit the gate yourself in the Workbench.

Good Iteration

You

[uploads siso.js, SISO-SKILL.md, spec] Build this unit converter.

Claude

Here's your converter. [provides HTML file]

You

The FahrenheitGate matches bare numbers like "32" — it should only match "f:32". The pattern is too broad.

✓ Specific: names the gate, describes the problem, gives an example.

Generate Spec (Reverse Flow)

Already built something in the Workbench? Use the "Generate Spec" button to create a spec from your existing project — useful for sharing, extending, or learning what a good spec looks like.